Entry/Exit
- Entry: Before starting a new task, when the context window is mixed, when agent output quality degrades, when switching projects
- Exit: Clean and correct context + all necessary task-relevant information
- Points to: Continue the current build flow
- Output path: The build skill currently being executed (e.g.
build-workflow-execute) - Preload: CANON.md
When not to use
- The task is a clear, self-contained one-line change (white screen/null pointer fix)
- The conversation has just started and the problem description is extremely precise
Iron Law
上下文质量是 agent 输出质量的最大杠杆。
更多上下文 ≠ 更好上下文。
上下文窗口大小 ≠ 注意力预算。
Five-level context hierarchy
Load by priority — upper levels first, lower levels on demand:
Level 1: 规则文件
AGENTS.md / CANON.md / .cursorrules
→ 始终加载。定义全局行为和宪法纪律。
Level 2: 规格说明
docs/features/YYYYMMDD-<name>/01-spec.md / 02-design.md / 03-plan.md
→ 当前任务需要时加载。定义"做什么"。
Level 3: 源代码
相关文件 / 接口定义 / 类型声明
→ 仅在需要理解现有代码时加载。定义"怎么做"。
Level 4: 错误输出
测试失败日志 / 构建错误 / lint 警告
→ 仅在调试或验证时加载。定义"什么错了"。
Level 5: 对话历史
先前讨论 / 中间决策 / 已排除方案
→ 引用结论,不复述全过程。定义"什么已决定"。
Context packing strategies
| Strategy | Method | Applicable |
|---|---|---|
| Brain Dump | Load all relevant files at once | Small projects (< 50 files), exploration phase |
| Selective Include | Load only files directly relevant to the task | Regular tasks (default) |
| Hierarchical Summary | Hierarchical summary (architecture→module→file) | Large projects, cross-module refactoring |
Use Selective Include by default. Brain Dump wastes tokens and attention. Hierarchical Summary is costly.
Confusion management
When contexts conflict with each other
STOP。不要在混淆中前进。
1. 识别冲突: "spec 说 X,但现有代码做的是 Y"
✅ 验证点: 冲突是否已明确写出到 human partner?
2. 明确选项: "选项 A: 按 spec 重构(需要 X 小时)。选项 B: 更新 spec(已和用户确认这是旧 spec)"
✅ 验证点: 两个选项是否包含时间/影响估算?
3. 呈现权衡: "选 A 意味着 XX。选 B 意味着 YY"
✅ 验证点: human partner 是否已做出明确选择?
4. 等待用户决定。不猜。
When requirements are incomplete
Do not silently assume to fill in the gaps. Expose the gaps:
"需求说'让仪表盘更快',但没指定:
1. 目标 LCP 是多少?(2.5s 是 Core Web Vitals 标准)
2. 什么网络条件?(4G?WiFi?)
3. 包括 SSR 时间吗?
我假设:目标 LCP < 2.5s(4G 网络),不包括 SSR。
→ 纠正我,否则我按这些继续。"
When there is implicit knowledge
If the project follows non-standard conventions but they are not documented → document them:
"我刚发现这个项目用 Prisma 而不是 TypeORM(虽然同类项目都用的 TypeORM)。
这不在 AGENTS.md 里。让我记下来避免下次混淆。"
Then write the findings into AGENTS.md.
Anti-patterns
| Anti-pattern | Symptom | Fix |
|---|---|---|
| Context starvation | Agent guesses API behavior, invents interfaces on its own | Load relevant source code or documentation |
| Context flooding | 20+ files loaded but only 1 changed | Trim to the files actually needed |
| Stale context | Uses deleted functions/deprecated APIs | Re-read the files, do not rely on memory |
| Missing examples | The patterns the agent writes differ from existing consistent code in the project | Find a working example in the project as a reference |
| Implicit knowledge | Project conventions are not written in any documentation | Write them into AGENTS.md |
| Silent confusion | The agent finds an inconsistency but does not say so | Enforce Article 8 of the constitution |
Common excuses
| Excuse | Reality | Consequence |
|---|---|---|
| "I have already looked at this file" | The file may have changed. Re-read the key parts. | Coding based on stale context → introduces bugs or conflicts with deleted APIs, wasting an average of 30-60 minutes debugging |
| "Loading more is always better than loading less" | Context flooding dilutes attention. Selectively loading target information is more effective. | Only 1 change across 20+ files → 90%+ of tokens go to irrelevant content, key details get drowned out, and decision quality drops |
| "I know how to use this library" | Different versions have different APIs. Trust the documentation, not memory. | Using a deprecated API → runtime crash or silent behavior differences, 1-4 hours of rework per occurrence |
Validation Failure Handling
| Failure Scenario | Handling Method |
|---|---|
| spec not loaded | Stop the task and first load the current feature's 01-spec.md before continuing |
| Key source code inferred from memory rather than read | Force re-reading of the relevant files; using "I remember" as a basis is prohibited |
| spec and code conflict and no clarification has been made | List the conflict points and two options, and wait for the human partner to decide before continuing |
| Ambiguous requirement not raised for clarification | List the gaps one by one with default assumptions, and wait for the human partner to correct or confirm |
| Non-standard project convention not recorded | Immediately write to AGENTS.md and note the discovery time to avoid confusion next time |
Good and Bad Examples
✅ Good: Selective loading + make conflicts explicit
任务: 修改 TaskList 组件的筛选逻辑
加载策略: Selective Include
- Level 1: AGENTS.md(始终)
- Level 2: 01-spec.md(筛选逻辑规格)
- Level 3: TaskList.tsx / TaskList.test.tsx / filterUtils.ts(只这 3 个)
- Level 5: 上次讨论结论 "筛选应支持多条件组合"
发现冲突: spec 说"筛选条件互斥",但现有代码支持组合筛选。
→ 向 human partner 呈现两个选项,等待决定。
❌ Bad: Full loading + implicit assumptions
任务: 修改 TaskList 组件的筛选逻辑
加载策略: Brain Dump(读了 25 个文件)
→ 关键信息被淹没,注意力浪费在无关组件上
发现冲突: spec 和代码不一致,但默默选择"按代码改"。
→ 没有向 human partner 澄清,后续实现偏离 spec。
Red Flags — STOP
- Starting implementation without checking the existing code
- Discovering a conflict between spec and code but silently continuing
- Seeing a strange convention ("Why is it written like this?") but neither asking nor recording it
- Re-reading the same file over and over without making progress
- Using "this is the usual way" instead of "what the project actually uses is X"
Output Template
After context organization is complete, the following structure should be produced (written into a checkpoint or the task start comment):
## Context Summary — [任务名称]
### 加载策略
- 策略类型: [Brain Dump / Selective Include / Hierarchical Summary]
- 已加载文件: [文件列表]
- 跳过文件及原因: [跳过列表]
### 已识别冲突
| # | 冲突描述 | 选项 A | 选项 B | 决定 |
|---|---------|--------|--------|------|
| 1 | ... | ... | ... | [待定 / 已决定] |
### 需澄清缺口
| # | 缺口描述 | 默认假设 | 确认状态 |
|---|---------|---------|---------|
| 1 | ... | ... | [待确认 / 已确认] |
### 新发现的项目约定
| # | 约定描述 | 写入位置 |
|---|---------|---------|
| 1 | ... | AGENTS.md |
Validation Checklist
- The AGENTS.md/spec relevant to the current task has been loaded (detailed runtime rules are in
docs/contracts/, read on demand) - Key source code files have been read (not inferred from memory)
- Any conflicts (spec vs code) have been identified and resolved
- Unclear points in ambiguous requirements have been raised to the user for clarification
- Newly discovered project conventions have been written into AGENTS.md