# Build Cognitive Context

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

- Skill: `zeroz-lab/build-cognitive-context` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zeroz-lab/build-cognitive-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeroz-lab/build-cognitive-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zeroz-lab (https://skillmd.com/u/zeroz-lab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zeroz-lab/build-cognitive-context

---


# 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 起始注释）：

```markdown
## Context Summary — [任务名称]

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

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

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

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

## 验证清单

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