Update global.md to define how memory bank should be updated
This commit is contained in:
Nikhil Mundra
parent
e061a2a678
commit
41917ff924
1 changed files with 87 additions and 25 deletions
112
latest/Global.md
112
latest/Global.md
|
|
@ -72,38 +72,100 @@ flowchart TD
|
|||
- **Session management** - Recognize when to start fresh vs. continuing in current context
|
||||
- **Learning from failures** - Document patterns that don't work to avoid repetition
|
||||
|
||||
## Documentation Update Requirements
|
||||
## Documentation Mandate: The "No Fact Left Behind" Protocol
|
||||
|
||||
**Memory Bank updates are MANDATORY** under the following conditions:
|
||||
**Core Principle**: The Memory Bank is the single source of truth. Information that is not in the Memory Bank is considered lost. Therefore, the documentation of every newly discovered fact, pattern, or decision is **non-negotiable and mandatory**.
|
||||
|
||||
1. **Discovering new project patterns** - Document in appropriate files
|
||||
2. **After implementing significant changes** - Update relevant context files
|
||||
3. **When user requests "update memory bank"** - Review and update ALL files
|
||||
4. **When context needs clarification** - Update relevant files for clarity
|
||||
5. **When task status changes** - Update currentTask.md immediately
|
||||
6. **When encountering conflicting information** - Resolve and update affected files
|
||||
7. **When any file approaches 300 lines** - Trigger splitting into logical sections
|
||||
### The Golden Rule of Documentation
|
||||
If you had to spend time figuring something out (a configuration detail, a library's quirk, an architectural pattern, a bug's root cause), you **MUST** document it immediately. This prevents future sessions from wasting time rediscovering the same information.
|
||||
|
||||
### Update Process Workflow
|
||||
### Detailed Core File Directives
|
||||
|
||||
```
|
||||
flowchart TD
|
||||
Start[Update Process]
|
||||
This section provides explicit instructions on what each core file contains and, most importantly, **when and why to update it**.
|
||||
|
||||
subgraph Process
|
||||
P1[Review ALL Files]
|
||||
P2[Identify Conflicts]
|
||||
P3[Document Current State]
|
||||
P4[Clarify Next Steps]
|
||||
P5[Document Insights & Patterns]
|
||||
P6[Update Task Status]
|
||||
P7[Update .clinerules]
|
||||
#### 1. `projectbrief.md`
|
||||
- **Purpose**: The high-level, stable vision for the project. What are we building and why?
|
||||
- **Update Frequency**: Rarely.
|
||||
- **Update Triggers**:
|
||||
- A fundamental shift in project goals (e.g., pivoting from a web app to a mobile app).
|
||||
- A major change in the core problem being solved.
|
||||
- Onboarding a new project that requires a fresh brief.
|
||||
|
||||
P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
|
||||
end
|
||||
#### 2. `productContext.md`
|
||||
- **Purpose**: Defines the "who" and "how" of the user experience. Who are the users? What problems are we solving for them? What are the key user journeys?
|
||||
- **Update Frequency**: Occasionally.
|
||||
- **Update Triggers**:
|
||||
- Introduction of a new major feature that alters the user experience.
|
||||
- A change in the target user audience.
|
||||
- Discovery of new user pain points that the project must address.
|
||||
|
||||
Start --> Process
|
||||
```
|
||||
#### 3. `techContext.md`
|
||||
- **Purpose**: A living document detailing the "what" and "how" of our technology stack. It's not just a list of technologies, but a guide to their specific usage within this project.
|
||||
- **Update Frequency**: Frequently. This file should be updated almost as often as code is written.
|
||||
- **Update Triggers**:
|
||||
- **Immediately upon discovering a new library/framework detail**: This is critical. If you learn something new about a library's API, its performance characteristics, or a common pitfall, it goes here.
|
||||
- **Adding a new dependency**: Document what it is, why it was added, and any configuration notes.
|
||||
- **Making a technology choice**: e.g., "We chose `gRPC` over `REST` for inter-service communication because..."
|
||||
- **Defining environment setup**: How to get the project running from scratch.
|
||||
- **Example Scenario (`Kubernetes Client-Go`)**:
|
||||
- **Initial Discovery**: You learn the project uses `client-go`. You add a section to `techContext.md`.
|
||||
```markdown
|
||||
## Kubernetes Client-Go
|
||||
- The project uses the official Go client for interacting with the Kubernetes API.
|
||||
- Primary package: `k8s.io/client-go`
|
||||
```
|
||||
- **Deeper Learning**: You discover that the project consistently uses dynamic clients and unstructured objects to handle Custom Resources (CRDs).
|
||||
```markdown
|
||||
### Dynamic Client Usage
|
||||
- **Pattern**: The controller heavily relies on the dynamic client (`dynamic.Interface`) for interacting with our CRDs. This is preferred over generated clientsets to keep the controller agile.
|
||||
- **Key Function**: `dynamic.NewForConfig(...)` is the standard entry point.
|
||||
- **Gotcha**: When working with `unstructured.Unstructured`, always use the helper functions from `k8s.io/apimachinery/pkg/apis/meta/v1/unstructured/unstructured.go` to avoid panics when accessing nested fields. Direct map access is an anti-pattern in this codebase.
|
||||
```
|
||||
- **Performance Tweak**: You find that watches on a particular resource are overwhelming the API server and implement a client-side rate limiter.
|
||||
```markdown
|
||||
### Informer Rate Limiting
|
||||
- **Problem**: Watches on the `FooResource` CRD were causing excessive API server load.
|
||||
- **Solution**: All informers for `FooResource` MUST be configured with a client-side rate limiter.
|
||||
- **Implementation**:
|
||||
```go
|
||||
// Example of required rate limiter
|
||||
factory.WithTweak(func(options *metav1.ListOptions) {
|
||||
options.Limit = 100
|
||||
})
|
||||
```
|
||||
```
|
||||
|
||||
#### 4. `systemPatterns.md`
|
||||
- **Purpose**: The blueprint for how we build things. This file documents the recurring architectural and coding patterns specific to this project. It answers: "What is the 'project way' of doing X?"
|
||||
- **Update Frequency**: Frequently.
|
||||
- **Update Triggers**:
|
||||
- **Discovering a new, recurring pattern**: If you see the same solution in two or more places, it's a pattern. Document it.
|
||||
- **Establishing a new pattern**: When you implement a new foundational solution (e.g., a new error handling strategy, a generic retry mechanism).
|
||||
- **Refactoring an existing pattern**: When a pattern is improved, document the change and the rationale.
|
||||
- **Example**:
|
||||
```markdown
|
||||
## Idempotent Kafka Consumers
|
||||
- **Pattern**: All Kafka consumers must be idempotent.
|
||||
- **Implementation**: Each message handler must first check a Redis cache using the message's unique ID. If the ID exists, the message is a duplicate and should be skipped. If not, the ID is written to Redis with a TTL before processing begins.
|
||||
- **Rationale**: Guarantees exactly-once processing semantics even if Kafka delivers a message multiple times.
|
||||
```
|
||||
|
||||
#### 5. `activeContext.md`
|
||||
- **Purpose**: A high-bandwidth, short-term memory file. It's a journal of the current work stream, capturing the "what's happening now" and "what I'm thinking."
|
||||
- **Update Frequency**: Constantly. This is the most frequently updated file during a task.
|
||||
- **Update Triggers**:
|
||||
- **Making a micro-decision**: "I'm choosing to use a channel here instead of a mutex because..."
|
||||
- **Encountering a roadblock**: "The build is failing due to dependency X. I need to investigate."
|
||||
- **Recording a temporary finding**: "The value of `foo` is `nil` at this point, which is unexpected. I need to trace why."
|
||||
- **Summarizing a conversation or feedback loop.**
|
||||
- **Lifecycle**: Information in `activeContext.md` is often ephemeral. Once a task is complete, valuable, long-term insights from `activeContext.md` should be migrated to `techContext.md` or `systemPatterns.md`, and the rest can be cleared for the next task.
|
||||
|
||||
#### 6. `progress.md` & `currentTask.md`
|
||||
- **Purpose**: Task and project management.
|
||||
- **Update Frequency**: At the start, during, and end of every task.
|
||||
- **Update Triggers**:
|
||||
- **`currentTask.md`**: Updated whenever a step in the implementation plan is started, blocked, or completed.
|
||||
- **`progress.md`**: Updated after a major feature is completed or a significant milestone is reached, summarizing the impact on the overall project.
|
||||
|
||||
## Task Management Guidelines
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue