build-cognitive-context

name	build-cognitive-context
description	上下文工程——最大化 agent 输出质量。当开始新任务、上下文混乱或 agent 输出质量下降，或提到"上下文""context window""注意力"

Context — 上下文工程

入口/出口

• 入口: 开始新任务前、上下文窗口混杂、agent 输出质量下降、项目切换
• 出口: 干净正确的上下文 + 任务相关的全部必要信息
• 指向: 继续当前 build 流程
• 输出路径: 当前正在执行的 build 技能（如 build-workflow-execute）
• 前置加载: CANON.md

何时不使用

• 任务是一个明确、自包含的一行改动（白屏/空指针修复）
• 对话刚开始且问题描述极其精确

Iron Law

上下文质量是 agent 输出质量的最大杠杆。
更多上下文 ≠ 更好上下文。
上下文窗口大小 ≠ 注意力预算。

五级上下文层次

按优先级加载——上层优先，下层按需：

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: 对话历史
  先前讨论 / 中间决策 / 已排除方案
  → 引用结论，不复述全过程。定义"什么已决定"。

上下文打包策略

策略	方式	适用
Brain Dump	一次性加载全部相关文件	小项目（< 50 文件）、探索阶段
Selective Include	仅加载任务直接相关的文件	常规任务（默认）
Hierarchical Summary	分层摘要（架构→模块→文件）	大项目、跨模块重构

默认使用 Selective Include。 Brain Dump 浪费 tokens 和注意力。Hierarchical Summary 成本高。

混淆管理

当上下文互相冲突

STOP。不要在混淆中前进。

1. 识别冲突: "spec 说 X，但现有代码做的是 Y"
   ✅ 验证点: 冲突是否已明确写出到 human partner？
2. 明确选项: "选项 A: 按 spec 重构（需要 X 小时）。选项 B: 更新 spec（已和用户确认这是旧 spec）"
   ✅ 验证点: 两个选项是否包含时间/影响估算？
3. 呈现权衡: "选 A 意味着 XX。选 B 意味着 YY"
   ✅ 验证点: human partner 是否已做出明确选择？
4. 等待用户决定。不猜。

当需求不完整

不要默默假设填补空白。把缺口亮出来：

"需求说'让仪表盘更快'，但没指定：
1. 目标 LCP 是多少？（2.5s 是 Core Web Vitals 标准）
2. 什么网络条件？（4G？WiFi？）
3. 包括 SSR 时间吗？

我假设：目标 LCP < 2.5s（4G 网络），不包括 SSR。
→ 纠正我，否则我按这些继续。"

当有隐式知识

如果项目做了非标准约定但没记录 → 记录下来：

"我刚发现这个项目用 Prisma 而不是 TypeORM（虽然同类项目都用的 TypeORM）。
这不在 AGENTS.md 里。让我记下来避免下次混淆。"

然后将发现写入 AGENTS.md。

反模式

反模式	症状	修复
上下文饥饿	Agent 猜 API 行为、自己发明接口	加载相关源码或文档
上下文泛滥	加载了 20+ 个文件但只改了 1 个	精简到实际需要的文件
过期上下文	使用了已删除的函数/已废弃的 API	重新读取文件，不要依赖记忆
缺失示例	Agent 写的模式和项目已有一致代码不同	找到项目中的工作示例作为参考
隐式知识	项目约定没写在任何文档里	写到 AGENTS.md
静默混淆	Agent 发现不一致但没说	强制执行宪法第 8 条

常见说辞

说辞	现实	后果
"我已经看过这个文件了"	文件可能已变更。重新读关键部分。	基于 stale 上下文编码 → 引入 bug 或与已删除 API 冲突，平均浪费 30-60 分钟调试
"多加载总比漏加载好"	上下文泛滥稀释注意力。选择性加载目标信息更有效。	20+ 文件中只改 1 个 → 90%+ token 用于无关内容，关键细节被淹没，决策质量下降
"我知道这个库怎么用"	版本不同 API 不同。不信记忆信文档。	使用已废弃 API → 运行时崩溃或静默行为差异，单次返工 1-4 小时

验证失败处理

失败场景	处理方式
spec 未加载	停止任务，先加载当前 feature 的 01-spec.md 再继续
关键源码从记忆推断而非读取	强制重新读取相关文件，禁止使用"我记得"作为依据
spec 与代码冲突且未澄清	列出冲突点和两个选项，等待 human partner 决定后再继续
模糊需求未提请澄清	把缺口逐条列出并附默认假设，等 human partner 纠正或确认
非标准项目约定未记录	立即写入 AGENTS.md 并标注发现时间，避免下次混淆

好坏示例

✅ Good: 选择性加载 + 冲突显式化

任务: 修改 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: 全量加载 + 隐式假设

任务: 修改 TaskList 组件的筛选逻辑

加载策略: Brain Dump（读了 25 个文件）
→ 关键信息被淹没，注意力浪费在无关组件上

发现冲突: spec 和代码不一致，但默默选择"按代码改"。
→ 没有向 human partner 澄清，后续实现偏离 spec。

红旗 — STOP

• 在不检查现有代码的情况下开始实现
• 发现 spec 和代码冲突但默默继续
• 看到奇怪约定（"怎么这么写？"）但不问也不记录
• 一遍又一遍重读同一文件而不推进
• 用"这就是常规做法"而不是"项目实际用的是 X"

输出模板

上下文整理完成后，应产出以下结构（写入 checkpoint 或 task 起始注释）：

## Context Summary — [任务名称]

### 加载策略
- 策略类型: [Brain Dump / Selective Include / Hierarchical Summary]
- 已加载文件: [文件列表]
- 跳过文件及原因: [跳过列表]

### 已识别冲突
| # | 冲突描述 | 选项 A | 选项 B | 决定 |
|---|---------|--------|--------|------|
| 1 | ... | ... | ... | [待定 / 已决定] |

### 需澄清缺口
| # | 缺口描述 | 默认假设 | 确认状态 |
|---|---------|---------|---------|
| 1 | ... | ... | [待确认 / 已确认] |

### 新发现的项目约定
| # | 约定描述 | 写入位置 |
|---|---------|---------|
| 1 | ... | AGENTS.md |

验证清单

• 当前任务相关的 AGENTS.md/spec 已加载（运行时详细规则在 docs/contracts/ 按需读取）
• 关键源码文件已读取（非从记忆推断）
• 识别并解决了任何冲突（spec vs 代码）
• 模糊需求的不明确处已提请用户澄清
• 新发现的项目约定已写入 AGENTS.md