implementkit

implementkit

将经过完善的计划、规范或问题转化为可运行的代码，到此为止。implementkit 是已敲定计划与干净提交之间的构建步骤：它读取明确的输入，确定如何构建（直接实现、先实现后测试或测试驱动），编写代码，并通过仓库自身的测试和构建门禁验证，之后才宣布工作完成。它绝不提交，因为那是 commitkit 的工作；它也绝不设计，因为如果输入不够明确，就会退回给 plankit/grillkit，而不是自行猜测。

它的标志性特性是模式解析：同一项请求会根据仓库（或用户）是否需要测试以及何时需要测试而采用不同的构建方式；implementkit 会按照固定优先级确定模式，而不是盲目使用默认方式。

何时触发

用户交接了要构建的具体内容：“实现这个计划”“构建问题 #42”“编写 docs/plans/0007-plan-sso-2026-07-23.md 的代码”“实现这个规范”“按 TDD 方式完成”“构建它并添加测试”“让这个失败的测试通过”。为已经运行但从未经过测试的代码补充测试属于改造工作，如果已安装 testkit，则应由它负责。这是计划 → grill → file → 构建 → 提交工作流中的 implementkit 步骤。

两条硬性边界：

• 不提交或暂存。 它会将已完成的工作保留为未暂存的更改，并报告所做的工作；commitkit 负责整理并提交。
• 不设计。 如果输入过于简略，无法在不臆造设计的情况下构建，它就会停止并指回 grillkit/plankit。implementkit 将已敲定的意图转化为代码；它不会敲定意图。

流程

1. 获取明确的输入

要求用户指定要构建的内容。可选输入包括计划文件（docs/plans/NNNN-plan-<slug>-YYYY-MM-DD.md，或不含 NNNN- 序号的旧文件）、问题（#42，或 gh 可获取的 URL/ID）、直接写在提示词中的自由格式规范，或修复轮次。修复轮次有两种形式：一份具体的审查发现列表（例如某轮审查中的阻塞问题），每项都要指出问题及其所在位置；或者一个能证明问题原因的失败复现测试（例如来自 debugkit）。不要自行寻找输入：如果用户没有指定任何内容，就停止并询问要实现什么。唯一的例外是问题分支。如果提示词没有指定内容，而当前分支符合 issue-<n>-<slug> 格式（这是 gitkit 为基于问题启动的工作树设置的格式），则将问题 #<n> 作为指定输入，并说明该分支提供了输入。其他任何分支格式都应停止并询问。完整读取指定的输入（对于问题，使用 gh issue view <n> 获取；如果无法使用 gh，则请用户粘贴内容）。只有在完整读取输入后，或本次运行已停止并要求用户提供输入后，这一步才算完成。

计划或问题可以限定为某一个阶段（“实现 0007-plan-sso-2026-07-23.md 的阶段 3”“实现 #42 的阶段 2”）。两者都用标题标出各阶段，因此限定范围后，只构建指定阶段，其余部分保持不变。无论如何都要通读整个文档：指定阶段之前的内容说明代码可能已有的假设，之后的内容则说明哪些内容不能提前实现。

2. 评估是否可实现；信息不足时退回

动手写任何内容之前，先判断输入是否具体到可以直接实现，而无需自行设计。经过充分打磨的计划或内容详尽的问题均符合要求。

查看计划本身的打磨信号。 标题正下方的 Grilled: YYYY-MM-DD 行表示计划已经通过 grilling。没有这一行，表示计划未经 grilling，或者自上次 grilling 后有过实质性修改，因为实质性修改会删除这一行。然后查看 ## Open questions 部分。如果计划未经 grilling，或该部分含有条目，就提醒用户并逐一列出未决问题。当前阶段依赖的未决问题属于缺口，应退回。其他未决问题仅作警告，继续构建。只有标题、单行需求，或核心决策尚未解决的规格说明，均不符合要求。停止并告知用户先用 grillkit 深入梳理决策，或用 plankit 起草完整计划，并指出遇到的具体缺口。不要用假设来弥补规格说明的不足；这里猜错的代价比退回更高。

因其他原因而信息不足时，应采用不同的处理路径。 如果输入尚未明确，是因为没人看过设计成果（状态模型在纸面上看似可行，但屏幕布局从未设计过），那么再多追问也无法解决，因为缺少的是证据，而不是决策。这种情况应转交给 prototypekit（如果已安装），否则就有意做一次一次性验证；问题解决后再回到这里。

修复轮次满足此门槛，因为发现结果或失败测试已明确指出缺陷，无需自行设计；绝不能以信息不足为由退回修复轮次。满足此门槛不代表通过：修复轮次和其他轮次一样，都要完整执行 完成门禁。此外，修复轮次会跳过下文的模式判定：直接按周边代码已体现的风格应用指定修复。

复现测试修复轮次应保留测试作为验证依据。 先运行测试，确认它如预期那样因相应原因失败。如果修复前测试已通过，则停止并报告该问题已无法复现。绝不能删除、跳过或削弱测试。完成修复的标准是：该测试在完成门禁检查时与其余测试一起通过。

当输入通过检查且所有警告均已说明，或已退回且每个缺口均已指出时，此步骤即告完成。

3. 判定模式

按以下优先顺序选择直接实现、先实现后测试或 TDD；采用第一个能得出结论的层级：

1. 提示词。 用户已明确说明（“用 TDD 实现”“先构建，再补测试”“直接写代码，不需要测试”）。明确指示始终优先。
2. Agent 指令。 仓库的 Agent 指南文件（CLAUDE.md 或同等文件）声明了模式或测试优先策略。遵循该指引。
3. 仓库惯例。 根据代码库推断。仅当以下两项同时成立时，才判定为 TDD：(a) 存在实际测试基础设施（例如 jest、vitest、pytest、go test、rspec、cargo test 等运行器或配置），且 (b) 仓库实际会随功能一同提交测试，近期提交同时涉及测试文件和源文件，并且测试与源代码的比例合理。仅有基础设施但没有相应惯例（例如孤立的配置文件，或测试远落后于代码），不算 TDD。
4. 询问一次。 如果仍未确定，且用户可以回答，就只询问一次要使用哪种模式。如果是非交互式运行（委托式／自主运行，无人可答），则默认采用直接实现，因为另外两种测试模式耗时更多，绝不会在未说明的情况下强行采用。说明最终采用的模式及原因。

4. 按已判定的模式构建

长时间构建应由协调者统筹。 如果范围包含多个需要独立新上下文的重型阶段，或一个机械性的大批量阶段（例如移植厂商代码或大规模 lint 检查），本线程不应直接执行其中任何阶段。每次工具调用都会重新计入整个上下文，因此在当前线程中执行每个阶段，都会增加后续所有阶段的成本。此时：

• 对阶段进行分组：繁重阶段单独成组，连续的轻量阶段共用一组。
• 按顺序为每组调度一个子 Agent，使用宿主提供的子 Agent 工具（Task 或 Agent；在 Codex 上使用 spawn_agent）。任务说明中应包含它会涉及的路径、它所调用的共享 API 的签名、已确定的模式、该阶段的验收项和门禁命令，这样它就不必读取本线程已经读过的内容。
• 子 Agent 按照工具规则构建并运行门禁，将备注和日志写入文件，并返回简短结果：通过或失败、已更改的文件、门禁结果，以及该文件的路径。
• 主控不编辑代码。它读取每份结果，调度下一组，然后对整个代码树运行一次完成门禁。

安装了 afkkit 时，其 调度规则章节包含完整的任务说明规则：使用新 Agent，绝不使用分叉；通过路径提供输入；以及两条命令规则。宿主没有子 Agent 工具时，按顺序在主线程中构建各组，并说明这一点。

无论是在主线程中还是委派执行，每条命令和每次文件写入都必须遵循工具规则。

直通模式。 编写生产代码以满足输入要求。不要编写新测试；将现有测试套件作为门禁的一部分运行（运行完成门禁）。这里真正的安全网是构建和类型检查，因为新代码可能尚未被测试覆盖。

测试后模式。 先像直通模式那样编写生产代码。然后为输入中提到的每种行为编写一个针对性测试。保留测试前，先观察它失败： 对测试覆盖的代码做一个小的语义改动（例如翻转比较条件或更改返回值），运行测试，确认它变红，然后撤销改动。如果测试在该改动下仍然通过，就说明它没有测试任何东西，应重写或删除。撤销每项改动时，只撤销你自己的编辑，绝不要还原包含其他更改的文件。

TDD 模式。 严格按 红 → 绿 → 重构 进行，每次处理一个行为单元：

1. 红。 为下一个行为切片编写一个有针对性的失败测试，运行并确认它失败（如果代码尚未实现时测试就通过，说明测试没有测试任何东西，继续前先修好它）。
2. 绿。 编写能使测试通过的最少量生产代码；运行测试并确认通过。
3. 重构。 清理代码和测试，同时确保测试套件持续通过。

对每个切片重复以上步骤，直到完全实现输入要求。在所有模式下，都要遵循相邻代码的约定、命名和结构，复用现有内容，而不是另起炉灶。

当范围内的每项要求都有对应代码，并且在测试后模式和 TDD 模式下，每种提到的行为都有一个曾观察到失败的测试时，该步骤即告完成。

视觉界面委派处理。 如果工作包含 UI（页面、组件或屏幕），且已安装 uikit，则将这些文件交由它处理，而不是盲目编写；它会遵循项目的设计约束，并运行自己的视觉预检。若未安装，则直接编写 UI。无论哪种情况，其余工作都由 implementkit 负责：包括输入契约、上面确定的模式，以及下面的完成门禁；完成门禁仍然是唯一的门禁。uikit 会直接将结果交还 implementkit，不会自行进行交接，因此用户只会看到 implementkit 的交接。

边做边检查，不要只在最后检查。 构建过程中要保持紧密的反馈循环：每个切片完成时都运行类型检查和单个受影响的测试文件，以便在修复成本低时及时发现问题。完整测试套件和构建留到完成门禁中执行。TDD 的红→绿流程已经会一次运行一个测试；这样做是为了弥补直通模式中的同一处缺口，否则它要到最后才会得到任何反馈。

5. 运行完成门禁

“完成”意味着仓库的检查全部通过，而不只是写好了代码。从仓库本身查找要运行的命令（package.json 脚本、Makefile、pyproject.toml、justfile、CI 配置），不要凭空猜测，然后运行：

• 测试命令；以及
• 构建 / 类型检查命令（如果仓库有 lint，也要运行）。

每个门禁命令只运行一次，并将输出写入日志文件，然后打印其退出代码以及日志中有长度限制的末尾内容或匹配行：

log="${TMPDIR:-/tmp}/gate-lint.log"; pnpm lint >"$log" 2>&1; echo "exit $?"; tail -n 40 "$log"

一次运行就能同时获得通过信号和相关消息，因此再次运行同一个门禁毫无意义。如果日志末尾没有指出失败原因，就继续查看日志内容。

必须全部通过后才能宣告完成。如果某个命令确实不存在（没有测试脚本、没有构建步骤），就说明这一点，并依据现有内容进行判断；不要编造命令。

检查通过并不代表全部达标。 即使现有测试套件通过，也可能没有覆盖新要求。列出输入中的每项验收要求：计划阶段的 Done when: 行、问题的验收标准、每项审查发现，或复现测试。为每项提供证据，例如测试名称、命令及其输出，或文件和行号。没有证据的项目应标为 未验证，绝不能说已完成。

只有在每个命令都运行并通过，且每项验收要求都有证据或标记为 unverified 时，此步骤才算完成。

6. 失败时修复，但要有上限

如果门禁失败，尝试修复自己的输出并重新运行，但尝试次数应控制在大约三次。如果仍未通过，就停止：绝不要在门禁失败时宣告完成，也不要无限循环。报告失败情况、尝试过的修复，以及你认为问题卡在哪里，然后交还处理。

7. 输入是计划时，标记计划

除非输入是计划文件且门禁已通过，否则完全跳过此步骤。然后标记已完成的工作，说明计划还剩什么。

如果阶段有 Done when: 行，先检查这一行。 运行或检查其中指出的可观察项，并报告结果。只有当可观察项成立时，才标记该阶段。若检查失败，保留未标记的标题，并报告该阶段已构建但尚未完成。若此处无法检查（需要部署或由他人执行），则标记该阶段，并报告该可观察项尚未检查。

在每个已完成阶段的标题后追加 (built YYYY-MM-DD)，使用今天的日期：

### Phase 2: auth (built 2026-08-20)
### Phase 3: session refresh (#41) (built 2026-08-20)

以下四条规则能确保标记属实：

• 只标记实际构建的阶段。 如果运行范围限定为一个阶段，就只标记该阶段，其他标题保持不变。绝不要标记跳过的阶段，也不要因为大部分工作已完成就标记整个计划。
• 必须在门禁通过且 Done when: 检查成立后再标记，绝不能提前标记。标记意味着工作已通过，因此给未经验证的代码加上标记，会让计划对其要记录的内容作出虚假声明。
• 保留已有的 (#41)，并在其后添加你的标记。 两种注释可以同时存在：编号说明该阶段的跟踪位置，标记说明它已完成。
• 像本次运行中的其他更改一样，不要暂存此编辑，以便 commitkit 将计划与实现计划的代码一并纳入。

每次运行都要添加标记，无论项目使用哪种跟踪方式。使用 GitHub issues 的项目会有同时包含两种注释的计划；不使用任何跟踪方式的项目则会有一份作为自身工作清单的计划。判断项目属于哪种类型是 implementkit 不需要、也不应做的事情。

8. 交接给 commitkit

本节使用流程性语体：每句话一条指令，使用主动语态和现在时，不用比喻。

让所有更改保持未暂存。不要运行 git add，不要提交，也不要起草提交说明（这是 commitkit 的工作，预先暂存会妨碍它分组）。报告简短摘要：

• 使用的模式以及决定模式的优先级层级，
• 创建和更改的文件，
• 检查结果（运行了哪些命令，以及这些命令均已通过），
• 每项验收项及其证据，并将每项标记为 unverified，
• 对于复现测试修复轮次，提供测试路径，说明修复前测试失败、修复后测试通过，
• 构建继续进行时接受的每项计划警告（未审查的问题、未解答的问题），
• 已盖章的阶段、每项 Done when: 的结果，以及该计划中仍未构建的阶段，
• 子 Agent 构建的每个阶段组及其结果文件，
• 本次运行启动的每个进程，并说明它们均已停止。

然后明确提出一个下一步：如果已安装 commitkit，就用它提交更改；否则，明确说明下一步是分组并提交更改。不要自行执行。按以下顺序列出备选方案：

1. 如果已安装 reviewkit，就在提交前使用它审查 Agent 的工作；否则自行查看差异。
2. 如果构建涉及 UI 界面，且已安装 verifykit，就使用 show 查看；否则打开应用查看。

如果计划还有下一阶段，就指出该阶段。如果没有，就说明计划已全部构建完成。

工具规则

每条规则都能避免长时间构建过程中反复付出的重试成本。

• 精确修改。 对于小型、精确的修改，使用 Edit。如果脚本会写入文件（如 codemod、sed -i、heredoc），请在同一命令中对这些文件运行仓库的格式化程序，并打印更改的行（git diff --stat，或针对相关文件运行 git diff -U0），以便立即发现错误模式，而不是等到检查阶段。
• 兼容 zsh 和 bash 的命令。 为每个 glob 参数加引号（--include='*.tsx'、'pkg@*'）。使用 printf '%s\n' … | while IFS= read -r f; do …; done 或 xargs 遍历文件列表，绝不要使用 for f in $files。zsh 不会拆分未加引号的变量，而且 glob 没有匹配项时会停止执行。
• 通过 PID 管理长时间运行的进程。 如果仓库提供自己的启动和停止脚本，就用它们启动开发服务器。否则，在后台启动服务器，将输出写入日志，并将 PID 写入文件。包管理器的包装进程可能会退出，而它启动的子进程仍占用端口，因此应检查端口（curl -sf、lsof -ti :<port>），不要根据包装进程的退出状态判断服务器是否仍在运行。交接前，通过 PID 或端口上的 PID 停止你启动的每个进程，并确认端口已释放。
• 浏览器检查应先读取事实。 浏览器工具检查 UI 时，先通过 evaluate 调用读取事实（文本、计算样式、元素数量），再执行其他操作。默认使用不含图像的快照。只有在需要作出视觉判断时才使用图像；如果用户需要查看图像，就将其保存到文件。

注意事项

• 仅负责构建。 不提交、不暂存、不发起 PR；这些属于 commitkit 和 prkit 的职责。implementkit 的工作在代码通过检查且未暂存时结束。
• 改造现有代码属于 testkit。 本次构建的代码由事后补测覆盖。对于已上线但尚无测试的代码，若已安装 testkit，则应交由 testkit 处理。
• Skill 在此处是为了委派给 uikit，调用并非没有代价。 在视觉相关工作中调用 uikit，会将一份大型文档载入本就庞大的构建上下文，而且本次运行中之后每次使用工具都会再次计费。这就是取舍：针对项目实际设计约束构建 UI，并进行自己的预检；或者选择更省钱的运行方式，在不了解设计的情况下编写界面。仅在 UI 工作中使用，其他情况一律不要使用。implementkit 不会调用其他技能，最后将任务交给 commitkit 只是指出下一步操作，并非实际调用它。
• 绝不臆测设计。 将信息不足的输入退回给 grillkit/plankit，是成功而非失败；这条边界能确保此技能保持诚实。
• 绝不粉饰通过状态。 声明“完成”始终意味着检查确实通过。限定修复后仍未通过，就如实报告未通过。
• 以代码库的约定为准，而非这些默认规则。 如果代码库有自己的测试/构建命令、目录布局或明确的工作流，请遵循并说明你已这样做。
• 如果无法使用文件系统或 shell（例如使用基于浏览器的 Agent），就无法写入文件或运行检查。此时应以代码块形式打印完成的代码（每个文件一个代码块，并注明其路径），供用户保存；说明你会采用的模式，并列出用户应自行运行的检查命令。