spec-implement

Spec 实施

执行已批准的 Spec 支持计划。如果计划使用了任务跟踪，请跟踪进度。汇报。遇到阻碍时停止。

开始时声明：“我将使用 spec-implement 技能来执行此计划。”

此技能不会做出设计决策，也不会更改已批准的内容。如果 Plan Mode 无法写入所需文档，它可以将对话中已批准的内容保存下来。如果计划有误，请返回 spec-plan。如果设计有误，请返回 spec-brainstorm。

前置条件

开始产品实现前，按顺序处理所需文档：

1. 如果缺少 docs/specs/YYYY-MM-DD-<feature>/design.md，请根据当前对话中已批准的设计编写该文件。验证文件，报告其路径，然后停止。在同一次调用中，不要创建 plan.json，也不要开始实现。
2. 否则，如果缺少 docs/specs/YYYY-MM-DD-<feature>/plan.json，请根据当前对话中已批准的计划编写该文件。按照 spec-plan 中的架构验证该文件，报告其路径，然后停止。在同一次调用中，不要开始实现。
3. 如果当前对话中没有编写下一个缺失文档所需的已批准内容，请停止，并告知人工审阅者缺少哪些内容。不要要求人工审阅者创建文件。
4. 两份文档都存在时，请确认规划时选定的任何跟踪器条目均可用；如果已配置跟踪，请同时确认 docs/agents/issue-tracker.md 可用。
5. 确认当前不在 main/master 分支上，除非用户明确同意。先创建分支或使用 git worktree。

每次调用最多创建一份缺失文档。只有在本次调用开始时两份已批准文档都已存在，才可以继续进行产品实现。

---

第 1 步：加载并审查计划

编写代码前，请仔细阅读 plan.json。检查以下问题：

• 任务含糊不清
• 缺少文件路径或验证标准不完整
• 任务之间存在冲突
• 依赖关系与代码库实际情况不符
• 现有代码或平台行为已经满足计划中的功能
• ID、解析器、错误、架构、生命周期处理或测试工具重复
• 共享抽象的当前使用者不足两个
• 测试的唯一目的只是验证新封装

如果计划中的机制未通过这些检查，请在实现前停止，并返回 spec-plan，提交较小范围的修订供人工审阅。保留已批准的行为和范围；不要强行实现缺乏依据的结构。

其他问题请在开始前向人工审阅者提出。不要猜测，不要想当然，也不要强行绕过阻碍。

如果没有问题，请继续。存在跟踪器条目时，使用现有条目。

---

第 2 步：选择执行方式

如果人工审阅者尚未指定执行方式，请询问。

自主模式

“全部实现。完成前不要停止。”

• 按依赖顺序执行所有任务
• Spec 支持的计划包含跟踪器条目时，跟踪进度
• 持续运行类型检查和 lint
• 仅在遇到阻碍时停止
• 如需无人值守地运行直至生成草稿 PR，请使用 spec-loop

分批模式（默认）

“每次完成几个任务。”

• 执行 3–5 个任务
• 停止并汇报已完成的工作、测试输出和任何意外情况
• 等待人工反馈后再继续

委派（所有模式）

在任何模式下，当设计已经敲定，只需完成文件时，按照 code-subagents 的“使用时机”标准，将任务委派给新的子代理。

• 使用 code-subagents 确认资格、派发模式和实现者模板
• 将相关设计摘录粘贴到派发内容中，确保子代理无需做出设计决策
• 明确指定 Agent（参见 atelier-orchestrator 中的 Delegation）
• 将相互关联、需要探索或对设计敏感的任务留在主线程中
• 主 Agent 在每批任务完成后执行合并计划和代码质量审查，并自行运行验证命令

子代理模式

“使用子代理。”

委派所有符合条件的任务。独立任务并行派发，有依赖关系的任务按顺序运行。

如果人类没有表达偏好，默认采用分批模式；仍须逐项委派任务。

---

第 3 步：执行计划

保留已批准的行为和范围。将计划中提出的结构视为假设，并确保它始终得到仓库证据的支持。

对于每项任务，直接从 plan.json 中查找下一个未阻塞的任务。如果存在跟踪器，请使用 docs/agents/issue-tracker.md 同步任务的执行状态；跟踪器状态绝不能覆盖计划的依赖关系图。

如果存在跟踪器，请按照 docs/agents/issue-tracker.md 将任务标记为进行中。

对于每项任务

先阅读任务的输入和描述。

对于会改变行为的代码任务，先编写覆盖验证标准的测试，再编写实现。对于文档、配置、迁移或仅验证类任务，请改用任务指定的验证方式。必要时调用已安装的特定语言测试技能。在模块接口处编写测试（参见 oracle-codebase-design），重构时使用其中的危险信号。

1. Read task inputs and description
2. Write failing tests (cover validation criteria)
3. Run them — verify they fail for the RIGHT reason
4. Implement minimal code to make tests pass
5. Refactor if needed (tests stay green)

对于会改变行为的代码，不要先写实现再写测试。不要跳过“验证测试失败”这一步。通过测试所需的代码不要多写。

根据任务的验证和验收标准核验任务。

每批完成后：验证并提交

运行任务针对性的验证，并检查本地差异，确认没有意外或超出范围的更改。报告偏差和意外发现。需要提交时，使用 code-commit；计划获批并不意味着可以跳过其审批关卡。全面的 code-review 会在 spec-finish 中进行。

完成时

如果存在跟踪器，请按照 docs/agents/issue-tracker.md 将任务标记为已完成。

参考现有代码

当计划或人类引用现有实现（例如“让它看起来像 users 表”）时，先阅读所引用的代码，再进行修改。引用中包含了所有未明确说明的隐含要求。

---

第 4 步：汇报（分批模式）

每批完成后：

Completed: [tasks]
- [completed work]

Test output: 6 passed, 0 failed
Type check: clean

Ready for feedback.

等待。在人类回复之前不要继续。

---

第 5 步：处理反馈

预期会收到简短、直接的纠正：

• “你没有实现 deduplicateByTitle。”
• “这应该放在管理应用中。把它移过去。”
• “更宽一些”／“还是被裁切了”

除非确实需要，否则不要追问。

调整方向的模式

模式	示例	如何处理
挑选	“第一个用 X。忽略第四个。”	按指示逐项处理
缩小范围	“跳过任务 T7。”	标记为已跳过，然后继续
保护接口	“这些签名不能变。”	调整调用方
覆盖	“使用该库内置的方法。”	直接按指示覆盖原方案
撤销	“我已撤销。现在只做 X。”	尊重缩小后的范围

撤销时

如果人类撤销了 Git 更改并缩小了范围，请完全遵守缩小后的范围。 不要挽救之前的方案。不要问“你确定吗？”

何时停止并询问

遇到以下情况时立即停止：

• 测试失败，且尝试 2 次仍无法修复
• 遇到计划中未涵盖的依赖项
• 指令不清楚或有歧义
• 计划与实际代码库不符
• 需要更改设计，而不只是更改实现
• 验证反复失败

停止时：

1. 清楚地说明阻碍
2. 展示你尝试过的做法
3. 询问接下来该怎么做

不要猜测。不要绕过问题。停止并询问。宁可请求澄清，也不要猜测。

如果需要更改计划：

“这需要修订计划。要我回到 spec-plan 吗？”

如果设计有误：

“这会改变设计假设。要我回到 spec-brainstorm 吗？”

---

何时重新审视前面的步骤

在以下情况下返回 spec-plan：

• 重大变更会影响已批准的行为、范围、架构、公共接口或主要依赖项
• 如果不做其中一项重大变更，任务就无法完成

较小的偏差可以在适当时随手记录，并反映到 plan.json 中。在下一次进度更新中报告这些偏差。

在以下情况下返回 spec-brainstorm：

• 需要重新思考根本方案
• 实现过程中发现设计有误

---

完成

完成所有计划工作后，进行验证并汇报。

验证清单

1. 运行完整测试套件 — 所有测试都必须通过，不能只通过新增的测试
2. 运行类型检查 / lint — 输出干净，没有新增警告
3. 确认完成情况 — 使用跟踪工具时，关闭每个跟踪条目
4. 检查差异 — 对照预期的基分支检查完整差异。注意：
   • 不该更改却被更改的文件
   • 遗留的调试代码或临时变通方案
   • 计划内容与实际实现之间的不一致

汇总报告

向用户展示：

## Feature Complete: {feature name}

**Plan:** Spec-backed Plan
**Tasks:** {completed} / {total}
**Tests:** {new tests added}, {total passing}
**Files:** {created}, {modified}

### What was built
- [concise list of what was implemented]

### Verification
- Test suite: ✓ all passing
- Type check: ✓ clean
- Lint: ✓ clean
- Comprehensive code review: pending spec-finish

### Ready for review

后续步骤

完成并验证所有计划工作后，下一步是 spec-finish。

“实现已完成。准备好进行验证、审查并为 PR 做准备了吗？”

向用户提供选项：

完成 — 调用 spec-finish 进行验证、审查并整理提交 保留 — 暂时保留此分支，稍后再继续 放弃 — 删除此分支，重新开始

不要替用户做决定。展示选项并等待。

如果验证发现错误，返回实现阶段。迭代模式请参阅 atelier-orchestrator。