规划、实现和验证功能时用 Spec-Driven…

适用于规划功能、带验证和原子提交地实现功能，以及对照 spec 验证实现；不适用于纯架构分解或独立技术设计文档。

适用场景

解决思路

1. 加载本技能文件时，从 SKILL.md 所在技能目录解析 references/ 下的引用文件，不要用工作区根目录；通过活动技能按名称加载；读到引用步骤时完整读到 EOF 再行动，不要基于部分或截断读取行动。
2. 运行本技能脚本时，先解析技能目录，再执行 python3 <skill-dir>/scripts/<name>.py ...；不要从消费项目根目录运行 python3 scripts/...；项目数据 .specs/ 仍相对项目根读写，cwd 不同时传 --root。
3. 执行契约：每个任务的测试从 spec 的验收标准派生，断言 spec 定义的结果，绝不镜像实现。
4. 任务完成前必须通过 gate（测试通过），由测试运行器决定，不是自评。
5. 每个任务一个原子提交；在提交前在 tasks.md 标记任务完成，并在使用 traceability 时更新 spec，把这些更新包含在同一提交；不要批量任务；不要为了通过而削弱、跳过或删除测试。
6. 最后一个任务后，自动运行新的 Verifier（author != verifier）：做 spec 锚定结果检查加判别传感器；它永不跳过、永不提示。见 Sub-Agent Delegation。
7. Blast radius：批准 spec 或 tasks 只授权本地实现和本地提交；git push、force-push、deploy、production DB changes 及其他远程、外部可见或破坏性操作需要针对该操作的明确 go-ahead。
8. 确定性 gate 在人工审查前运行，不能靠记忆：确认 spec 前运行 python3 <skill-dir>/scripts/validate_spec.py <spec-path-or-feature>（闭包 gate：EARS 形态 AC、已填写假设、格式良好的 requirement IDs、必需章节）。
9. 展示 tasks 供批准前运行 python3 <skill-dir>/scripts/validate_tasks.py <tasks-path-or-feature>（粒度异味、图与 Depends on 在同阶段一致、无前向阶段依赖、每个任务带 Tests 加 Gate）。
10. 每次提交运行 python3 <skill-dir>/scripts/check_commit.py --message "<msg>" 检查 Conventional Commits；可选把它接成 git commit-msg guard（仅 git，无 agent 依赖）。
11. 声明 feature 完成前运行 python3 <skill-dir>/scripts/validate_state.py <feature>（完成 gate：Verifier 的 validation.md 存在、verdict 填到 PASS、并引用 file:line 证据；缺失、FAIL、占位或无证据报告都失败）。Execute 收尾自动运行此步。
12. 任何脚本非零退出意味着 STOP 并在继续前修复。只有在没有代码执行工具时才跳过脚本；此时通过阅读 artifact 做同样检查。
13. Execute 前：完整读 references/implement.md 并运行 validate_tasks.py；如果正式 tasks.md 打包超过一个任务预算批次（> ~8 tasks），先提出 sub-agent offer（见 Sub-Agent Delegation）。
14. 开始任何 feature 前评估 scope，只应用所需深度：Small（≤3 文件、一句话）写 inline 的 one-liner spec，跳过 Design 和 Tasks，inline 实现加验证。
15. Medium（清晰功能、<10 tasks）写 brief spec，跳过 Design（inline design），跳过 Tasks（tasks 隐式），实现加验证。
16. Large（多组件功能）写 full spec 加 requirement IDs、architecture 加 components、full breakdown 加 dependencies，并按任务实现加验证。
17. Complex（模糊、新领域）写 full spec 加 discuss gray areas、research 加 architecture、breakdown 加 phase plan，并做 interactive UAT。
18. Auto-sizing 规则：Specify 和 Execute 总是必需；Design 在变更直接（无架构决策、无新模式）时跳过；Tasks 在 ≤3 个明显步骤时跳过（在 Execute 中隐式）；Discuss 在 Specify 内触发，当检测到需要用户输入的模糊灰色区域，或功能有任何隐含需求维度（persistence/state、external calls、auth、payments、concurrency、state transitions）；Interactive UAT 在 Execute 内只对具有复杂行为的用户可见功能触发。
19. 安全阀：即使 Tasks 被跳过，Execute 总是先内联列出原子步骤；如果列表显示 >5 步或复杂依赖，STOP 并创建正式 tasks.md。
20. 维护 .specs 结构：STATE.md 存 Decisions log（AD-NNN）加 Handoff snapshot；LESSONS.md 由 scripts/lessons.py 渲染，不手编；lessons.json 是机器拥有的规范 lessons 状态；features/[feature]/ 下按需包含 spec.md、context.md（仅 discuss 触发时）、design.md（仅 Large/Complex）、tasks.md（仅 Large/Complex）、validation.md（Verifier 报告：PASS/FAIL、per-AC evidence、sensor result、diff range）。
21. 惰性创建 artifacts：只在阶段实际产生内容时写每个文件；绝不要预先 scaffold 空 context.md、design.md 或 tasks.md；空文件会表示阶段发生了但实际没有；跳过阶段的正确状态是缺失。
22. 新 feature 工作流：Specify → (Design) → (Tasks) → Execute，深度自动 sized。
23. 恢复工作时：读 .specs/STATE.md（Handoff 加 Decisions）；用 git（branch、status --porcelain、recent commits）和 tasks.md 核对 Handoff，证据胜过过期快照；完整流程见 references/memory.md；写代码前提出核对后的下一步。
24. 按需加载上下文，只加载当前任务需要的：.specs/STATE.md 的 Decisions 在 Design 读、恢复时重读；Handoff 仅在恢复时读；confirmed lessons 在 Specify 和 Design 通过 python3 <skill-dir>/scripts/lessons.py list --status confirmed 加载（只 confirmed，不 candidates）；spec.md 在特定 feature 工作时读；context.md 在从用户决策设计或实现时读；design.md 在从 design 实现时读；tasks.md 在执行 tasks 时读。
25. 绝不同时加载多个 feature specs 或多个 architecture docs。
26. 上下文目标：总计 <40k tokens；预留 160k+ tokens 给工作、推理、输出；>40k 时显示状态（见 references/context-limits.md）。
27. Sub-agent 触发：统计总任务。如果 feature 打包超过一个任务预算批次（> ~8 tasks）就提供 sub-agents；如果适合单批次（≤ ~8 tasks）就 inline 执行。Offer-then-confirm，绝不自动 spawn；用户接受后才派发任何 sub-agent。
28. 一个 worker 负责一个任务预算批次（~7 tasks、whole phases）：phases 保持语义或依赖单元；batch 是执行单元，一个或多个连续 whole phases 打包到 ~7 tasks。按顺序遍历 phases，把 whole phases 累积到当前 batch 直到预算，再开下一个；绝不把 phase 拆到多个 worker。~20 tasks → ~3 workers；线性扩展（40 → ~6）。每个 worker 按顺序执行所有任务（implement → gate → atomic commit），然后报告 compact summary（tasks done、commit hashes、test counts、deviations）。Batches 顺序运行；前一个 batch 未报告所有任务完成前，下一个 batch 不开始。Workers 不再 spawn sub-agents。
29. Verifier 总是自动运行且无需提示：最后任务提交后，orchestrator 自动派发 fresh Verifier sub-agent，不论 phase 数量。Validation 不需要用户 prompt；它是 Execute 的收尾步骤。Author ≠ verifier；Verifier 用 evidence-or-zero 独立重新推导覆盖，不继承作者心智模型。
30. Verifier 做：(1) spec-anchored outcome check：确认每个测试断言的值匹配 spec 定义的期望结果，标记 spec-precision gaps；(2) 运行 discrimination sensor：在隔离 scratch（临时 worktree 或 file copies，绝不用 git stash）注入行为级故障，确认 tests kill them，丢弃 scratch 并验证 real-tree porcelain 匹配 pre-sensor baseline；存活的 mutant 成为 fix tasks；(3) 写 .specs/features/[feature]/validation.md（PASS/FAIL、per-AC evidence、sensor result、diff range）；(4) 向 orchestrator 在聊天中返回 compact verdict 加 ranked gap list；Gaps 成为 fix tasks；fix→re-verify 循环限制 3 次后升级；(5) distill lessons：每个 grounded failure（surviving mutant、spec-precision gap、failed AC、SPEC_DEVIATION）通过 <skill-dir>/scripts/lessons.py 变成可复用项目本地 lesson；clean PASS 不记录任何内容（见 references/lessons.md）。
31. 如果 harness 支持按 sub-agent 选择模型，按角色匹配模型 tier：机械、低模糊 phase（entities、config、wiring、straightforward CRUD）用更快或更便宜 tier；核心领域或高模糊 phase、以及 Design phase 用高推理 tier；Verifier 用中到高 tier，因为它做 adversarial reasoning 并设计 mutations。如果 harness 不能设置 per-sub-agent model，忽略此项。完整 rubric 见 references/sub-agents.md。
32. 没有 sub-agents 的 standalone fallback：在最后提交后运行 references/validate.md 作为独立 fresh-eyes pass，包括 spec-anchored check 和 discrimination sensor。
33. Feature-level 命令映射：Specify feature 或 define requirements 读 references/specify.md；Discuss feature、capture context、how should this work 读 references/discuss.md；Design feature 或 architecture 读 references/design.md；Break into tasks 或 create tasks 读 references/tasks.md；Implement task、build、execute 读 references/implement.md；Validate、verify、test、UAT、walk me through it 读 references/validate.md。
34. Memory 命令映射：Record decision 或 this is a project-level decision 读 references/memory.md；Pause work、end session、I need to stop 读 references/memory.md；Resume work、continue、pick up where we left off 读 references/memory.md；Load lessons、what have we learned、apply past lessons 读 references/lessons.md；Record lesson、distill lessons（validation 后自动运行）读 references/lessons.md。
35. Knowledge Verification Chain 按严格顺序执行，绝不跳步：Step 1 Codebase 检查现有代码、约定、已用模式；Step 2 Project docs README、docs/、inline comments、.specs/STATE.md（Decisions）；Step 3 Context7 MCP 解析 library ID，再查询当前 API 或 patterns；Step 4 Web search 官方文档、可靠来源、社区模式；Step 5 标记为不确定：「I'm not certain about X - here's my reasoning, but verify」。
36. Knowledge Verification Chain 规则：如果 Steps 1-4 可用，绝不跳到 Step 5；Step 5 总是标记为不确定，绝不作为事实呈现；绝不假设或捏造。如果找不到答案，说「I don't know」或「I couldn't find documentation for this」。发明 API、模式或行为会导致 design → tasks → implementation 级联失败；不确定总是优于捏造。
37. Output Behavior：做工作，不叙述机器。产生该阶段的正确 artifact，而不是宣布阶段（如「I will now run the Specify phase」）。用户判断输出，而不是过程 play-by-play；保持流程不像机器人。
38. Match effort to the work：轻量步骤（feature-level checks、validation、mechanical tasks）不需要顶级推理；重步骤（复杂设计、模糊功能）需要。如果 harness 允许 per-sub-agent 选模型，应用 references/sub-agents.md 的 tier rubric；否则继续，并在重步骤投入更多 care。每 session 最多提一次，且只在有帮助时提；经验用户跳过。
39. 写生成的 artifacts 用 plain、decided voice：Specs、ADRs、validation reports、commit messages、chat summaries 遵循 references/coding-principles.md 的写作规则：先给 verdict，决定性地陈述决策，删掉填充和机械 hedging。
40. Code Analysis：使用可用工具并优雅降级；见 references/code-analysis.md。

适用边界 · 注意事项

• 不要用于纯架构分解分析。
• 不要用于独立技术设计文档。
• 没有代码执行工具时不能依赖脚本强制结构门禁；只能阅读 artifact 做同样检查。