SKILL.md
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