name: implement-spec description: "用代码实现一份规格说明。" disable-model-invocation: true
第 28 课 / implement-spec
用任务图组织并行实现与集成
这个实验性技能把整份规格实现为一个分支上的 PR，各任务由独立工作区的执行者处理。
还不清楚 Skill、Agent、安装和调用？先读 从零开始的6节入门课。
实验性技能
作者将它放在 in-progress，未作为稳定插件内容推广。先理解原理，实际使用前核实版本和依赖。
在关系图中查看 implement-spec 与其他技能的关联 →
一 / 读这一课之前
先把必要的概念讲清楚
这份实验性技能负责协调多项实施任务。你要先理解任务图和依赖，再理解为什么各实现者需要独立目录、合并以后还要整体检查。
下面是老师补充的入门说明；原作者的要求保留在中英对照正文中。所有例子均为帮助理解而构造的教学情境。
issue / ticket｜问题或任务工单
跟踪一项需求、缺陷、调查或实施任务的记录，通常有标题、正文、状态和引用。issue 和 ticket 在这些文档里经常都指工单，具体含义由上下文决定。工单写着“已完成”只是状态声明，还需要相应证据支持。
frontier｜当前可推进的事项集合
任务存在先后依赖时，前置条件已满足、现在能处理的那些事项。先决定是否登录，才能决定收藏记录如何归属用户；配色可能不受这个决定影响，可以先讨论。前沿不是所有未完成事项，更不是凭直觉挑一个开始做。
worktree｜同仓库的独立工作目录
Git 可以让同一仓库在多个目录各自检出不同分支。多个 Agent 因而能分别编辑自己的文件副本，减少同时改同一工作目录的混乱。它不自动消除逻辑冲突，合并后仍需验证两个修改是否能一起工作。
Git、commit、branch｜版本与分支
Git 记录项目随时间的变化；commit 是一次有标识的修改记录；branch 是一条可继续发展的工作线。你可在功能分支试做收藏能力，验证后再合入主分支。保存了文件不等于已提交，提交了也不等于已推到服务器或已上线。
PR / pull request｜合并评审请求
把一条分支的修改交给他人检查，并请求合入目标分支的协作对象。PR 通常包含改了什么、为何修改、验证结果和代码差异。草稿 PR 表示还在做；“可评审”表示可以检查；合并完成也不自动等于部署完成。
CI｜持续集成检查
把修改提交到共享流程时，自动运行测试、类型检查等约定检查，尽早发现集成问题。绿灯表示配置的检查通过，不代表所有需求都正确；红灯也可能由环境故障导致，应看具体证据。需要先检查“配置了什么”，才能解释绿灯的意义。
context pointer｜上下文资料指引
告诉 Agent 在什么条件下去读哪份材料的短指引。例如“新增或修改数据写入时，先读权限规则文档”。它同时承担地址与触发条件两项作用。只有“见文档”太模糊，可能找不到或不知道何时需要；一股脑放入所有内容又会占用上下文。
二 / 中英全文对照与精讲
读原文，理解每一步为什么这样做
左右内容按小节对应；窄屏先中文、后英文。两种语言均完整展示，对应讲解紧接在小节之后。译文传达原文要求；老师讲解补充概念、原因、例子与适用边界。
中文译文English · 英文原文
name: implement-spec description: "Implement a specification in code." disable-model-invocation: true
你已经收到一份规格说明。这份规格应该关联若干工单，由这些工单说明如何把规格落实为代码。
最终目标是得到一份 PR，也就是一份可以交给他人审查的代码变更请求。这份 PR 应在同一个分支上包含整份规格要求的实现。
这些工单并不是一张只能从第一项做到最后一项的步骤清单。它们组成的是一张任务关系图（task graph），图中记录了哪些任务必须等另一些任务完成后才能开始。
因此，在工作的任一阶段，都有一组前置条件已经满足、可以领取的工单。原文将这组当前可执行任务称为 frontier。
与子 Agent 来回沟通时，信息应尽量简洁。主要通过**资料位置引用（context pointers）**传递背景：告诉它规格在哪里、工单在哪里、研究笔记在哪里，以及需要查看哪些先前提交。
如果某项信息已经可以从这些引用中读取，就不要再把同一份内容重复发送一遍。
条件允许时，让实现子 Agent 在后台运行，使互不阻塞的任务尽可能并行。
You have been provided a spec. This spec should have tickets associated with it, describing how to implement the spec.
The goal is a PR which implements the entire spec on a single branch.
The tickets are not a list of steps. They are a task graph with blocking relationships between them. This means there is always a frontier of tickets which are ready to be grabbed.
Communication to and from subagents should be sparse. Communicate primarily through context pointers: 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 maximum concurrency.
老师讲解 · 对应上方原文 · 含教学举例
任务图不是一张按编号逐条执行的清单
这段解决的是多个 Agent 怎样共同推进一个完整需求的问题。 关键不在于同时启动多少个 Agent，而在于它们是否知道自己能做什么、必须等谁，以及成果怎样合在一起。
1. task graph：把任务之间的先后条件画清楚。 假设要为学习网站增加个人收藏，同时调整阅读字号：
| 工单 | 要完成的结果 | 必须先等谁 |
|---|---|---|
| A | 系统能识别当前用户 | 无 |
| B | 把收藏保存到当前用户下面 | A |
| C | 阅读页面可以调整字号 | 无 |
A 和 C 可以同时开展。B 需要知道当前用户是谁，因此必须等待 A。这里的“任务图”记录的是这种真实依赖，不是单纯把编号排成一列。
2. frontier：目前已经能够开始的那组任务。 一开始是 A 和 C。A 完成并合入共同分支后，B 才进入可执行集合。这个集合会随着进展而变化，所以调度者需要反复检查，而不是一次发完任务后就不再关注。
3. context pointer：告诉执行者去哪里读取准确资料。 例如工单写明“先读收藏规格和用户身份接口说明”，比主 Agent 给每个人各说一版需求更容易保持一致。所谓“指针”在这里通常就是路径、链接或提交引用，不需要把它理解为编程语言里的内存地址。
资料必须真实存在，并且接手者能够访问。给出一个只在另一台电脑上存在的路径，并没有完成有效的信息传递。
4. 并行的前提是确实互不阻塞。 两个任务如果都在改变同一份核心约定，就可能并不独立。例如一个把课程编号改叫 courseId，另一个继续按 lessonId 读取，即使各自做完，也可能无法配合。先确定共同约定，再安排并行，才能让速度转化为有效进展。
步骤
-
阅读规格说明及关联工单，读到足以理解整个任务关系图，以及任务之间的前置依赖为止。
-
这一步可选：如果工单需要先调查相关代码或外部资料，就安排一位负责探索的子 Agent。确保它有保存文件的能力，并把 Markdown 调查笔记写到仓库之外、后续所有子 Agent 都能访问的目录。这样，负责实现的子 Agent 就可以把精力集中在实现上，而不必重新调查同样的内容。
-
创建一个分支和一份草稿 PR。设置 PR 与规格工单、实现工单之间的关闭关联，使 PR 合并时能够关闭这些对应工单。
-
安排负责实现的子 Agent 执行各张工单。每位实现者都应在自己的 worktree 工作目录中，使用自己的分支工作。
-
一位实现者完成后，再让负责合并的子 Agent 将这份成果合入承载 PR 的分支。
-
如果这次合并使其他工单的前置依赖得到满足，就启动更多实现子 Agent，领取这些刚刚可以开始的任务。这种安排使互不阻塞的工作能够尽量并行推进。
-
所有工单都完成以后，在 PR 分支上运行
/code-review。再由一位实现子 Agent 集中修复代码审查提出的全部问题。 -
将 PR 从草稿状态改为可以正式审查的状态。
-
清理所有实现子 Agent 使用过的 worktree 工作目录。
Steps
-
Read the spec and tickets. Read enough to understand the task graph.
-
(optional) Use an exploration subagent to conduct any exploration required by the tickets - relevant codebase files or external documentation. Ensure the exploration subagent can save files - it should save its markdown notes in a directory outside the repo, accessible by all future subagents. This lets implementer subagents focus on implementation rather than exploration.
-
Create a branch, and a draft PR. The PR should be marked as 'closing' the spec issue and tickets.
-
Use implementer subagents to implement each ticket. Each implementer subagent should work in its own worktree, on its own branch.
-
Once an implementer subagent completes, merge its work to the PR branch with a merger subagent.
-
If this changes the frontier of available tickets, kick off more implementer subagents to work on the new tickets. This allows for maximum concurrency.
-
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.
-
Mark the PR as ready for review.
-
Clean up all implementer subagent worktrees.
老师讲解 · 对应上方原文 · 含教学举例
独立实现、集中合并，最后验证整体行为
1. worktree 解决“各自在哪里修改”的问题。 可以把它理解为同一个 Git 仓库中的独立工作目录。每位实现者在自己的目录和分支上改代码，减少把别人尚未完成的内容混进自己工作的机会。
2. 合并解决“怎样汇成一个结果”的问题。 一个实现者完成工单后，合并角色把这份改动加入承载整项需求的共同分支。只有共同分支真的拿到了前置任务的成果，依赖它的后续任务才能可靠地继续。
例如 A 已经在自己的目录中完成身份识别，但 B 的工作目录仍没有这些代码，B 不能仅凭“A 说完成了”就假定接口已经可用。成果的位置和合并状态都需要明确。
3. 整体检查解决“合在一起还能否工作”的问题。 隔离工作目录只能减少互相覆盖，不能保证接口兼容。假设保存收藏的代码返回 courseId，而展示列表的代码按 lessonId 读取，各自的小范围检查可能通过，合并后的用户路径仍会失败。因此，全部工单完成以后，还要在共同分支上审查、修复并检查整体结果。
4. PR 状态说的是协作进度。 草稿 PR 表示工作正在推进；改为 ready for review，表示已经准备好交给审查者。它不等于已经合并，更不等于网站已经上线。
最后清理 worktree 是收尾动作。教师补充的前提是：确认需要保留的成果已经进入应有分支，再清理目录。多 Agent、worktree 和 PR 都需要实际工具环境支持，读完 Markdown 本身不会自动赋予普通聊天这些能力。
三 / 你问我答
先作答，再看参考思路
Q1 · 理解
用自己的话说明：它解决什么问题，完成后会留下什么？
请各用一句话回答。若它只做规划或解释，不要把“已开发”“已部署”写成产物。
Q2 · 判断
为什么多个 worktree 可以减少冲突，却不能消除集成问题？
我已思考，查看参考思路
它隔离工作目录，避免直接互相覆盖；但逻辑、接口和最终合并仍可能冲突，必须进行集成和验证。
Q3 · 追问
原文中哪条要求在你的环境下可能不成立？
说出具体一句及其前提，例如工具不可用、资料缺失、已有项目约定冲突，或它只是作者偏好。把你的答案带回课堂，我们据此继续讨论。
课堂回传格式：第 28 课 / 我的理解 / Q2 回答 / 仍不理解的原句。这里是阅读教材；实时问答在我们的对话中进行。
四 / 应用场景讨论
把方法放进一个具体情境
教学案例：资料读取与阅读界面可在接口确定后并行，最终仍需验证它们能连通。各自的局部测试通过，不能替代集成结果。
边界与容易误读的地方
这是 Beta。父 PR 声明关闭任务，并不意味着任务已被真实验收；遇到合并冲突和失败不能盲目启动更多写者。
讨论后再实践：先判断上述情境是否适用，再选择真实任务。现在无需安装、运行命令或修改现有项目。