implement

实现

每次会话仅实现一项工作，全程采用测试优先并端到端验证。工作项可以是一个工单、一项足够小、可在一次会话中完成的规范，或双方商定的对话范围。唯一例外是规范运行，它会在一次会话中实现某项规范的所有工单。

规范运行和 PR 交付见 references/spec-run.md。每次运行都要在步骤 1 前阅读：先回答其中的选择交付方式问题（当前分支、一个 PR，或为整个规范创建一组 PR）。当用户要求实现整项规范（all、"implement all of …"）或修改已通过 PR 交付的工作时，适用其中的规范运行和后续处理章节。

流程位置：wayfinder（决策）→ to-spec（编写规范）→ to-tickets（拆分为工单）→ implement（每次会话构建一个工单，并在其中审查和验证）。

防护措施

• 绝不重置、回滚、删除或截断数据库，也不得执行其他破坏性数据操作，除非获得明确批准。将架构变更放入新的迁移中；对线上表的变更按扩展–收缩顺序执行。
• 使用前先验证标识符：路由名称、配置键、枚举值、图标名称和软件包 API。清单中的条目本身并不能证明已注册或正在使用。

技术栈参考。 根据清单识别技术栈。如果下方存在匹配的文件，请在步骤 1 前阅读：其中列出了该技术栈的破坏性命令、格式化工具、测试命令和工作树设置。

• Laravel（composer.json 中的 laravel/framework）：references/laravel.md

流程

1. 界定范围并认领工作

对输入分类，并明确其验收标准：

• Ticket：获取完整正文和评论。如果有父级 spec，先加载其中的 Build Contract 部分（如有），再加载 Ticket 指定的标题部分或实现过程中涉及的部分。读取直接阻塞项的 Resolution 部分，以了解交接过来的衔接点；仅在需要时加载其他已关闭的 Ticket 和映射表。wayfinder 决策 Ticket 仅当其类型为 task 时才符合条件；其他类型用于决策而非构建，因此应停止。task 是手动解除阻塞的工作，不涉及代码；能自行完成的就自行处理，否则把 ticket-types 中精确的检查清单交给人类；任何破坏性或不可逆操作都必须先获得明确批准，记录由此产生的事实，并将其标记为已解决。此类工作跳过衔接点／TDD／提交／审查／验证循环（步骤 2–7），因为这些步骤假设会修改代码。Ticket 就是工作项。
• Spec：获取完整正文和评论。如果其中包含多个可独立交付的 Ticket，或无法在一个会话内完成，就需要拆分为 Ticket：如果 tickets/ 已发布且有人要求执行 spec run，就运行 spec run；否则停止，并告知用户运行 to-tickets。可在一个会话内完成的 spec 本身就是工作项。
• Conversation：用几行重述范围和行为标准。它没有跟踪器认领或解决流程。

工作项是 .scratch/ 下的 Markdown 文件；不存在外部跟踪器。如果启动上下文已指出所选文件、其状态和阻塞项，就重新验证这些确切文件，而不要重新读取跟踪器布局。否则，通过 .agents/issue-tracker.md（由 /setup 编写）读取一次布局。若该文件不存在，则尝试读取 docs/agents/issue-tracker.md（旧版），然后读取 setup 技能中的种子文件。通过工作项的 blocked-by frontmatter 确认每个直接阻塞项都已关闭；如仍有未关闭项，在认领前停止。然后在开始构建前认领：

• 对于来自 to-tickets 的 Ticket，或直接实现的 spec，将其 frontmatter 中的 status: 设为 in-progress，将 claimed-by: 设为会话唯一值，然后重新读取以确认认领成功（写入后比较，参见跟踪器中的并行工作规则）。直接构建的 spec 与 Ticket 一样认领；它就是实际构建所依据的文件，而非应保持不变的父级文件。
• 对于 wayfinder 决策 Ticket，使用 Wayfinding 的 Claim 操作（claimed-by）。

Ticket 或 spec 是可跟踪的：其 frontmatter 中的 status 是记录状态。某些仓库还会在跟踪器文档中维护工作事项的台账或文字摘要；若仓库要求，就更新它，但不能用它替代 frontmatter 写入。在关联的工作树中构建不会改变任何状态：在该工作树中写入并提交 frontmatter，分支合并后更改才会进入主检出目录。

如果工作项已被认领或处于进行中状态，就停止；只有当其工作明显已提交或明确被放弃时，才将认领视为过期。

认领后，或完成仅限对话的范围界定后，将 git rev-parse HEAD 的输出记录为不可变的 base_sha。审查和证明故障原本就存在时，必须使用该确切 SHA。

只有在工作可于一个会话内完成、验收标准明确、所有可跟踪工作项均已认领且阻塞项已关闭，并且已记录 base_sha 时，才算完成此步骤。

2. 选择衔接点

使用 tdd 技能中 Seams: where tests go 部分的排序和选择规则。复用 spec 中已记录的衔接点；否则，自行选择并说明选择结果：每个衔接点一行，无需征求批准。衔接点位置属于测试结构；grilling 的 What still earns a question 将其交由你决定，而相关规则是唯一事实来源。只有当规则将两个方案评为同等优先，且两种位置会导致实质不同的工作时，才提出问题。

只有在每项验收标准都有对应衔接点时，才算完成此步骤。

3. TDD 循环

在选定的切入点运行 tdd 技能。根据仓库脚本和现有用法，找出针对性测试和静态分析命令；循环期间每次运行测试，都要将范围限定为覆盖此次变更的单个测试或文件（使用 --filter=<test name> 或确切的测试文件路径，绝不运行同一目录下相邻的测试套件或演示套件），并在已配置静态分析时定期运行。如果用户明确要求本次会话跳过测试，则在本次会话剩余时间内都遵守这一要求，并在第 8 步注明。

只有在选定的切入点覆盖了所有验收标准、所有针对性测试均通过（如果用户要求跳过测试，则以最后一次针对性测试结果为准），且已配置的静态分析通过后，才结束循环。

4. 格式化并提交可供审查的检查点

仅对你修改过的路径运行仓库配置的格式化工具（Pint、Prettier、Black、gofmt：以仓库配置为准），确保并行会话中未提交的文件保持原样。检查 git status --porcelain，仅通过显式路径暂存工作项文件，并让外部变更保持未暂存状态。.claude/agent-memory/ 下的变更始终也属于你，无论由谁编写：这些是设置了 memory: project 的 Agent 的笔记，并非并行会话的进行中工作，因此要一并提交（git add -- .claude/agent-memory）。提交到当前分支（PR 交付流程已在第 1 步之前创建该分支）；此步骤不创建分支或工作树。记录你修改过的路径；下一步的审查范围仅限这些路径，因此并行会话在同一分支上的提交既不会在此处被暂存，也不会在此处被审查。

完成此步骤时，所有工作项变更都必须已提交，所有外部变更都必须保持原样，并记录检查点提交的 SHA。

5. 审查

针对你记录的工作项路径运行 code-review 技能，并以 base_sha 为基准（这样共享分支上的并发提交就不会纳入审查范围）。通过 tdd 循环解决所有可操作的发现，重新运行受影响的针对性检查和静态分析，格式化，仅暂存显式路径，并提交修复。每次修复提交后，都要重新运行 code-review 进行复审，并传入上一轮的发现和 HEAD。审查轮次上限为两轮：如果第二轮仍有可操作的发现，就停止修复，并将这些发现及每轮审查所针对的提交列给用户。

code-review 的 Correctness 维度负责查找错误和故障模式；其 BLOCKING 和 MAJOR 级发现与其他发现一样都应处理。若修复新增了某种机制（作业、锁、认领、重试），这就构成了新的审查范围，因此修复提交后的复审也要覆盖它。此步骤中遗漏的任何问题都将交由 PR 审查机器人处理，每次推送进行一轮审查。

只有在审查未报告尚未解决的可操作发现（或已用完审查轮次，并已列出剩余发现），且所有工作项变更都已提交后，才完成此步骤。

6. 运行最终自动化检查

如果仓库规则或用户保存的偏好已明确决定是否运行完整测试套件（例如，CI 会运行测试套件，或“除非另有要求，否则不要运行完整测试套件”），则跳过询问并遵循该决定。否则，通过 AskUserQuestion（如可用；否则在聊天中直接提问）询问一次是否要运行完整测试套件，作为最终自动化门禁。如果回答为否，则跳过完整测试（第 3 步的定向测试可作为自动化证据），并记录此次跳过，以便第 8 步明确报告。

获得批准后，运行仓库文档中说明的完整测试套件命令：AGENTS.md 或 CLAUDE.md、包脚本（composer.json、package.json、Makefile）或 CI 工作流中会注明该命令。只有在这些地方都没有说明时，才使用该技术栈的默认测试运行器。如果运行可能超过前台时限，则将其放到后台运行（如可用，使用 Bash run_in_background）。然后结束本轮，不要回复，等待完成通知唤醒你；只告知用户测试仍在运行会白白占用用户一轮。修复由本次工作导致的失败。通过对照 base_sha 证明无关失败在此之前就已存在，然后明确记录，不要扩大范围。

任何代码修复都要返回第 3–5 步，然后才能再次运行此门禁。若完整测试已跳过（用户拒绝，或规则、偏好已决定跳过），或者所有由本次工作导致的检查均已通过且剩余失败都有 base_sha 证据，则完成本步骤。

7. 端到端验证

运行 verify 技能。如果发现产品问题，则返回第 3–6 步，修复后再重新验证。只有验证成功，才能完成可跟踪的工作项。

如果外部依赖导致无法验证，保留已提交的实现，报告确切的阻碍，并保持工作项为打开状态。不得仅凭推断标记为已验证。

8. 收尾

验证成功后，记录已构建的内容、任何有充分理由的偏离、验证证据、实现提交 SHA（一个或多个），以及直接后续工作可复用的公开接口；勾选所有已满足的验收标准。此 Resolution 是交接给后续工作的内容，因此应具体说明接口和证据，不要重述父级规范。根据分支处理工作项：

• Ticket 或直接实现的规范：将其 frontmatter 中的 status: closed 写入，并追加 ## Resolution。必须准确写为 closed，不得使用 built 或 done 等自创值。
• wayfinder 决策 ticket：使用 Wayfinding 的 Resolve 操作。
• 对话：报告结果，不要修改 .scratch/ 下的任何文件。

保持所有父级工作项为打开状态；ticket 永远不会关闭其规范，而 implement 绝不修改 map（规范或 tickets 写入时，map 已由 to-spec 关闭；或者在没有规范时由 to-tickets 关闭）。当 tickets/ 中的每个 ticket 都已关闭时，规范才算完成；这是需要报告的派生状态，不是写入规范的状态。如果规范本身就是本次会话的工作项，则直接关闭该规范。不要将 Resolution 写入代码提交：如果 .scratch/ 受版本控制，请单独提交；绝不要将其并入实现提交。Resolution 文本引用实现提交，而不是它自己的关闭提交。

对于可跟踪的工作，写入后重新读取 Markdown 文件，并确认其 frontmatter 中为 status: closed，且包含 ## Resolution 部分。

实现提交和任何单独的 Resolution 提交均已记录、跟踪器的最终状态已验证，或者已报告仅对话的结果后，即可完成并停止；任何后续工作项都应在新的会话中开始，并使用干净的上下文。

完成后

使用 wayfinder/references/pipeline-end-block.md 中的格式打印会话结束块。对于有父项的可跟踪工作项，打印结束块前，请查看 Markdown 跟踪器，确认剩余待处理事项，不要猜测还剩什么。

---
Pipeline: decide → spec → tickets → **build**   (4 of 4)
Done: <what now works, the work-item ref if any, commit(s), verification state>
Next:
  • <condition> → /<skill> <ref>

各阶段适用的 下一步 条件（仅列出适用项，最可能的优先）：

• PR 已开启，且审查机器人仍在运行 → 它们发布评论后，运行 /resolve-review-comments <PR>；注明 PR 和工作树路径
• 有一组已开启的 PR → 运行 /triage-github-pr <every PR, bottom-up>，按从底到顶的顺序使用合并提交将其合并
• 父规格上还有待处理的前沿工单 → 运行 /clear，然后运行 /implement <next frontier ticket>（如果你在工作中途停止，先继续处理自己已认领但未完成的工单）；或者运行 /implement <spec path> all，一次完成其余工作；也可以运行 /implement-spec <spec path>，并行完成这些工作；注明工单名称和剩余数量
• 规格中的所有工单都已关闭 → 无需运行任何命令；说明规格已完成，并注明任何推迟到范围之外的事项
• 所有剩余工单都受阻 → 先运行 /implement <the blocker>；如果阻塞原因是决策，则运行 /grill-me
• 构建过程中发现尚未有人决定的问题 → 针对该问题运行 /grill-me，然后如果规格已不再正确，则重新运行 /to-spec
• 验证因外部原因受阻 → 保持工作项开启，并注明解除阻塞的具体条件
• 工作中途停止 → 说明哪些检查已通过、哪些内容已提交或未提交、认领状态，以及接下来要编写的失败测试；下次会话先继续处理该工单，再领取新工单；或者将其 Release，交回待处理事项列表