forge-implement

实现变更

按照项目标准实现功能或修复问题。

输入

主要输入（$ARGUMENTS）：Issue 编号/URL、计划文件路径或自由文本描述。可选：-- <additional context>，用于提供执行指导。

无人值守模式： --unattended 会跳过计划审批，并在没有确认提示的情况下继续执行。

流程

第 1 步：了解工作内容

通过 状态报告报告 implementing。判断输入类型并提取需求。检测 Issue 跟踪系统提供方（参见 Issue 操作）。

• Issue — 使用项目的 Issue 跟踪系统获取信息（参见 Issue 操作）。解析标题、需求、验收标准、标签、子 Issue 和评论。若缺少标签，则添加标签。如果 Issue 有子 Issue，则将每个子 Issue 作为单独任务处理，并在完成后关闭。
• 计划文件 — 提取目标、需求、约束和验收标准。
• 自由文本 — 解析范围和约束。

如果需求过于模糊，或依赖信息不完整，以至于无法可靠地制定计划，请提出澄清问题；在无人值守模式下，则根据明确说明的假设继续执行。

第 2 步：规划方案

识别持久的架构决策——能够吸收变更而非暴露内部实现的数据模型、API 契约和模块边界（参见 深模块）。

对于复杂工作，委派代码库调研，以获得客观的答案：

调研（委派）

编写 3–7 个关于现有系统、模式和集成点的事实性问题。每个问题都应询问当前某项功能的运作方式；如果读者能从问题中猜出目标，就改写该问题。原样传递 Issue 中指向现有内容的线索（文件路径、包、库文档），绝不传递指向 Issue、PR 或变更规范的链接。委派给 forge-scout 子 Agent，该 Agent 只能接收问题和线索。如果不支持子 Agent，则阅读角色文件，并按照其中的规则回答每个问题。

**提供给子 Agent 的输入：**角色：forge-scout、调研问题、线索、代码库访问权限。
**预期输出：**每个问题提供一条事实性答案，并附上文件路径和代码引用。

如果运行时支持为每项任务单独选择模型，调研工作优先使用成本低、速度快的模型。

根据调研结果制定计划：

• 持久的架构决策
• 结构大纲——按垂直阶段划分；每个阶段涵盖所需的所有受影响层，并以验证步骤结束。第 1 阶段端到端验证正常路径；后续阶段每次只增加一个复杂维度。
• 要创建或修改的文件
• 范围边界（哪些内容不会变更）

通过 AskUserQuestion 提交计划。开始编码前须获得用户确认。在无人值守模式下：跳过 AskUserQuestion，直接继续。

第 3 步：创建功能分支

git fetch origin
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git rev-list --count origin/$DEFAULT_BRANCH..HEAD   # 0 on a non-default branch → a worktree tool prepared it; stay on it

否则，从已获取的默认分支创建分支，但不要切换到该分支——在默认分支已于其他位置检出的工作树中也能正常使用：

git checkout --no-track -b <TYPE>/<ISSUE_NUMBER>-<BRIEF_DESCRIPTION> origin/$DEFAULT_BRANCH

如果使用计划文件或自由文本（没有 Issue 编号），请使用描述性 slug：<TYPE>/<BRIEF_DESCRIPTION>。

第 4 步：实现

首先阅读 AGENTS.md。严格遵循项目约定。

按照 阶段执行 分阶段完成工作：第一阶段前进行预检验证；每个阶段内同时编写代码和测试；并设置阶段门槛——测试通过、没有新增的 lint/type 错误、提交一项逻辑变更——之后才能进入下一阶段。

发生偏离第 2 步计划的情况时，立即记录偏离内容及原因；PR 中应说明每一项偏离。

第 5 步：审查模式一致性

如果变更了某种模式（错误处理、组件结构、API 约定），请搜索所有其他使用旧模式的文件，并一并更新——审查模式的形态，而不只是查找字面字符串。参见 模式审查。

步骤 6：更新文档

如果行为或约定发生变化，请更新 docs/*.md 和 AGENTS.md。

步骤 7：运行最终质量检查

运行所有项目质量检查（从 AGENTS.md、项目文档或仓库脚本中查找）：

• Lint — 无违规
• 格式检查 — 无违规
• 类型检查 — 无错误
• 所有测试均通过
• 新增/修改代码的测试覆盖率 ≥ 90% — 运行项目的覆盖率工具。如果尚未配置覆盖率工具，请告知用户并提出配置方案。

修复问题并提交修复。

步骤 8：验证更改

运行应用并使用一次已更改的路径，再尝试一次失败场景，遵循 exercise 中的说明。在打开 PR 前，修复发现的问题，并为修复添加测试。

步骤 9：推送并创建 PR

git push -u origin <BRANCH_NAME>

使用符合 Conventional Commits 规范的标题以及 pr-body 中的正文创建 PR。原因说明取自关联 Issue 的问题描述；如果没有关联 Issue，则取自提交历史。无人值守模式下，将你据以继续操作的假设写在 Notes 下。有 Issue 时，请关闭该 Issue。

通过带引号的 heredoc 从 stdin 传入正文 — 内联的 --body "..." 会破坏多行文本、反引号和引号：

gh pr create --title "<TYPE>(<SCOPE>): <DESCRIPTION>" --body-file - <<'PR_EOF'
<PR body>
PR_EOF

步骤 10：总结

报告：分支名称、PR 链接、所做提交、更改的文件、新增的测试、更新的文档、验证结果、延期事项。

指南

• 先探索，再编码 — 在确定方案前先研究代码库
• 不确定时先询问 — 澄清总比实现错误好；无人值守运行时，应说明假设并继续操作
• 不要扩大范围 — 只实现所请求的内容，不做其他改动

相关技能

实现后： 使用 forge-reflect 在请求评审前进行自我审查。 单次调用： 使用 forge-ship 一步完成实现和评审。

示例用法

/forge-implement 123
/forge-implement 123 -- keep the diff minimal and prefer existing UI patterns
/forge-implement --unattended 123
/forge-implement docs/roadmap.md
/forge-implement add a dark mode toggle to the settings page