work-on-issues

イシューへの対応

イシューへの対応は、次の3つのフェーズで行います。

1. トラッカーの設定

git remote -v でホストを検出します。$TRACKER を gh または glab に設定します。 用語：

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

---

2. フェーズ 1：取得とトリアージ

1. オープン中のイシューを一覧表示：gh issue list --state open --json number,title,labels または glab issue list -O json を使用します。
2. フィルタリング：メインイシュー（タイトルが PRD: または feat: で始まるもの）のみを残します。自動実行／バッチ実行では、それ以外はスキップします（明示的に選択された場合は対応可能です）。
3. 選択：ユーザーがイシュー番号または続行モードを選択します。
4. 事前確認：
   • オープン中であることを確認します（クローズ済みの場合はスキップします）。
   • ラベルが PRD、またはタイトルに PRD: プレフィックスが付いている場合は、PRD／エピックとして検出します。実装はスキップし、自動クローズ確認用に $PRD_TRACKER に追加します。
5. 詳細の確認：イシューの詳細とコメントを取得します（gh issue view --comments ／ glab issue view --comments）。
6. 親 PRD の特定：このイシューを所有する PRD を検索します。オープン中の PRD イシュー（PRD: プレフィックスまたは PRD ラベル）を検索し、本文で #<number> を参照しているものを探すか、トラッカーのサブイシュー／ブロック元リンクを使用します。その本文とコメントを取得します。このコンテキストはフェーズ 2 で実装担当に渡します。
7. 割り当てとラベル付け：in-progress ラベルを付け、ready-for-agent と needs-triage を削除して、進行中としてマークします。

---

3. 依存関係とリンク

イシュー本文の ## Blocked by を解析し（#42 またはイシューの完全な URL に一致）、DEPS[issue] = [blockers] を構築します。 可能であれば、トラッカーのネイティブリンクを作成します（例：is_blocked_by を指定した GitLab API /links、または blocked_by=true を指定した GitHub のサブイシュー API）。できない場合は、テキスト参照を使用します。

---

4. フェーズ 2：実装（メインイシューを1件ずつ）

サブエージェントのみを使用します。 シングルイシューモード、バッチモード、続行モードのいずれでも、すべてのイシューはディスパッチされたサブエージェントが実装します。オーケストレーターは取得、トリアージ、ディスパッチ、提出を行いますが、自身でファイルを編集したり、コードを書いたり、テストを実行したりすることはありません。ディスパッチするほどでもないほど小さく見えるイシューも、必ずサブエージェントに依頼します。

1. ワークツリーを作成：

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

2. .env ファイルをコピー：.env および .env.* ファイルをワークツリーディレクトリにコピーします。
3. haiku モデルを使用してサブエージェントをディスパッチ（.claude/worktrees/issue-<number> 内）： サブエージェントは、このプロンプト以外のコンテキストを持たない状態で開始します。ここに明記されていない制約は、実装担当にとって存在しないのと同じです。以下の各項目をすべて埋めてください。「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. コミット：ワークツリー内で変更がコミットされていることを確認します（fix: resolve #<number> — <desc>）。

---

5. フェーズ 3：提出とクローズ

1. PR／MR を作成：Closes #<number> を使ってイシューにリンクします。
2. 自動マージ：すぐにマージします（スカッシュしてブランチを削除します）。
3. コメント：実装の概要を投稿します。
4. クローズ：トリアージ／進行状況のラベル（in-progress など）を削除し、closed を追加してイシューをクローズします。
5. .env ファイルを反映：ワークツリーを削除する前に、変更された環境ファイルをメインの作業ディレクトリにコピーします。

   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 の自動クローズ

サブイシューをクローズした後、PRD_TRACKER 内のすべての PRD を確認します。PRD の説明／リンクを読みます。参照されているすべてのサブイシュー（#42 など）がクローズ済みの場合、PRD をクローズし、PRD_TRACKER から削除します。

---

7. サブタスクの並列化

ディスパッチされたサブエージェントは、次の場合にイシューをサブタスクに分割します。

• 重複しないファイル／フォルダーを変更する。
• 独立した成果物である（順序への依存がない）。 同じファイルを共有する場合、厳密なフロー依存関係がある場合、または先に設定が必要な場合は、順次実行します。

サブタスクのプロンプト仕様：

サブエージェントも新しいコンテキストで開始するため、各サブタスクのプロンプトには、そのサブタスクに関係するコンテキストを明記します（メインのディスパッチと同じルールです）。

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 の課題はスキップします。
   • サブエージェントをワークツリーに割り当てます。
   • 検証を実行 → PR/MR をマージ → クローズ → 環境を反映 → クリーンアップ → PRD を確認します。
   • 依存関係を再評価します。繰り返します。
5. 完了後、未解決の課題をすべて再取得し（外側のループ）、新しいメインの課題を取り込みます。未解決のメインの課題がなくなるか、ユーザーが中断するまで終了しません。

単一課題モード

フェーズ 2 と同じサブエージェントの割り当てを使用して、選択した課題のみを最初から最後まで実行します。依存関係グラフの処理はスキップします。

---

9. ラベルとヘルパー

ラベル	意味	色
PRD	親の追跡課題	#0075CA
in-progress	作業中	#E4E669
ready-for-agent	エージェントの作業準備完了	#0E8A16
closed	AI によってクローズ済み／完了	#5319E7

ラベルを適用するには、まず直接更新を試みます。ラベルが見つからない場合は、先に作成してから再試行します（例：in-progress の色は #E4E669）。

---

10. エッジケース

• CLI がない場合：API を直接使用するか、gh／glab のインストールをユーザーに依頼します。
• Fallow がない場合：JS/TS のセキュリティ監査用に fallow をインストールするようユーザーに依頼します。
• 競合／循環：循環依存関係を報告し、影響を受ける課題をスキップします。
• 外部ブロッカー：未解決の外部課題は未解決のブロッカーとして扱います。
• API リンクの失敗：テキストによる参照にフォールバックします。
• メインの課題がない場合：ユーザーに通知し、メイン以外の課題を処理するかどうか尋ねます。
• 環境ファイルが gitignore 対象の場合：実行間で状態を保持するには、ワークツリーを削除する前に環境ファイルを反映する必要があります。シークレットはコミットしないでください。