work-on-issues

处理 Issue

处理 Issue 分为三个阶段：

1. 跟踪器设置

通过 git remote -v 检测主机。将 $TRACKER 设置为 gh 或 glab。 术语：

• GitHub：pr / comment
• GitLab：mr / note

---

2. 阶段 1：获取与分类

1. 列出未关闭的 Issue：使用 gh issue list --state open --json number,title,labels 或 glab issue list -O json。
2. 筛选：仅保留主要 Issue（标题以 PRD: 或 feat: 开头）。自动/批量运行时跳过其他 Issue（但显式选择时可以处理）。
3. 选择：用户选择 Issue 编号或选择继续模式。
4. 预检查：
   • 验证 Issue 是否未关闭（已关闭则跳过）。
   • 通过 PRD 标签或标题前缀 PRD: 检测 PRD/Epic。跳过实现，并将其添加到 $PRD_TRACKER，以供自动关闭检查。
5. 读取详情：获取完整 Issue 视图和评论（gh issue view --comments / glab issue view --comments）。
6. 解析父级 PRD：查找拥有此 Issue 的 PRD——搜索未关闭的 PRD Issue（PRD: 前缀或 PRD 标签），查看其正文是否引用了 #<number>，或者使用跟踪器的子 Issue/阻塞关系链接——并获取其正文和评论。此上下文会传递给阶段 2 的实现者。
7. 分配与添加标签：标记为 in-progress（添加 in-progress 标签并移除 ready-for-agent 和 needs-triage）。

---

3. 依赖关系与链接

解析 Issue 正文中的 ## Blocked by（匹配 #42 或完整 Issue URL），以构建 DEPS[issue] = [blockers]。 如果可行，创建跟踪器原生链接（例如，使用 is_blocked_by 的 GitLab API /links，或 blocked_by=true 的 GitHub 子 Issue API）。否则使用文本引用。

---

4. 阶段 2：实现（一次处理一个主要 Issue）

仅使用子 Agent。 每个 Issue 都由派发的子 Agent 实现——无论是单 Issue 模式、批量模式还是继续模式，均如此。协调器负责获取、分类、派发和提交；它绝不自行编辑文件、编写代码或运行测试。如果某个 Issue 小到似乎不值得派发，那它恰恰仍应交给子 Agent 处理。

1. 创建 Worktree：

   git worktree add .claude/worktrees/issue-<number> -b work-on-issue-<number>
   

2. 复制 .env 文件：将 .env 和 .env.* 文件复制到 Worktree 目录。
3. 使用 haiku 模型派发子 Agent（位于 .claude/worktrees/issue-<number> 中）： 子 Agent 除了此提示词外没有任何上下文——未在此处明确写出的约束，对实现者而言就不存在。填写以下所有内容；像“遵循 PRD #3”这样的 AC 行并不起作用，除非内联 PRD 的实际约束。 提示词规范：

   Implement issue #<number>: <title>.
   Issue body (verbatim):
   <full issue description — summary, acceptance criteria, everything in the body>
   Issue comments (verbatim, in order, or "none"):
   <all comments, attributing each to its author>
   Parent PRD context (#<PRD number>: <PRD title>, or "none"):
   <full PRD body and its comments, or "no comments">
   Branch/Worktree: work-on-issue-<number> in .claude/worktrees/issue-<number>
   API/best-practices: Search via `context7`, `/brightdata-plugin:search`, `/search`, or WebSearch before writing code if unsure.
   Stuck on errors: If 2+ consecutive failures, you MUST research via `context7`, `/brightdata-plugin:search`, `/search`, or WebSearch first (they are available) to find the correct API/approach, then retry. Only escalate after researching.
   Parallel subtasks: Decompose & dispatch sub-agents if tasks are independent (no shared files/dirs).
   Post-implementation: Check output, diff, and run tests and run `/find-mismatch` skill on modified files only. If the programming language is typescript or javascript, run `npx fallow audit` (Make sure to install `fallow` if not present). If errors, fix and re-run tests.
   Output: Summary, find-mismatch fixes, tests run, and commit hash.
   Commit format: `fix: resolve #<number> — <short description>`
   

4. 提交：确保在 Worktree 中提交更改（fix: resolve #<number> — <desc>）。

---

5. 阶段 3：提交与关闭

1. 创建 PR/MR：使用 “Closes #” 链接到 Issue。
2. 自动合并：立即合并（压缩提交并删除分支）。
3. 评论：发布实现摘要。
4. 关闭：移除分类/进度标签（如 in-progress），添加 closed，并关闭 Issue。
5. 传播 .env 文件：在移除 Worktree 之前，将已修改的环境文件复制回主工作目录：

   WT=.claude/worktrees/issue-<number>
   for wtf in "$WT"/.env "$WT"/.env.*; do
     [ -f "$wtf" ] || continue
     base=$(basename "$wtf")
     if [ ! -f "$base" ] || ! cmp -s "$base" "$wtf"; then
       cp "$wtf" "$base" && echo "Propagated $base back"
     fi
   done
   

6. 清理：

   git worktree remove .claude/worktrees/issue-<number>
   git branch -d work-on-issue-<number>
   

---

6. PRD 自动关闭

关闭子 Issue 后，检查 PRD_TRACKER 中的所有 PRD。阅读 PRD 描述/链接。如果所有引用的子 Issue（如 #42）都已关闭，则关闭该 PRD 并从 PRD_TRACKER 中移除。

---

7. 子任务并行化

如果满足以下条件，派发的子 Agent 会将 Issue 拆分为子任务：

• 修改互不重叠的文件/文件夹。
• 输出相互独立（没有顺序依赖）。 如果子任务共享文件、存在严格的流程依赖，或需要先完成配置，则按顺序执行。

子任务提示词规范：

子 Agent 也会以全新上下文启动——每个子任务提示词都应内联与该子任务相关的上下文（与主派发遵循相同规则）。

Implement subtask for issue #<number>: <title>.
Subtask: <details>
Issue context (verbatim excerpts bearing on this subtask): <issue body / comments / parent-PRD constraints>
Working Directory: .claude/worktrees/issue-<number>
Scope: Modify <MAY_MODIFY>, DO NOT modify <MUST_NOT_MODIFY>.
Compile/Lint errors: If 2+ consecutive failures or any 3rd party dependency issues, research via `context7`, `/brightdata-plugin:search`, `/search`, or WebSearch first (they are available) to find the correct API/approach, then retry. Check Reference Directories (<RefDirs>) to align configurations.
Post-implementation: Run `/find-mismatch` skill on modified files, auto-fix.
Verification: Run relevant tests. Return summary, modified files, test results.

---

8. 执行模式

批处理与后续模式

1. 获取所有未关闭的问题，并筛选出主要问题（PRD:、feat:）。
2. 从问题正文中解析 DEPS 映射，设置正式链接。
3. 显示进度表：| Issue | Title | Type | Blocked By | Agent | Status | PR/MR |
4. 循环：
   • 选择下一个没有未解决阻塞项的问题。跳过已关闭或 PRD 问题。
   • 派遣子 Agent 到工作树中执行任务。
   • 运行验证 -> 合并 PR/MR -> 关闭 -> 传播环境配置 -> 清理 -> 检查 PRD。
   • 重新评估依赖关系。重复执行。
5. 完成后重新获取所有未关闭的问题（外层循环），以发现新出现的主要问题。仅当没有未关闭的主要问题或用户中断时退出。

单问题模式

通过同一阶段 2 的子 Agent 派遣流程，仅端到端执行所选问题。跳过依赖图处理。

---

9. 标签与辅助工具

标签	含义	颜色
PRD	父级跟踪问题	#0075CA
in-progress	进行中	#E4E669
ready-for-agent	可供 Agent 处理	#0E8A16
closed	已由 AI 关闭／已完成	#5319E7

要应用标签，请尝试直接更新。如果找不到标签，请先创建（例如，为 in-progress 设置颜色 #E4E669），然后重试。

---

10. 边缘情况

• 没有 CLI：直接使用 API，或请用户安装 gh／glab。
• 没有 Fallow：请用户安装 fallow 以进行 JS/TS 安全审计。
• 冲突／循环：报告循环依赖，跳过受影响的问题。
• 外部阻塞项：将未关闭的外部问题视为未解决的阻塞项。
• API 链接失败：改用文本引用。
• 没有主要问题：告知用户，并询问是否要处理非主要问题。
• 环境文件被 gitignore 忽略：移除工作树之前，必须将环境文件传播回来，以便在后续运行中保留。不要提交机密信息。