Skills 项目 implement 技能全解析：基于 Spec 与 Tickets 驱动的工程实现工作流

Skills 项目 implement 技能全解析：基于 Spec 与 Tickets 驱动的工程实现工作流

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills

导读

implement是 skills 仓库 中工程类（engineering）技能族的「收口」环节：它接收由 Spec 或一组 Tickets 定义的工作描述，按照「在预约定缝处用 TDD 推进 → 持续类型检查与测试 → 用 code-review 双轴评审 → 提交到当前分支」的固定协议完成实现。本文将以 skills/engineering/implement/SKILL.md 为骨架，逐条拆解其指令语义，并联动 tdd、code-review、to-spec、to-tickets 等上下游技能，结合仓库源码与测试规范文件，完整还原一条从 Spec 到提交的工程实现流水线。读完你将掌握：如何显式触发 implement、它内部五条指令的准确含义、pre-agreed seams 的约定方法，以及收尾阶段两轴代码评审的执行要点。

一、技能定位：从「收到任务」到「提交代码」的收口环节

在 skills/engineering/README.md 的「User-invoked」技能列表中，implement被定义为：

Build the work described by a spec or set of tickets, driving/tddat pre-agreed seams and closing out with/code-reviewbefore committing.

也就是说，它不负责「探索需求」（那是 research 的职责）、不负责「设计方案」（那是 codebase-design 与 domain-modeling 的职责），它只做一件事：把已经写清楚的工作描述，变成可以提交的代码。

调用方式：仅限用户显式触发

SKILL.md 的 frontmatter 明确声明了两种主流 Agent 环境下的调用约束：

--- name: implement description: "Implement a piece of work based on a spec or set of tickets." disable-model-invocation: true ---

• disable-model-invocation: true：在 Claude Code 中，模型不能自行触发该技能，只能由用户以/implement形式显式输入；
• 配套的 agents/openai.yaml 中policy.allow_implicit_invocation: false对 Codex 类 Agent 表达了同样的约束，并给出了界面元信息：

interface: display_name: "Implement" short_description: "Build work from a spec or tickets" policy: allow_implicit_invocation: false

这一设计意图很明确：实现是一个有明确投入产出边界的操作，只有当用户确认手头已经有一份 Spec 或一组 Tickets 时，才应进入 implement 流程。它与 triage 一样，属于「用户判断时机、Agent 执行协议」的协作模式。

二、输入侧：Spec 与 Tickets 从哪来

implement 的输入是「用户描述的 Spec 或 Tickets」。在 skills 仓库中，这两类输入分别由上游技能生产：

• to-spec：把当前会话中已经讨论清楚的内容综合成一份 Spec 并发布到项目 issue tracker，全程不采访用户，只做综合。其模板包含Problem Statement、Solution、User Stories、Implementation Decisions、Testing Decisions、Out of Scope、Further Notes七节，其中Testing Decisions一节要求写明「什么是好测试」「测哪些模块」「测试的 prior art」——这直接为 implement 阶段「在哪些 seam 上测试」提供了依据。发布时需打上ready-for-agent的 triage 标签。
• to-tickets：把计划、Spec 或会话拆解为一组tracer-bullet 垂直切片票据，每张票据声明自己的blocking edges（被哪些票据阻塞）。垂直切片的规则是「每个切片切过所有层（schema、API、UI、测试）的完整路径，而不是某一层的水平切片；完成即独立可演示/可验证」。票据可以发布为本地文件（.scratch/<feature-slug>/issues/<NN>-<slug>.md）或真实 tracker（GitHub、Linear 等）上的 issue，并持续推进frontier（所有 blocker 都完成的票据集合）。

因此，一条完整的规格化链路是：to-spec 产出 Spec → to-tickets 拆出带依赖关系的 Tickets → implement 按 Tickets 逐片实现。implement 位于这条链路的末端执行位。

三、核心协议：implement 的五条执行指令

SKILL.md 正文本身极其凝练，共五条指令，是全文的骨架：

1. Implement the work described by the user in the spec or tickets.（按 Spec 或 Tickets 实现用户描述的工作）
2. Use /tdd where possible, at pre-agreed seams.（尽可能在预约定缝处使用/tdd）
3. Run typechecking regularly, single test files regularly, and the full test suite once at the end.（定期跑类型检查、定期跑单个测试文件、最后跑一次完整测试套件）
4. Once done, use /code-review to review the work.（完成后用/code-review评审）
5. Commit your work to the current branch.（提交到当前分支）

下面逐条展开，并结合对应技能的源码文档说明其具体含义与执行细节。

四、指令二拆解：在 pre-agreed seams 处用 TDD 驱动实现

第五条指令中出现的关键词是/tdd与pre-agreed seams。这两者共同定义了「实现过程中测试怎么写、写在哪」的纪律，其完整语义在 tdd/SKILL.md 中。

什么是 seam

tdd 技能给出定义：

Aseamis the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.

seam 是观察行为的外部公共边界。测试只生活在 seam 上，绝不深入内部实现。

为什么必须「预约定缝」

tdd 技能的核心约束是：

Test only at pre-agreed seams.Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam.

在写任何测试之前，先把要测试的 seam 写下来并与用户确认；未经确认的 seam 上一律不写测试。因为「你不可能测一切」，提前约定 seam 才能把有限的测试精力投放到关键路径和复杂逻辑上，而不是平均撒在每个边界用例上。实操中应主动提问："What's the public interface, and which seams should we test?"

若接口本身的形态（模块该多深、seam 该在哪、接口该暴露什么）存疑，tdd 技能建议调用 codebase-design 获取 module / interface / depth / seam / adapter / leverage / locality 等共享词汇，它是参考文档而非会话流程。

垂直切片：一次一个 tracer bullet

tdd 技能明确反对horizontal slicing（先写完所有测试、再写全部实现），因为「批量测试验证的是想象出来的行为」——你测试的是事物的形状而非用户可见行为。正确做法是vertical slices：一个测试 → 一段最小实现 → 重复，每个测试都是响应上一轮经验教训的tracer bullet。

循环规则

tdd 技能给出三条硬规则：

• Red before green.先写失败的测试，再只写足够让它通过的代码。不要为未来的测试做铺垫，不要加投机性功能。
• One slice at a time.每个循环只处理一个 seam、一个测试、一段最小实现。
• Refactoring is not part of the loop.重构不属于红绿实现循环，它属于评审阶段（见 code-review 技能）。

三个反模式与好测试判据

tdd 技能列出三个必须规避的反模式：

1. Implementation-coupled（实现耦合）：mock 内部协作者、测试私有方法、或通过旁路验证（如直接查数据库而非走接口）。特征：行为没变，重构却把测试弄挂了。
2. Tautological（同义反复）：断言用与实现相同的方式重算期望值（如expect(add(a, b)).toBe(a + b)），测试通过构造而成立、永远不可能与代码产生分歧。期望值必须来自独立的真值源：已知正确的字面量、手算例子或 Spec。
3. Horizontal slicing（水平切片）：先写全部测试再写全部实现，见上文。

配套的 tdd/tests.md 给出了好测试与坏测试的直接对照。好测试是「integration-style」——通过真实接口测试可观察行为：

// GOOD: Tests observable behavior test("user can checkout with valid cart", async () => { const cart = createCart(); cart.add(product); const result = await checkout(cart, paymentMethod); expect(result.status).toBe("confirmed"); });

坏测试则耦合内部结构——mock 内部协作者、测私有方法、断言调用次数/顺序、测名描述 HOW 而非 WHAT：

// BAD: Tests implementation details test("checkout calls paymentService.process", async () => { const mockPayment = jest.mock(paymentService); await checkout(cart, payment); expect(mockPayment.process).toHaveBeenCalledWith(cart.total); });

同义反复测试的对照同样来自 tests.md：

// BAD: Expected value is recomputed the way the code computes it const expected = items.reduce((sum, i) => sum + i.price, 0); expect(calculateTotal(items)).toBe(expected); // GOOD: Expected value is an independent, known literal expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);

Mock 纪律：只在系统边界 mock

tdd/mocking.md 进一步规定 mock 的边界：只在系统边界 mock（外部 API、数据库、时间/随机、文件系统），绝不 mock 自己写的类/模块/内部协作者/任何你能控制的东西。同时给出了两个「为可 mock 性而设计」的实操建议：

1. 依赖注入：外部依赖通过参数传入而不是内部 new 出来，例如把paymentClient作为参数传入processPayment(order, paymentClient)，而不是在函数内部new StripeClient(...)；
2. 优先 SDK 风格接口而非通用 fetcher：为每个外部操作提供独立函数（api.getUser(id)、api.createOrder(data)），这样每个 mock 只返回一种确定的形状、测试设置里没有条件逻辑、每个测试用到了哪些端点一目了然。

五、指令三拆解：类型检查与测试的节奏控制

第三条指令规定了验证节奏，它是 SKILL.md 中唯一的「频率」约定：

Run typechecking regularly, single test files regularly, and the full test suite once at the end.

• 定期跑类型检查（typechecking regularly）：保证类型层始终处于可编译状态，避免实现积压到最后一次性暴露大量类型错误。具体命令以项目自身的类型检查配置为准（TypeScript 项目通常为tsc --noEmit或 package.json 中约定的 typecheck 脚本）。
• 定期跑单个测试文件（single test files regularly）：与 TDD 的垂直切片节奏配合——每完成一个 slice，只跑当前涉及的单个测试文件，获得秒级反馈，而不是每次都跑全量套件拖慢循环。
• 最后跑一次完整测试套件（the full test suite once at the end）：收尾前的最终回归，确保所有切片合流后整体依然全绿。

这一「单文件快反馈 + 全量终回归」的节奏，正是为了让红绿循环保持轻量，同时守住最终交付的完整性。

六、指令四拆解：用 code-review 双轴评审收尾

实现完成后，implement 要求调用/code-review。完整的双轴评审协议在 code-review/SKILL.md 中定义，其核心是对HEAD与某个固定点（fixed point）之间的 diff 沿两条轴并行评审：

• Standards 轴：代码是否符合仓库文档化的编码标准（CODING_STANDARDS.md、CONTRIBUTING.md等），外加一组固定的 Fowler code smells 基线（Mysterious Name、Duplicated Code、Feature Envy、Data Clumps、Primitive Obsession、Repeated Switches、Shotgun Surgery、Divergent Change、Speculative Generality、Message Chains、Middle Man、Refused Bequest 共 12 项）；
• Spec 轴：代码是否忠实实现了源头 issue/Spec——缺失或部分实现的需求、未被要求的越界行为（scope creep）、看似实现实则错误的点，每条都要引用 Spec 原文。

两条轴以并行 sub-agents运行（互不污染上下文），diff 命令统一为git diff <fixed-point>...HEAD（三点式，即对比 merge-base），再以git log <fixed-point>..HEAD --oneline记录提交列表。最终聚合时两份报告分别在## Standards与## Spec标题下并列呈现，不做合并、不做跨轴重排——因为「代码符合所有规范但实现错了东西」（Standards pass, Spec fail）与「代码完全按 issue 做但破坏了项目约定」（Spec pass, Standards fail）是两种必须独立可见的失败。报告末尾只给一行总结：每轴的总发现数与每轴内最严重的问题。

需要说明的是：Spec 轴的溯源顺序是「commit message 中的 issue 引用 → 用户传入的路径 →docs/、specs/、.scratch/下的 Spec 文件」，若都找不到则询问用户；而 issue tracker 的配置由/setup-matt-pocock-skills提供（本仓库中对应 setup-matt-pocock-skills 目录下的 issue-tracker 文档）。

七、指令五拆解：提交到当前分支

Commit your work to the current branch.

这是 implement 的最后一步，措辞值得注意：提交到「当前分支」，而不是新建分支。也就是说 implement 假设分支管理（建分支、开 PR）发生在更早的规划阶段，执行者只负责在当前工作分支上把代码固化下来。这与 implement-spec（见下节）中「每个 implementer 子 Agent 在独立 worktree 独立分支上工作、再由 merger 合并到 PR 分支」的并行模式形成了串行/并行的对照。

八、并行变体：in-progress 的 implement-spec

仓库 skills/in-progress/implement-spec/SKILL.md 提供了一个标记为 in-progress 的并行化实现变体，它与 implement 的串行协议互补，核心差异在于：

• Tickets 是任务图而非步骤列表：票据之间是阻塞关系，任何时刻都存在一个可被领取的frontier；
• 实现子 Agent（implementer subagents）尽量后台并行运行，每个在自己的 worktree 和自己的分支上实现一张票据，完成后由merger subagent合并到统一 PR 分支；frontier 变化后再启动新票据的实现，从而最大化并发；
• 探索与实现分离：可先用 exploration subagent 产出 markdown 笔记（存放在仓库外的共享目录），让 implementer 专注实现而非探索；
• 全部票据完成后在 PR 分支上运行/code-review，用单个 implementer subagent 修完所有问题，标记 PR ready，最后清理所有 worktree。

该变体同样以「单分支单 PR 实现整个 Spec」为目标，适合超出一个 Agent 会话容量的大块工作；而 implement 本体则是适合常规规模任务的串行基线。两者共享同一收尾动作：code-review 之后再提交。

九、全景工作流与适用前提

综合上述技能，implement 所嵌入的完整规格化工作流可以概括为：

to-spec（综合会话产出 Spec，打 ready-for-agent 标签） → to-tickets（拆出带 blocking edges 的 tracer-bullet 垂直切片票据） → implement（预约定缝 → TDD 逐片实现 → 定期 typecheck/单测 → 全量回归） → code-review（Standards + Spec 双轴并行评审） → 修复评审问题 → 提交到当前分支

几点适用前提与限制，均以仓库现状为准：

• 调用前提：implement 是 user-invoked 技能（disable-model-invocation: true/allow_implicit_invocation: false），必须显式输入/implement；且调用前应已具备 Spec 或 Tickets 输入；
• seam 前提：测试只写在预先与用户确认的 seam 上，未经确认不得写测试；seam 相关词汇与设计纪律参见 codebase-design；
• 测试纪律：只在系统边界 mock、用独立字面量做期望值、按垂直切片推进，详见 tests.md 与 mocking.md；
• 分支前提：最终提交到当前分支，分支/PR 管理不属于 implement 的职责范围；
• 配置前提：issue tracker 与 triage 标签等前置配置需先通过 /setup-matt-pocock-skills 完成。

一句话总结：implement 不是「写代码」的笼统提示，而是一条「以预约定缝的 TDD 为推进引擎、以分层测试节奏为安全网、以双轴 code-review 为质量闸门、最终落盘当前分支」的严格协议——它把「把一个功能做出来」这件事，变成了每一步都有依据、每一条指令都有对应技能文档可查的可复现流程。

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills