implement-issue

实施 Issue

通过 team-executor 端到端交付 GitHub issue。优先选择稳健方案，而非快速方案——执行 Agent 不受人力时间、速度或估算约束；风险和一致性才是重点。

捆绑资源

文件	用途
references/workflow.md	详细的逐步工作流和边缘情况
references/team-composition.md	根据项目技术栈选择规划 Agent 和技能分配的方法

输入

• GitHub issue 编号（纯整数 → 当前仓库）、owner/repo#N 标识，或完整的 https://github.com/.../issues/N URL。
• 用户消息中的可选标记：“decide” / “make all decisions” / “no confirmation” → 跳过 TL;DR 确认环节，自主选择最稳健且符合惯例的方案。

输出

• 命名为 issue-<N>-<slug> 的功能分支（如果检测到仓库分支惯例，则遵循该惯例）。
• team-executor 生成的计划文档，位于 docs/plans/issue-<N>/ 下。
• 在 issue 上发表评论，详细记录已商定的实现方案，确保新的团队能够据此执行。
• 功能分支上的实现提交。
• 与该 issue 关联的拉取请求（Closes #N）。

工作流

0. 前置条件：必须已安装 team-executor

在执行任何其他步骤之前，确认能够访问 team-executor。按以下顺序检查：

1. ~/.claude/skills/team-executor/SKILL.md
2. .claude/skills/team-executor/SKILL.md（项目）
3. ./team-executor/SKILL.md（原地运行时的当前仓库）
4. /mnt/skills/team-executor/SKILL.md
5. skills-lock.json 中的 team-executor 条目

如果均未找到：停止并警告用户。说明检查过的路径，并指出此技能用于驱动 team-executor 进行规划和执行。询问用户是否要：

• (a) 安装它（npx skills add thatjuan/agent-skills --skill team-executor）并继续，或
• (b) 中止。

等待用户明确确认。未经确认不得继续。缓存解析出的路径，供后续步骤使用。

1. 解析 issue

• 解析用户输入。如果是纯整数，则将其视为当前仓库中的 issue 编号。
• 运行 gh issue view <N> --json number,title,state,body,labels,assignees,milestone,url,author,comments 并阅读全部内容，包括评论——先前的讨论可能已经限定了方案。
• 如果 state != "OPEN"：
  • 向用户报告当前状态（已关闭 / 已合并 / 已锁定）。
  • 询问用户要 (a) 重新打开，(b) 仍继续并创建新分支，还是 (c) 中止。等待用户选择。
• 检测仓库惯例：阅读 CLAUDE.md、AGENTS.md、CONTRIBUTING.md，查看近期分支中的命名提示（git branch -a --sort=-committerdate | head -20），以及提交信息风格（git log --oneline -20）。

2. 创建功能分支

• 从仓库的默认分支创建分支（通过 gh repo view --json defaultBranchRef -q .defaultBranchRef.name 确认）。
• 分支名称：issue-<N>-<kebab-title>，截断至 60 个字符；除非仓库惯例另有要求。
• 先运行 git fetch origin；从 origin/<default> 创建分支。

3. 确定实现路径

Issue 说明了 要做什么。此技能（配合 team-executor）决定 如何实现 ——除非 Issue 正文明确规定了实现方式。

如果 Issue 包含明确的实现指导（例如具体文件、API、代码模式，或编码人员可以照章执行的清单）：

• 跳过规划团队。将 Issue 正文作为计划，继续执行第 5 步。

否则：通过 team-executor 派出规划团队。

• 阅读 team-executor 技能：~/.claude/skills/team-executor/SKILL.md（若安装在项目中，则为 ./team-executor/SKILL.md）。
• 按照 team-executor 第 1 阶段（规划）——步骤 1–8——将 Issue 正文和评论作为「整理输入」的内容。
• 如何为此项目的技术栈选择 Agent 并分配技能，请参阅 references/team-composition.md。

通过 team-executor 为此 Issue 派出的每个架构、编码和审查 Agent，都会分配 software-engineer 技能——这是基础工程层。无论其上是否叠加了任何技术栈/SDK 技能，该技能都会要求实现达到架构师、开发者和审查者的标准（三种视角）以及八项标准。具体的技能与 Agent 映射请参阅 references/team-composition.md。

传递给每个规划 Agent 提示词的约束：

实现工作将由其他编码 Agent 完成。人工时间、速度和工作量估算均不适用——不要因为人类觉得耗时就回避更稳健的方案。考虑风险、安全性、可维护性以及与现有项目规范的一致性。优先选择最稳健、工程质量最高，且能利用此仓库现有工具、样式和组件的方案。现有模式适用时，不要引入并行模式。

4. 确认路径（或自主决定）

• 如果用户的请求要求你自行决定（例如「决定」、「做出所有决定」、「无需确认」、「自主执行」），则跳过确认。从规划结果中选择最稳健且符合规范的方案并继续。
• 否则，向用户提供高度概括的 TL;DR：用 3–6 个要点说明选定方案、主要权衡、受影响的部分和风险。等待确认或指示调整。
• 确认后（或自主决定后），按照 team-executor 步骤 8，将最终计划写入 docs/plans/issue-<N>/execution-plan.md。

5. 在 Issue 上评论实现方案

通过 gh issue comment <N> --body-file <path> 发布评论，内容包括：

• 方案——用 1–2 段说明选定的路径。
• 选择此方案的原因——说明与考虑过的替代方案相比的权衡。
• 范围——涉及的文件/模块、新增文件和迁移。
• 步骤——按顺序列出，详细到一支新团队可以毫无歧义地执行（文件路径、函数签名、库调用、测试预期）。
• 范围之外——说明此 PR 不会处理的事项。
• 验证——说明审查者应如何验证（要运行的命令、手动检查）。

此评论是持久的执行说明，必须独立完整。

6. 执行

启动 team-executor 第 2 阶段（执行）——步骤 9–12——并向 Agent 提供：

• Issue（通过 gh issue view <N> 查看），了解原始需求。
• 已发布的 Issue 评论 / docs/plans/issue-<N>/execution-plan.md，了解选定方案。
• 项目上下文（CLAUDE.md、AGENTS.md、README、相关源文件）。

执行 Agent 将自主工作：独立的步骤并行执行，存在依赖的步骤则按顺序执行。

7. 验证

• 运行仓库中的测试套件、代码检查器、类型检查器和构建流程（按项目实际情况）。通过 package.json 脚本、Makefile、pyproject.toml 等文件检测可用项目。
• 对于 UI 更改：启动开发服务器并实际测试功能；如果无法进行浏览器验证，需明确说明。
• 创建 PR 前，通过有针对性的后续 Agent 修复失败项。

8. 打开拉取请求

• 提交并推送功能分支。
• 使用 gh pr create，并包含：
  • 标题：简短，不超过 70 个字符，符合仓库的提交消息规范。
  • 正文部分：摘要（项目符号列表）、方案（链接到问题评论）、测试计划（检查清单）、Closes #。
• 将 PR URL 返回给用户。

故障处理

情况	响应
未安装 team-executor	停止。警告用户，显示检查过的路径，提供安装命令，并等待确认。
未找到问题／无权访问	原样显示 gh 错误；请用户核实编号／身份验证。
问题已关闭／锁定	继续前先与用户确认意图（见步骤 1）。
未安装 gh 或尚未通过身份验证	停止；指导用户安装 gh／运行 gh auth login。
当前目录不在 git 仓库内	停止；说明情况并询问用户应在哪个目录运行。
规划团队提出相互冲突的建议，项目负责人无法协调	在 TL;DR 中说明冲突；请用户作出决定。
执行后测试失败	启动有针对性的修复 Agent；绝不在 CI 阻塞性检查失败时打开 PR。
工作树中已有未提交的更改	停止；询问用户如何处理（暂存／提交／中止）。

相关技能

• software-engineer — 工程 SME（架构师／开发者／审查者视角，基础工程层），每个编码／架构／审查 Agent 都会分配该技能。技术栈／SDK 技能会叠加在此基础上。
• team-executor — 此技能所驱动的规划与执行引擎。
• commitpush — 如果用户希望使用其安全检查，则用于提交步骤。
• git-github-cli — 分支和 PR 操作的 Git/GitHub CLI 参考。