@specpow/framework 0.5.11 → 0.5.13

package/builtin/skills/execution-subagent-dispatch/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: execution-subagent-dispatch
+description: 子代理派发技能。将 ai-caller.ts 的三种 prompt 模板（实现者、审查者、重审者）转化为宿主 Agent 可执行的指令。当需要派发子代理执行具体任务时使用。
+version: 1.0.0
+trigger: on-demand
+---
+
+# 子代理派发技能
+
+当需要派发子代理执行实现、审查或重审任务时，按以下模板构建指令。
+
+## 核心原则
+
+1. **文件即接口** — 告诉子代理去哪里读文件，不在 prompt 中粘贴大段内容
+2. **新鲜上下文** — 每个子代理只获得它需要的文件路径，不继承历史对话
+3. **输出到文件** — 所有结果写入指定文件，不通过对话返回
+
+---
+
+## 实现者子代理 Prompt 模板
+
+派发实现者时，给子代理的指令应包含以下部分：
+
+```markdown
+# 任务实现
+
+## 上下文
+你正在项目 {projectContext} 中工作。
+
+## 任务简报
+请阅读完整的任务简报文件: {briefPath}
+
+## 规范约束
+{specConstraints}
+（如无 spec，写"遵循项目现有代码风格和架构约定"）
+
+## 涉及文件
+{filesList}
+（如无指定文件，写"由你自行判断需要修改的文件"）
+
+## 铁律：测试驱动开发 (TDD)
+
+没有失败测试就不写产品代码！
+
+## 执行步骤 — RED-GREEN-REFACTOR
+
+### RED — 先写一个失败的测试
+1. 阅读任务简报，理解需求行为
+2. 为下一个要实现的 _行为_ 写一个测试
+3. 运行测试，确认它失败
+4. 失败原因必须是"功能还不存在"
+
+### GREEN — 写最少的代码让测试通过
+1. 写刚好够让测试通过的代码
+2. 不多写。YAGNI。
+3. 运行测试，确认全部通过
+
+### REFACTOR — 在测试保护下清理代码
+1. 消除重复，改善命名
+2. 运行测试，确认仍然全部通过
+
+重复 RED-GREEN-REFACTOR 直到任务完成。
+
+## 报告要求
+将详细的实现报告写入: {reportPath}
+
+报告格式（文本要点）：
+```
+报告格式：
+- 状态: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
+- 产生的 commit 列表（如果适用）
+- 测试摘要（RED 阶段写了哪些测试，GREEN 阶段全部通过）
+- 任何疑虑或未解决的问题
+```
+
+注意：`parseTaskReport` 同时接受上述文本格式和 JSON 格式。JSON 格式使用大写状态值：`"status": "DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED"`。
+```
+
+### 变量说明
+
+| 变量 | 来源 | 示例 |
+|------|------|------|
+| `{projectContext}` | 项目根目录名 | `specpow` |
+| `{briefPath}` | 任务简报路径 | `.specpow/sdd/{change}/task-{N}-brief.md` |
+| `{specConstraints}` | specs/ 目录中的规范内容 | 从 `specs/*.md` 读取 |
+| `{filesList}` | 任务涉及的文件列表 | 从任务描述中提取 |
+| `{reportPath}` | 实现报告输出路径 | `.specpow/sdd/{change}/task-{N}-report.md` |
+
+### Fix 轮次的实现者派发
+
+修复轮次复用相同的 prompt 模板，但：
+- **不修改 brief 文件** — 复用原始 brief，open findings 通过指令传递
+- **追加 open findings 列表** — 在 prompt 中列出需要修复的 findings
+- **reportPath 变更** — 写入 `task-{N}-report.md.fix-{R}`（不是覆盖原 report）
+- **模型升级** — 第 4-5 轮使用比当前高一级模型
+
+---
+
+## 审查者子代理 Prompt 模板
+
+派发审查者时，给子代理的指令应包含以下部分：
+
+```markdown
+# 代码审查 — 三阶段裁决
+
+## 任务上下文
+- 任务: {taskTitle}
+- 简报: {briefPath}
+
+## 审查包
+请阅读完整的审查包: {reviewPackagePath}
+
+## 审查流程
+
+### 第一阶段: 规格合规裁决
+对照任务简报，逐项检查：
+1. 所有需求项是否已实现
+2. 是否有超出规范的实现（scope creep）
+3. 接口签名是否与设计一致
+
+### 第二阶段: 代码质量裁决
+1. 命名和结构是否清晰
+2. 错误处理是否完整
+3. 是否有安全隐患
+4. 是否有性能问题
+
+### 第三阶段: TDD 合规裁决
+1. 是否有测试覆盖新增/修改的代码
+2. 测试是否断言行为而非实现细节
+3. 测试是否在代码之前编写（检查 commit 顺序或测试结构）
+4. 关键路径和边界条件是否有测试
+
+## 输出格式
+将审查结果写入文件: {reviewResultPath}
+
+```json
+{
+  "specCompliant": true/false,
+  "qualityApproved": true/false,
+  "findings": [
+    {
+      "id": "F-001",
+      "severity": "critical|important|minor",
+      "description": "...",
+      "file": "path/to/file",
+      "line": 42,
+      "isLoadBearing": true/false
+    }
+  ],
+  "cannotVerify": ["从 diff 无法验证的项目"]
+}
+```
+```
+
+### 变量说明
+
+| 变量 | 来源 | 示例 |
+|------|------|------|
+| `{taskTitle}` | 任务标题 | 从 brief 中读取 |
+| `{briefPath}` | 任务简报路径 | `.specpow/sdd/{change}/task-{N}-brief.md` |
+| `{reviewPackagePath}` | 审查包路径（diff） | `.specpow/sdd/{change}/review-package.md` |
+| `{reviewResultPath}` | 审查结果输出路径 | `.specpow/sdd/{change}/review-result.json` |
+
+### 审查要点
+
+- **不输出 `addressed` 字段** — 初始审查不判断 addressed，该字段由重审者填充
+- **cannotVerify** — 无法从 diff 验证的项目（如运行时行为、外部依赖）放在此数组中
+- **isLoadBearing** — 标记该 finding 是否为承重墙（阻塞性），非承重墙的 finding 可以 park
+
+---
+
+## 重审者子代理 Prompt 模板
+
+派发重审者时（修复循环中），给子代理的指令应包含以下部分：
+
+```markdown
+# 范围限定重新审查
+
+只审查修复 diff: {fixDiffPath}
+
+## 待验证的开放发现
+{openFindingsList}
+
+## 要求
+对每个发现做出裁决: ADDRESSED / NOT ADDRESSED
+新问题（仅限修复 diff 内的）标记为 NEW
+超出修复范围的观察 → 忽略（不记录）
+
+将结果写入: {reReviewResultPath}
+```
+
+### 变量说明
+
+| 变量 | 来源 | 示例 |
+|------|------|------|
+| `{fixDiffPath}` | 修复 diff 路径 | `.specpow/sdd/{change}/review-package.md`（复用审查包命名） |
+| `{openFindingsList}` | 开放 findings 列表 | 格式化后的 finding 列表（见下方） |
+| `{reReviewResultPath}` | 重审结果输出路径 | `.specpow/sdd/{change}/re-review-result.json` |
+
+### Open Findings 列表格式
+
+```
+  1. [critical] Description of finding 1 (src/foo.ts:42)
+  2. [important] Description of finding 2 (src/bar.ts)
+  3. [minor] Description of finding 3
+```
+
+### 重审要点
+
+- **只审查修复部分** — 不重新审查整个任务，只看 fix diff
+- **对每个 finding 裁决** — ADDRESSED 或 NOT ADDRESSED
+- **新问题限制范围** — 只有在 fix diff 内发现的新问题才标记为 NEW
+- **超出范围忽略** — 不在 fix 范围内的观察不记录
+
+---
+
+## 派发流程（宿主 Agent 操作）
+
+### 1. 实现者派发
+
+```bash
+# 1. 确保 brief 文件已写入
+# （由编排技能在步骤 2a 完成）
+
+# 2. 使用宿主原生 subagent 工具派发
+# Claude Code: Agent tool
+# Cursor: subagent tool
+# 其他: 参考宿主工具文档
+
+# 3. 子代理读取 brief → 实现 → 写 report
+
+# 4. 读取 report 文件，解析 JSON
+```
+
+### 2. 审查者派发
+
+```bash
+# 1. 生成审查包（diff）
+BASE_COMMIT={recorded base commit}
+HEAD_COMMIT=$(git rev-parse HEAD)
+git diff ${BASE_COMMIT}..${HEAD_COMMIT} > .specpow/sdd/{change}/review-package.md
+
+# 2. 使用宿主原生 subagent 工具派发审查者
+# Prompt: 审查者模板（见上方）
+
+# 3. 子代理读取 brief + review package → 审查 → 写 review-result.json
+
+# 4. 读取 review-result.json，解析 JSON
+```
+
+### 3. 重审者派发（修复循环中）
+
+```bash
+# 1. 生成修复 diff（复用 generateReviewPackage 命名模式）
+FIX_BASE=$(git rev-parse HEAD)
+# 实现者修复后...
+FIX_HEAD=$(git rev-parse HEAD)
+git diff ${FIX_BASE}..${FIX_HEAD} > .specpow/sdd/{change}/review-package.md
+
+# 2. 使用宿主原生 subagent 工具派发重审者
+# Prompt: 重审者模板（见上方）+ open findings 列表
+
+# 3. 子代理读取 fix diff → 对每个 finding 裁决 → 写 re-review-result.json
+
+# 4. 读取 re-review-result.json，解析 JSON
+```
+
+---
+
+## 模型选择指导
+
+根据任务复杂度选择子代理模型（如果宿主工具支持）：
+
+| 场景 | 条件 | 推荐级别 |
+|------|------|----------|
+| 机械实现 | ≤2 文件 + 完整 spec | cheap（默认 haiku） |
+| 集成实现 | 多文件协调 | standard（默认 sonnet） |
+| 架构设计 | 需要设计判断 | capable（默认 opus） |
+| 简单审查 | <100 行 diff | cheap（默认 haiku） |
+| 标准审查 | 一般变更 | standard（默认 sonnet） |
+| 复杂审查 | 复杂变更 | capable（默认 opus） |
+| 最终审查 | 全变更审查 | capable（默认 opus） |
+| 修复轮次 4-5 | 升级模型 | 比当前高一级 |
+
+**注意**：这只是指导。根据你实际可用的模型做出最佳选择。
+
+---
+
+## 关键原则
+
+1. **文件即接口** — 所有产物通过文件传递，不占用上下文
+2. **范围限定** — 重审者只审查修复部分，提高效率
+3. **铁律 TDD** — 实现者必须遵循 RED-GREEN-REFACTOR
+4. **三阶段审查** — 规格合规 → 代码质量 → TDD 合规
+5. **模型升级** — 修复轮次 4-5 升级模型，避免卡死

package/builtin/skills/execution-subagent-driven-dev/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: execution-subagent-driven-dev
+description: 子代理驱动开发(SDD)。通过分发新鲜子代理执行每个任务，每个任务后进行审查，最后进行全分支审查。来自 Superpowers 的核心执行引擎。
+---
+
+# 子代理驱动开发(SDD)
+
+通过为每个任务分发一个全新的实现者子代理来执行计划，每个任务后进行任务审查（规范合规 + 代码质量），最后进行全分支审查。
+
+**为什么用子代理：** 你将任务委托给具有隔离上下文的专门代理。通过精确构建它们的指令和上下文，你确保它们保持专注并成功完成任务。它们不应该继承你会话的上下文或历史 — 你构建它们需要的一切。这也保护了你自己的上下文用于协调工作。
+
+**核心原则：** 每任务新鲜子代理 + 任务审查（规范 + 质量）+ 宽泛最终审查 = 高质量、快速迭代
+
+## 何时使用
+
+- 有实现计划？
+- 任务大多独立？
+- 想在当前会话中完成？
+
+如果都是 yes → 使用此技能。
+
+## 流程
+
+### 设置
+
+1. 确保工作在隔离工作区中（使用 `git-worktrees` 技能）
+2. 解析工作区目录：`scripts/sdd-workspace PLAN_FILE`
+3. 检查账本（`<workspace>/progress.md`）
+4. 读取计划一次，为每个任务创建 todo
+5. 扫描计划中的冲突（任务间矛盾、与全局约束矛盾）
+
+### 任务循环
+
+对每个任务：
+
+#### 1. 分发实现者
+记录 BASE commit（`git rev-parse HEAD`）。
+- **任务简报：** 运行 `scripts/task-brief PLAN_FILE N`
+- **报告文件名：** 与简报同名（`task-N-report.md`）
+- **分发 prompt 包含：**
+  1. 一行项目背景
+  2. 简报路径（"先读这个"）
+  3. 来自前置任务的接口信息
+  4. 你对歧义的解读
+  5. 报告文件路径和报告契约
+
+**绝不**让子代理读取整个计划文件。
+**绝不**分发多个实现子代理并行（会冲突）。
+
+#### 2. 处理报告
+
+实现者报告四种状态之一：
+- **DONE:** 生成审查包，分发审查者
+- **DONE_WITH_CONCERNS:** 先读取疑虑，如果是正确性问题则先处理
+- **NEEDS_CONTEXT:** 提供缺失上下文，重新分发
+- **BLOCKED:** 评估阻塞原因，可能需要更强模型或拆分任务
+
+#### 3. 审查任务
+
+- 运行 `scripts/review-package PLAN_FILE BASE HEAD`
+- 分发任务审查子代理
+- 审查者输入：简报 + 报告 + 审查包 + 全局约束
+- 审查者输出：规范合规 ✓/✗ + 质量通过/不通过 + 发现列表
+
+**绝不跳过任务审查。实现者自审不能替代任务审查。**
+
+#### 4. 修复循环
+
+触发条件：规范 ❌、Critical/Important 发现、或确认有 ⚠️ 项。
+
+**Rounds 1-3 — 恢复原始实现者：**
+发送开放发现原文。它的上下文完整。
+
+**Rounds 4-5 — 分发全新实现者，使用更强模型：**
+"A prior implementer attempted this task N times; you own it now."
+
+每轮：
+1. 实现者修复 + 重新运行测试 + 追加修复报告
+2. 运行 `scripts/review-package PLAN_FILE FIX_BASE HEAD`
+3. 分发范围限定的重新审查
+4. 重新审查者裁定每个发现：ADDRESSED 或 NOT ADDRESSED
+5. 记录到账本
+
+#### 5. 断路器（5 轮后）
+停止分发。自己裁定每个开放发现：
+
+- **审查者误报/有争议：** 停放 → `Task N: parked — <finding> — ruling: <why>`
+- **真实但无下游依赖：** 停放，注明延迟
+- **真实且承重：** STOP。`Task N: BLOCKED — <reason>`。报告给用户。
+
+**只在顶部裁定。提前裁定是用不同名字预先判断。**
+
+#### 6. 完成任务
+
+审查干净后（或所有开放发现都已停放）：
+- 追加完成行到账本
+- 标记 todo 完成
+- 继续下一任务
+
+### 最终审查
+所有任务完成后：
+1. 运行 `scripts/review-package PLAN_FILE MERGE_BASE HEAD`
+2. 分发最终审查（使用最强模型）
+3. 如果有发现，分发一个修复子代理（不是每个发现一个）
+4. 然后一次范围限定的重新审查
+5. 裁定剩余发现
+
+### 完成
+
+1. 删除工作区（`rm -rf <workspace>`）
+2. 使用 `finish-branch` 技能
+
+## 模型选择
+
+| 任务类型 | 模型级别 |
+|----------|----------|
+| 机械实现（1-2文件，完整规范） | cheap |
+| 集成和判断（多文件协调） | standard |
+| 架构和设计 | capable |
+| 最终审查 | capable（总是） |
+| 修复轮次 4-5 | 至少比卡住的实现者高一级 |
+
+**总是显式指定模型。** 省略模型会继承会话模型（通常是最贵的）。
+
+## 上下文管理铁律
+- 所有产物通过文件传递
+- 分发 prompt 只包含当前任务所需
+- 不粘贴历史任务摘要
+- 审查包是文件，不在你的上下文中
+- 信任账本而非自己的记忆
+
+## 合理化防御表
+
+| 借口 | 现实 |
+|------|------|
+| "规范合规差不多就行了" | 审查者发现规范差异 = 没完成。修复或裁定。 |
+| "我自己修复，分发太麻烦" | 控制器修复污染你的上下文且跳过审查。 |
+| "再来一轮会收敛吧" | 过了顶部，轮次不会收敛。失败是结构性的。 |
+| "审查者反正会发现新东西" | 范围限定的重新审查验证修复；它们不会游荡。 |
+| "这个发现明显错了，我跳过吧" | 你只在顶部裁定，每个裁定都是账本条目。 |
+| "修复很小，跳过重新审查" | 未审查的修复是回归的方式。 |
+| "审查拖慢了循环" | 没有审查的循环只是未验证的折腾。 |
+| "账本记录是多余的" | 账本是压缩后存活的东西。 |

package/builtin/skills/execution-systematic-debugging/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: execution-systematic-debugging
+description: 系统化调试 4 阶段根因分析：调查→模式分析→假设测试→实现修复。来自 Superpowers。
+---
+
+# 系统化调试
+
+## 铁律
+
+```
+不要猜测。调查。
+```
+
+## 4 阶段流程
+
+### 阶段 1: 调查
+
+1. 复现问题
+2. 收集错误信息（日志、堆栈、截图）
+3. 确定影响范围
+4. 检查最近的变更（`git log --oneline -20`）
+
+### 阶段 2: 模式分析
+
+1. 错误信息中的关键词是什么？
+2. 这个错误模式在代码库中有先例吗？
+3. 最近有什么变更可能引入这个问题？
+4. 是回归还是新问题？
+
+### 阶段 3: 假设测试
+
+1. 形成假设："如果 X，那么 Y"
+2. 设计验证实验
+3. 运行实验
+4. 如果假设被否定，形成新假设
+
+### 阶段 4: 实现修复
+
+1. 修复根因，不是症状
+2. 写回归测试
+3. 验证修复
+4. 检查是否有类似问题
+
+## 根因追踪
+
+如果修复后问题再次出现，说明你没有找到根因。回到阶段 1。
+
+## 合理化防御表
+
+| 你可能的想法 | 现实 |
+|-------------|------|
+| "我猜是这个问题" | 猜测不是调试。验证。 |
+| "先修了再说" | 修症状不是修根因。 |
+| "没时间调查了" | 不调查就修 = 问题会回来。 |
+| "这个错误信息不重要" | 错误信息是线索。读它。 |
+| "肯定是最近改的" | 也可能是旧 bug 被新代码触发。 |
+| "我应该直接问同事" | 先自己调查 15 分钟再问。 |
+| "这个 bug 太复杂了" | 复杂 bug 也是简单问题的组合。分解它。 |
+| "重启一下就好了" | 重启掩盖问题，不解决问题。 |
+| "这个只在测试环境出现" | 测试环境暴露问题，不是制造问题。 |
+| "用户操作错误" | 用户操作是反馈，不是借口。 |
+| "这个优先级不高" | bug 不会因为你标记低优先级就停止影响用户。 |
+
+## 红旗清单
+
+以下 13 条危险信号出现时，立即 STOP：
+
+1. **"我猜是这个问题"** → 猜测不是调试。形成假设并验证。
+2. **"先修了再说"** → 修症状不是修根因。问题会回来。
+3. **"没时间调查了"** → 不调查就修 = 赌博。
+4. **"这个错误信息不重要"** → 错误信息是第一条线索。忽略它 = 盲人摸象。
+5. **"肯定是最近改的"** → 确认偏误。检查所有可能性。
+6. **"我加个日志看看"** → 日志是好的，但先读现有日志和堆栈。
+7. **"这个 bug 太复杂了"** → 复杂 bug 也是简单问题的组合。分解它。
+8. **"重启一下就好了"** → 重启掩盖问题。根因还在。
+9. **"这个只在测试环境出现"** → 测试环境暴露问题，不是制造问题。
+10. **"用户操作错误"** → 用户操作是反馈。系统应该能处理错误操作。
+11. **"这个优先级不高"** → bug 不会因为低优先级就停止影响用户。
+12. **"我之前遇到过类似的"** → 类似不等于相同。每次都要验证。
+13. **"应该是并发/时序问题"** → 不要跳到结论。先排除确定性 bug。
+
+## 压力测试
+
+在声称修复完成前，问自己：
+
+1. 如果输入是空的怎么办？
+2. 如果输入是 null/undefined 怎么办？
+3. 如果并发 1000 个请求怎么办？
+4. 如果网络断了怎么办？
+5. 如果磁盘满了怎么办？
+6. 如果数据库连接超时怎么办？
+7. 如果配置缺失怎么办？
+8. 如果依赖服务返回错误怎么办？
+9. 如果这个修复引入了新问题怎么办？回归测试覆盖了吗？
+10. 如果问题在另一个环境复现不了怎么办？

package/builtin/skills/execution-tdd/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: execution-tdd
+description: 测试驱动开发。严格的 RED-GREEN-REFACTOR 循环。铁律：没有失败测试就不写产品代码。
+---
+
+# 测试驱动开发(TDD)
+
+## 铁律
+
+```
+没有失败测试就不写产品代码。
+```
+
+## 循环
+
+### RED — 写一个失败的测试
+
+1. 写一个描述期望行为的测试
+2. 运行测试，确认它失败
+3. 测试失败的原因必须是"功能还不存在"
+
+### GREEN — 写最少的代码让测试通过
+
+1. 写刚好够让测试通过的代码
+2. 不多写。YAGNI。
+3. 运行测试，确认全部通过
+
+### REFACTOR — 清理代码
+
+1. 在测试保护下重构
+2. 消除重复
+3. 改善命名
+4. 运行测试，确认仍然全部通过
+
+## 合理化防御表
+
+| 你可能的想法 | 现实 |
+|-------------|------|
+| "这个改动太小不需要测试" | 小改动也会引入 bug。先写测试。 |
+| "测试会花太长时间" | 不测试会花更长时间调试。 |
+| "这个函数太简单了" | 简单函数也会有边界情况。 |
+| "我先实现再补测试" | 事后测试无法驱动设计。先测试。 |
+| "现有测试已经够了" | 新行为需要新测试。 |
+| "这个 edge case 不太可能发生" | 不可能发生的事总会发生。 |
+| "重构可以等一等" | 技术债会复利增长。 |
+| "文档可以后面再写" | 后面 = 永远不。现在写。 |
+| "性能优化不急" | 等用户抱怨就来不及了。 |
+| "这个 TODO 我记住了" | 你会忘的。写下来。 |
+| "其他模块更重要" | 每个模块都是最重要的。 |
+
+## 红旗
+
+这些想法意味着 STOP — 你正在合理化：
+
+| 想法 | 现实 |
+|------|------|
+| "我先写实现再补测试" | STOP。先写测试。 |
+| "这个不需要测试" | 如果它需要工作，它需要测试。 |
+| "测试太多了" | 代码太多了还差不多。 |
+| "这个 edge case 不重要" | 不重要的 edge case 经常是最重要的 bug。 |
+| "测试会让我变慢" | 没有测试会让你更慢。 |
+
+## 压力测试
+
+在声称完成前，问自己：
+
+1. 如果输入是空的怎么办？
+2. 如果输入是 null/undefined 怎么办？
+3. 如果并发 1000 个请求怎么办？
+4. 如果网络断了怎么办？
+5. 如果磁盘满了怎么办？
+6. 如果数据库连接超时怎么办？
+7. 如果用户输入包含特殊字符怎么办？
+8. 如果配置缺失怎么办？

package/builtin/skills/execution-verification-before-completion/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: execution-verification-before-completion
+description: 完成前验证。铁律：没有新鲜验证证据就不声称完成。防止代理说"应该可以了"。
+---
+
+# 完成前验证
+
+## 铁律
+
+```
+没有新鲜验证证据就不声称完成。
+```
+
+## 规则
+
+1. **运行测试** — 不是"应该通过"，是"确实通过"
+2. **检查构建** — 不是"应该能构建"，是"确实构建了"
+3. **验证行为** — 不是"逻辑上应该对"，是"实际运行对了"
+
+## 验证清单
+
+完成前必须确认：
+
+- [ ] 所有测试通过（`npm test` / `mvn test`）
+- [ ] 构建成功（`npm run build` / `mvn package`）
+- [ ] Lint 通过（无新增警告）
+- [ ] 手动验证关键路径（如果适用）
+- [ ] 没有遗留 TODO 或 FIXME
+
+## 合理化防御表
+
+| 你可能的想法 | 现实 |
+|-------------|------|
+| "应该可以了" | "应该"不是证据。运行测试。 |
+| "改动太小不需要验证" | 小改动也能破坏东西。验证。 |
+| "测试太慢了" | 不验证就声称完成更慢（返工）。 |
+| "我检查了代码逻辑" | 检查逻辑 ≠ 运行测试。 |
+| "这个 edge case 不太可能" | 不太可能的事总会发生。 |
+| "集成测试就够了" | 集成测试慢且定位困难。两者都需要。 |
+| "我先发布再修复" | 修复线上 bug 的成本是开发阶段的 100 倍。 |
+| "其他人都验证过了" | 责任在你。自己验证。 |
+| "这个模块不重要" | 每个模块对用户都很重要。 |
+| "性能问题以后再说" | 性能问题会滚雪球。早处理。 |
+| "文档可以后面补" | 后面 = 永远不。现在写。 |
+
+## 红旗
+
+这些想法意味着 STOP — 你正在合理化：
+
+1. **"我觉得应该没问题"** → STOP。验证它。
+2. **"这个改动很明显是对的"** → 明显的改动也经常有 bug。验证。
+3. **"测试都通过了"** → 测试通过 ≠ 行为正确。检查测试覆盖。
+4. **"我手动测试过了"** → 手动测试不可复现。自动化它。
+5. **"这个功能很简单"** → 简单功能也会有复杂 bug。
+6. **"用户不会这样用"** → 用户总会做你意想不到的事。
+7. **"这个错误不重要"** | 错误就是错误。没有"不重要"的错误。
+8. **"我先标记为已知问题"** | 已知问题也会让用户流失。
+9. **"这个只在特定环境出现"** | 特定环境也是真实环境。
+10. **"我昨天测试过了"** | 昨天 ≠ 今天。代码变了。重新测试。
+11. **"这个 warning 可以忽略"** | warning 是未来的 bug。现在修复。
+
+## 压力测试
+
+在声称完成前，问自己：
+
+1. 如果输入是空的怎么办？
+2. 如果输入是 null/undefined 怎么办？
+3. 如果并发 1000 个请求怎么办？
+4. 如果网络断了怎么办？
+5. 如果磁盘满了怎么办？
+6. 如果数据库连接超时怎么办？
+7. 如果用户输入包含特殊字符怎么办？
+8. 如果配置缺失怎么办？
+9. 如果依赖服务不可用怎么办？
+10. 如果内存不足怎么办？