القائمة
上下文工程——最大化 agent 输出质量。当开始新任务、上下文混乱或 agent 输出质量下降，或提到"上下文""context window""注意力"
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| 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/ 按需读取）结构化脑暴——发散探索 + 收敛评估。当想法模糊、面临开放性问题或需要方案对比，或提到"脑暴""想法""方案对比""怎么办"
恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"
保存工作上下文。当需要保存当前工作状态供后续 session 恢复，或提到"保存""save""checkpoint""挂起"
架构决策记录（ADR）。当面临技术选型、架构决策、方案取舍需要记录，或提到"ADR""决策记录""为什么这样做"
发布或导出检查 → Go/No-Go → 归档。当审查通过后需要上线或交付最终产物，或提到"发布""上线""ship""Go/No-Go"
合并 PR → 等待 CI → 验证生产。当 PR 已创建需要合并到主分支并验证部署，或提到"合并""merge""PR""land"