bug-iterate

バグの順次対応

複数のバグ報告に対して、順番に対応するループです。ユーザーとの進め方はシンプルです。調査し、提案し、待ち、その後に実行します。バグごとにこれを繰り返します。

基本ルール：ユーザーがそのバグを明示的に承認するまで、バグのコードを絶対に編集しないでください。バグ N の承認は、バグ N+1 には適用されません。熱意から承認を推測してはいけません。承認の言葉を待ってください。

2 つのモード

• 即時モード（デフォルト）： 承認されたバグを 1 件ずつ修正してコミットしてから、次のバグに進みます（バグごとにフェーズ 4 を実施）。
• バッチモード（先に相談、後で修正）： ユーザーが、まずすべての修正について 1 件ずつ相談し、その後、最後にすべてをまとめて修正することを希望しています。通常は、新しい「最終エージェント」セッションで実行します。トリガーとなるフレーズ：「すべての修正について先に相談する」「その後、まとめて対応する」「最終エージェントがすべて修正する」。バッチモードでは：
  1. バグごとに、フェーズ 1～3 を通常どおり実行します（調査 → カード → 判定）。フェーズ 4 は記録に置き換えます。コードには触れず、議論での修正を反映した判定済みの修正内容を引き継ぎドキュメントに追記します。
  2. 引き継ぎドキュメントは .claude/bug-iterations/{YYYY-MM-DD}-{slug}.md に保存します。バッチモード開始時に作成し、バグの一覧全体を記入して、判定のたびに更新します。これは最終エージェントにとって唯一の信頼できる情報源です。バグごとに、次の情報を記載する必要があります。ステータス（agreed／revised／dropped／already-fixed）、ファイルと行番号を含む根本原因、リポジトリごとの合意済み修正手順、根拠の参照先（ログクエリ、テスト結果、再現出力、ファイルと行番号）、テストの期待値。最終エージェントは議論の内容を記憶していないため、ドキュメントは単体で完結している必要があります。
  3. 最後の判定後、ドキュメントを完成させます（実行順序、バグ間の相互作用、検証計画）。その内容から最終エージェント用のプロンプトを作成します（チーム用プロンプトを希望する場合は、agent-team-prompt-builder スキルを使用します）。
  4. バッチモードの依頼前に修正済みのバグは、そのまま修正済みとしておきます。最終エージェントが再度対応しないよう、コミット SHA とともに already-fixed としてドキュメントに記録します。

---

ステップ 0：バグ一覧を集める

バグ報告を見つけます。通常、報告は次のいずれかにあります。

• このセッションでの以前のアシスタントの発言（デバッグや調査の報告など）。
• ユーザーが貼り付けたメッセージ。
• チケットや Issue の URL（Notion、Linear、GitHub など）。必要に応じて取得します。

バグごとに短いタイトルを付けて、番号付きの一覧を作成します。開始前に計画をユーザーに伝えます。

Bug plan:
  1. <short title> — <repo>
  2. <short title> — <repo>
  3. <short title> — <repo>
Starting with Bug 1.

後で反復全体を簡単に見つけられるように、実行開始時点を記録します（セッションマーカーやメモの 1 行など）。

一覧が不明瞭、または複数の解釈が可能な場合は、確認の質問を 1 つ してから開始します。

---

ループ — バグごと

バグごとに、次の 4 つのフェーズを繰り返します。フェーズを飛ばしてはいけません。フェーズを統合してはいけません。

フェーズ 1 — 調査

後で各バグの作業を簡単に見つけられるように、このバグの開始時点を記録します（セッションマーカーやメモの 1 行など）。

実際の根拠を集めます。バグに応じて、次のように対応します。

• 関連するコードパスを読みます（grep から推測した内容ではなく、実際のファイル内容を確認します）。
• バグに本番環境での特徴がある場合は、本番ログを取得します。
• 「何かが変わった」ことが問題の場合は、git の履歴（git log、git blame）を確認します。
• 該当する場合は、ツリーの状態や DB と照合します。
• 何かを主張する前に、実際の信頼できる情報源を読みます。上流からの報告や監査での指摘は手掛かりであり、証明ではありません。引用ごとに正確な行番号を記録し、ユーザーに見える被害が実際にあることを確認します（与えられた入力に対してシステムが意図どおりに動作しているなら、それはバグではありません）。

要約で述べるすべての主張に、ログエントリ、ファイルと行番号、ツール呼び出しの結果、またはデータ値を根拠として示す必要があります。根拠を示せない場合は、主張してはいけません。

フェーズ 2 — サマリーカード

次の形式でユーザーに報告します。まず問題点を示し、次に証拠、その後に原因と修正を示してください。ユーザーは修正を判断する前に、背景と証拠を確認します。簡潔にまとめますが、分量を減らすために証拠を省いてはいけません。

すべてのカードのヘッダーに、進捗を示す Bug N of M を必ず表示してください。ユーザーが残りの件数を常に把握できるようにします。

## Bug N of M — <title>
`<severity>` · <pattern> · <repo>

**① What went wrong:** <1–3 plain sentences — what the system actually did and the user-visible harm>

**② Evidence:** <bullets, each a REAL citation: log line, tool result, file:line, or repro output. No "likely"/"probably" in place of a citation. Note reproduction status if reproduced.>

**③ Cause:** <root cause, with file:line>

**④ Suggested fix:**
- Bullet (what changes, which file)
- Which repo: <repo> (a run may span multiple repos)

**Not in scope:** <what you're deliberately NOT touching — usually other bugs in the list or known follow-ups>

Approve, deny, or revise?

カードの質は証拠次第です。実際のログ、コード、再現結果から問題点を示せない場合は、送信する前にさらに調査してください（誤った問題の提示はユーザーの時間を浪費し、信頼を損ないます）。

バグが誤検出（FALSE POSITIVE）だと考える場合でも、必ず提示してください。①が実際のバグではないことを示す証拠となるようカードを作成し、判断（却下／維持）はユーザーに委ねます。自信がある場合でも、決して独断でバグを取り下げないでください。取り下げを含め、すべてのバグをユーザーが判断します。自動で取り下げるのは、自動修正と同じ失敗パターンです。ユーザーから判断を奪ってしまいます。「1件ずつ」とは、ユーザーが順番に各件を判断するという意味です。

その後は停止してください。ファイルを開かず、コードの作成を始めず、「念のため」の変更も準備しないでください。ツールの使用をやめてください。

判断を求める際は、通常のチャットテキストを使ってください。AskUserQuestion ツールは使わないでください。 この UI には質問と選択肢しか表示されず、上のカードが表示されないため、ユーザーは情報がないまま判断することになります。メッセージの末尾を Approve, deny, or revise? として、返答を待ちます。選択肢だけで必要な情報がすべて伝わる自己完結型の選択（修正方針をどちらにするか、重複チケットをどう扱うか、デプロイするかなど）には AskUserQuestion が適しています。ただし、バグの判断を求める際には使わないでください。

フェーズ 3 — 判断を待つ

ユーザーの次のメッセージを次のように解釈します。

ユーザーの発言	対応
approve / yes / go / yup / ok / 👍	フェーズ 4 に進みます
deny / nah / strip / skip / no	次のバグに進みます。誤って何かをコミットしていた場合は、元に戻します（「元に戻す」を参照）
その他	「修正」として扱います。質問や異議に回答し、修正版のサマリーカードを送り、再び返答を待ちます

質問された場合は、回答して修正版のサマリーカードを送ります。「話し合いながら、とりあえず修正を始める」ことはしないでください。このスキルが防ごうとしているアンチパターンです。

フェーズ 4 — 修正とコミット

承認されたら、次の手順に従います。

1. このセッションで初めてファイルを編集する場合は、ファイルに触れる前に、プロジェクトのコーディング標準や規約を記したドキュメントがあれば読みます。
2. 提案した内容に絞って変更します。スコープ外のものは、こっそり追加するのではなく、リストに新しいバグとして追加します。
3. 既存のテストを拡張します。同じモジュールをカバーするテストが既にある場合、新しいテストファイルをむやみに増やさないでください。該当するテストスイートを実行し、失敗があればコミットする前に修正します。
4. 作業中のブランチでコミットします。承認されたバグごとに別々のコミットを作成し、黙ってブランチを切り替えないでください。
5. プロジェクトで使用されている共著者情報やトレーラーの規約に従って末尾を締めくくる、HEREDOC 形式のコミットメッセージを使用します。
6. ユーザーから頼まれない限り、プッシュしないでください。多くの環境ではプッシュによってデプロイが実行されます。準備ができたら、ユーザーがプッシュ／デプロイします。
7. プロジェクトで変更ログやメモリファイルを管理している場合は、先頭に1行追加します。日付、リポジトリ、コミット SHA、変更内容と理由を具体的に記した一文を含めます。後で一連の作業を簡単に再構成できるよう、イテレーション内のバグ番号を記載します（例：「 修正ストリームの Bug 3 of 7」）。
8. ユーザーへのフッターメッセージ：Bug N/M done. Next: <title of bug N+1>.

その後、次のバグに取りかかるため、フェーズ 1 に戻ります。

---

誤って適用した修正を取り消す

ユーザーが、バグをコミットした後に（先走ってしまった場合、またはユーザーの考えが変わった場合に）そのバグを否定した場合：

1. 対象のリポジトリで git log --oneline -3 を実行し、そのコミットが最新であることを確認します。
2. git reset --hard HEAD~1 を実行して、そのコミットを取り消します。コミットがプッシュされていない場合にのみ実行してください。git status -sb で確認します。すでにプッシュされている場合は、履歴を書き換える前にユーザーに確認してください。
3. 追加していた場合は、プロジェクトの変更ログ／メモファイルから該当する行を削除します。
4. 簡潔なメッセージで取り消したことを伝え、次のバグに進みます。

プッシュされていないコミットを reset --hard で問題なく取り消せる場合は、新しいコミットを作成する git revert を使わないでください。

---

作業の完了

最後のバグの後：

1. 最終的な集計を送ります：

   Done. <N> applied, <M> stripped, <K> skipped.
   Commits:
     - <repo> <sha> — <title>
     - <repo> <sha> — <title>
   

2. 話し合いの中で出てきたフォローアップ（「これは別途対応する」とユーザーが言った項目や、反復作業中に見つかった新しいバグ）を列挙し、漏れがないようにします。
3. デプロイを提案しないでください。ユーザーがデプロイを希望する場合は、そう伝えてくれます。

---

やってはいけないこと

• 「効率化」のために、複数のバグをひとつの編集やコミットにまとめないでください。承認されたバグごとに、個別のコミットを作成します。
• バグ修正のついでに、隣接するコードをリファクタリングしないでください。たとえ「すぐそこ」にあっても対象外です。対象外の項目は、次のバグとして扱い、便乗させないでください。
• フェーズ 1 の内部手順を逐一説明しないでください。ユーザーに見えるのはフェーズ 2 です。ツール呼び出しの合間の調査状況の説明は、最大 1 文にしてください。
• すでに 5 件のバグを修正していて、パターンが固まったと感じても、フェーズ 3 を省略しないでください。待つことがこのスキルの要点です。
• フェーズ 2 の途中でユーザーが訂正した場合（「やっぱりバグ 3 はいったん飛ばして」など）、もう一度確認を挟む必要はありません。了解したことを伝えて先に進みます。

反パターン

ユーザー：「この 5 件のバグに取り組みましょう」 Claude：バグ 1 を調査し、概要を送る ユーザー：「承認します」 Claude：修正してコミットし、次にバグ 2 を調査して概要を送り、さらに概要を書きながらバグ 2 の編集も開始する ユーザー：「いや、それは取り消して」 Claude：取り消さなければならなくなる

待つ理由：すでに編集を始めた Claude は、作業を完了させようとする傾向があり、編集を始めた後に送る概要は、始める前に送る概要よりも正直さに欠けます。この確認のゲートによって、概要をありのままに保てます。