Skill Learning

implement-spec

1. Bilingual SKILL.md

左右滑动可直接切换英文版与中文版；两种语言按段落自动对齐。英文中的蓝色虚线词语可点击查看解释。共标记 14 处。

You have been provided a spec. This spec should have , describing how to implement the spec.

The goal is a PR which on a single branch.

The tickets are . They are with between them. This means there is always which are ready to be grabbed.

Communication to and from subagents should be sparse. Communicate primarily through : to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers.

**Implementer subagents** should be run in the background where possible for .

## Steps

1. Read the spec and tickets. Read enough to understand the task graph.

2. (optional) Use an to conduct any exploration required by the tickets - relevant codebase files or external documentation. Ensure the can save files - it should save its markdown notes in , accessible by all future subagents. This lets **implementer subagents** focus on implementation rather than exploration.

3. Create a branch, and a draft PR. The PR should be marked as 'closing' the spec issue and tickets.

4. Use **implementer subagents** to implement each ticket. Each implementer subagent should , on its own branch.

5. Once an **implementer subagent** completes, merge its work to the PR branch with a **merger subagent**.

6. If this changes the **frontier** of available tickets, to work on the new tickets. This allows for .

7. Once all tickets are complete, run /code-review on the PR branch. Fix all issues raised by the code review in a single **implementer subagent**.

8. Mark the PR as ready for review.

9. Clean up all **implementer subagent** worktrees.

Source metadata

--- name: implement-spec description: "Implement a specification in code." disable-model-invocation: true ---

你已经获得了一份规格。这份规格应有关联的工单，用来描述如何实现该规格。

目标是在单一分支上通过一个 PR 实现整份规格。

这些工单不是步骤清单。它们是一个带有阻塞关系的**任务图（task graph）**。这意味着始终存在一组已经可以领取的工单**前沿（frontier）**。

与子智能体之间的沟通应保持精简。主要通过**上下文指针（context pointers）**沟通：指向规格、工单、研究笔记和先前提交。不要重复指针已经能够访问的信息。

只要条件允许，**实现者子智能体（Implementer subagents）**就应在后台运行，以实现**最大并发度（maximum concurrency）**。

## 步骤

1. 阅读规格和工单。阅读到足以理解任务图的程度。

2. （可选）使用一个**探索子智能体（exploration subagent）**开展工单所需的探索，例如相关代码库文件或外部文档。确保探索子智能体能够保存文件：它应把 Markdown 笔记保存在仓库外部、所有后续子智能体都能访问的目录中。这样，**实现者子智能体**就可以专注于实现，而不是探索。

3. 创建一个分支和一个草稿 PR。PR 应标记为将会“关闭（closing）”规格 issue 和相关工单。

4. 使用**实现者子智能体**实现每张工单。每个实现者子智能体都应在自己的 worktree 和自己的分支中工作。

5. 某个**实现者子智能体**完成后，使用一个**合并子智能体（merger subagent）**把它的工作合并到 PR 分支。

6. 如果这改变了可用工单的**前沿**，就启动更多**实现者子智能体**处理新就绪的工单。这样可以实现最大并发度。

7. 所有工单完成后，在 PR 分支上运行 `/code-review`。用一个**实现者子智能体**集中修复代码审查提出的全部问题。

8. 把 PR 标记为可供审查。

9. 清理所有**实现者子智能体**的 worktree。

Source metadata

--- name: implement-spec description: "用代码实现一份规格。" disable-model-invocation: true ---

Entry SHA-256: f703b5f41df9c2202e19540d203e0d5fc32613572a838a070136cc22e712b129

2. Why This Skill Is Clever

一句话核心机制

它把规格工单建模为带阻塞关系的任务图，持续从当前可执行前沿并发派发隔离的实现者，再由合并者汇流到一个 PR，最后统一代码审查和收尾。

触发与边界

直接来源： frontmatter 中的 disable-model-invocation: true 表示这是一项由用户显式调用的高影响工作流；输入前提是“已经提供规格”，并且规格拥有描述实现方式的关联工单。目标不是生成计划，也不是实现单张工单，而是在一个分支和一个 PR 中完成整份规格。

支持背景： agents/openai.yaml 设置 allow_implicit_invocation: false；skills/in-progress/README.md 将它标为 beta、user-invoked，并说明 in-progress 技能不随插件发布且可能变化。/code-review 是被调用的普通支持技能，不构成 wrapper 展开。

解释： 创建分支、draft PR、worktree、后台子智能体和合并都具有真实副作用，显式触发是合理安全边界。该流程假定执行环境能管理 Git worktree、PR 状态和多个有角色区分的子智能体；缺少这些能力时不能照搬实现细节。

信息架构 / 执行顺序

建立图模型：读取规格和工单，识别节点、阻塞边和当前可执行前沿，而不是把工单误读成线性步骤。
提前消除知识瓶颈：必要时由探索子智能体读取代码或外部文档，把共享笔记保存到仓库外部，让后续实现者直接消费。
先建立汇流目标：创建单一 PR 分支和 draft PR，并关联规格 issue 与工单，使所有并行工作拥有明确终点。
扇出并隔离：对前沿中的工单并发启动实现者，每个实现者拥有独立 worktree 和分支。
持续汇流与再调度：实现完成后由 merger 子智能体并入 PR 分支；每次前沿变化就启动新一批就绪工单。
集中质量门：全部工单完成后在汇总分支运行 /code-review，由一个实现者一次性修复全部问题。
显式完成：把 PR 从 draft 标记为 ready，并清理所有实现 worktree。

最巧妙的设计点

1. 用图而不是队列来理解工作

“not a list of steps ... a task graph”

直接来源： 技能首先纠正线性清单心智模型，再用阻塞关系定义可以并行的工作。并发不是靠随意多开智能体，而是由依赖图证明哪些工单此刻安全可做。

2. 把调度锚定在动态前沿

“there is always a frontier of tickets which are ready to be grabbed”

直接来源： frontier 把调度状态压缩成“当前可领取节点集合”。每次合并只需重新评估前沿，无需重新规划整张图；工作流因此可以逐步解锁并保持流水线饱和。

3. 探索与实现分离，减少重复读取

“save its markdown notes in a directory outside the repo”

直接来源： 可选探索者负责一次性整理事实，后续实现者通过共享笔记复用结果。笔记放在仓库外，既避免每个实现者重复调查，也避免临时研究材料混入产品提交。

4. 稀疏沟通依赖可追踪指针

“Communicate primarily through context pointers”

直接来源： 规格、工单、研究笔记和 commit 本身承担信息所有权，子智能体消息只传递定位线索和增量状态。这降低了长消息的上下文成本，也避免复制版本落后于事实源。

5. worktree 隔离与 merger 角色组成扇出/汇入结构

“Each implementer subagent should work in its own worktree, on its own branch.”

直接来源： 文件修改在独立 worktree 中并发发生，整合权限则集中到 merger 子智能体和 PR 分支。它把“并行生产”和“串行整合”拆成不同职责，减少多个实现者同时改写同一工作区的破坏性冲突。

6. 代码审查只在集成后的真实形态上进行

“Once all tickets are complete, run /code-review on the PR branch.”

直接来源： 最终审查针对已经汇流的 PR 分支，因此能发现跨工单接口、迁移顺序和集成行为的问题。之后用单个实现者集中修复，可避免审查阶段再次无序扇出。

防失败机制与 trade-off

明确不变量： 整份规格必须落在一个 PR 分支；工单按阻塞关系调度；每个实现者使用独立 worktree 和分支；完成结果经 merger 汇入；只有前沿变化后才继续派发；全部工单完成后必须运行 /code-review；修完问题才把 PR 标记为 ready；最后清理 worktree。

权衡与风险： 最大并发会增加 merge 冲突、资源占用和调度复杂度，尤其当工单边界不干净或阻塞关系遗漏时。context pointers 假定所有智能体具有同样的路径和读取权限；外部目录若不稳定，探索结果会失联。技能没有规定失败重试、合并冲突升级策略、测试门、并发上限、PR 创建失败或部分完成后的恢复协议。把所有代码审查问题交给一个实现者能保持修复一致性，但也可能成为尾部瓶颈。Beta 身份意味着这些缺口仍可能调整。

可迁移原则

先把工作依赖显式建图，再从就绪前沿派发并发任务。
把探索和生产分开，让共享证据只产生一次、被多次消费。
并行执行必须配套隔离工作区、独立分支和单一汇流点。
用指针连接可信事实源，只在消息中传递增量，不复制大段上下文。
在集成后的最终形态上设置统一质量门，并定义完成后的资源清理。

今日实践题

假设工单 A（数据库迁移）会解锁 B（写入路径）和 C（回填任务），而 D（监控面板）没有依赖：第一轮前沿应包含哪些工单，A 合并后你会如何重新派发，并用什么隔离与汇流规则避免相互覆盖？

Evidence note

任务图、阻塞关系、动态前沿、上下文指针、探索笔记、后台实现者、worktree、merger、统一代码审查和清理顺序都来自所选 SKILL.md。Beta 与不随插件发布来自 skills/in-progress/README.md，禁止隐式调用来自 agents/openai.yaml，两者仅作支持背景。关于图调度、单一事实源、扇出/汇入、瓶颈和可移植性的结论属于设计解释。

Source & provenance

Repository path: skills/in-progress/implement-spec/SKILL.md
Generated: 2026-08-28 15:02 Asia/Shanghai
Upstream commit: 6654f6b60cd9d5be8b54c6fafe44346dabeb3b76
Source: View on GitHub