메뉴
上下文工程——最大化 agent 输出质量。当开始新任务、上下文混乱或 agent 输出质量下降，或提到"上下文""context window""注意力"
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
结构化脑暴——发散探索 + 收敛评估。当想法模糊、面临开放性问题或需要方案对比，或提到"脑暴""想法""方案对比""怎么办"
恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"
保存工作上下文。当需要保存当前工作状态供后续 session 恢复，或提到"保存""save""checkpoint""挂起"
架构决策记录（ADR）。当面临技术选型、架构决策、方案取舍需要记录，或提到"ADR""决策记录""为什么这样做"
发布或导出检查 → Go/No-Go → 归档。当审查通过后需要上线或交付最终产物，或提到"发布""上线""ship""Go/No-Go"
合并 PR → 等待 CI → 验证生产。当 PR 已创建需要合并到主分支并验证部署，或提到"合并""merge""PR""land"
| name | build-cognitive-context |
| description | 上下文工程——最大化 agent 输出质量。当开始新任务、上下文混乱或 agent 输出质量下降，或提到"上下文""context window""注意力" |
build-workflow-execute）上下文质量是 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 并标注发现时间，避免下次混淆 |
任务: 修改 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 呈现两个选项，等待决定。
任务: 修改 TaskList 组件的筛选逻辑
加载策略: Brain Dump（读了 25 个文件）
→ 关键信息被淹没，注意力浪费在无关组件上
发现冲突: spec 和代码不一致，但默默选择"按代码改"。
→ 没有向 human partner 澄清，后续实现偏离 spec。
上下文整理完成后，应产出以下结构（写入 checkpoint 或 task 起始注释）：
## Context Summary — [任务名称]
### 加载策略
- 策略类型: [Brain Dump / Selective Include / Hierarchical Summary]
- 已加载文件: [文件列表]
- 跳过文件及原因: [跳过列表]
### 已识别冲突
| # | 冲突描述 | 选项 A | 选项 B | 决定 |
|---|---------|--------|--------|------|
| 1 | ... | ... | ... | [待定 / 已决定] |
### 需澄清缺口
| # | 缺口描述 | 默认假设 | 确认状态 |
|---|---------|---------|---------|
| 1 | ... | ... | [待确认 / 已确认] |
### 新发现的项目约定
| # | 约定描述 | 写入位置 |
|---|---------|---------|
| 1 | ... | AGENTS.md |
docs/contracts/ 按需读取）