CI失敗向け Claude Code：小さな修正と回帰テストのプロンプト

CI失敗で何がまずくなるか（AIが推測するとき）

CIの失敗は通常、謎めいているわけではありません。ログには停止した箇所、失敗したコマンド、エラーメッセージが示されています。スタックトレース、ファイルと行番号付きのコンパイラエラー、どのアサーションが失敗したかを示すテストレポートなどがあれば良いサインです。時には「expected X, got Y」のような差分スタイルの手がかりや、lint、build、migrate database のような明確に失敗したステップが出ることもあります。

問題は、人（とAI）がログを背景ノイズとして扱いがちなことです。長いログを貼って「修正して」と頼むと、多くのモデルは最後の意味ある行を読む代わりに馴染みのある説明に飛びつきます。エラーが一般的に見える（module not found、timeout、permission denied）ほど推測は悪化し、大掛かりな書き換え、不要な依存追加、あるいは「全部アップデートしてみて」といった実際の失敗に合わない答えになります。

目的は「なんとか通す」ことではありません。もっと単純です：

• 失敗出力を読む。
• 失敗したステップを通すための最小の変更を特定する。
• それ以外はなるべく同じままにする。

実務では「最小の修正」は多くの場合、次のいずれかです：一箇所の数行のコード変更、足りないインポートや間違ったパス、CI環境に対して明らかに間違っている設定値、あるいは大規模な設計変更ではなく偶発的な破壊的変更を元に戻すことです。

フォローアップのテストも重要です。一度CIが通ったからといって再発を防げるわけではありません。失敗がエッジケース（null入力、タイムゾーン、丸め、権限）に起因するなら、修正前には失敗し修正後に通る回帰テストを追加してください。これにより一度きりの救出がガードレールになります。

助けを求める前に集めるべきもの

多くの悪い修正はコンテキスト不足から始まります。最後の赤い行だけを貼ると、モデルは前に何が起きたか推測せざるをえず、その推測が大掛かりな書き換えにつながります。

誰かが失敗を追えるだけの詳細を提供することを目指してください。可能なら逐語で次を含めます：

• 最初のエラー行から終わりまでの完全な失敗ログ（最終スタックトレースだけでなく）。
• CIが実行した正確なコマンド（例：go test ./..., npm test, flutter test, golangci-lint run）。
• エラーに出てくるファイルパスと関連する設定（テスト設定、リンター設定、ビルドスクリプト）。
• 最近何が変わったか：PRの差分要約、依存関係の更新、CI設定の編集。
• フレークかどうか：もしあれば数回の失敗と一回の成功のログ。

制約を平易に書いてください。もし最小修正が欲しいならその旨を明記します：リファクタ禁止、振る舞い変更は必要な場合のみ、パッチは失敗した箇所に限定、など。

単純な例：依存関係の更新後にリンターが通らなくなった。最初の警告から貼り、CIが使ったコマンドと、変更したパッケージのバージョンを一つだけ添えれば、1行の設定調整や小さなコード修正を提案するのに十分です。リポジトリの半分を再フォーマットするような回答を避けられます。

コピー＆ペーストできる構成は通常これで十分です：

CI command:

Failing output (full):

Recent changes:

Constraints (smallest fix, no refactor):

Flaky? (runs attached):

失敗出力を読ませるためのプロンプト規則

モデルがCIの不具合を外す原因は、プロンプトが推測を許してしまうことです。モデルに失敗出力を使って「証拠を示す」ように強制し、そのうえで通すための最小変更にコミットさせるのがあなたの仕事です。

モデルの誠実性を保つルール

証拠と小さな計画を要求してください。良いプロンプトは次の5点を強制します：

• CIログから使うべき正確な失敗行（エラー、スタックトレース、file:line）を引用し、「私はこれらの行を使っています」と明言すること。
• 1文での診断（曖昧表現を避ける）。
• 1〜3の編集で最小パッチ計画を示し、触る正確なファイル名を挙げること。
• 無関係な変更を避けること（フォーマット、リネーム、リファクタ、依存更新など）――あなたが承認しない限り行わないこと。
• 不確かな点と、診断を確定するために必要な唯一の追加情報を列挙すること。

不確実性は問題ではありません。隠された不確実性が時間を浪費します。

コピー用プロンプト断片

質問の先頭にこれを貼ってください：

Use ONLY the evidence in the CI output below.
1) Quote the exact failing lines you are using.
2) Give ONE sentence: the most likely cause.
3) Propose the smallest fix: 1-3 edits, with file paths.
4) Do NOT do formatting/renames/refactors or "cleanup".
5) List uncertainties + the one extra detail that would confirm the diagnosis.

ログに「expected 200, got 500」や user_service.go:142 のようなスタックがあるなら、この構成はその関数と小さなガードやエラーハンドリングの変更へ応答を導きます。設計のやり直しではなく、まずは症状を直す方向です。

CI失敗用のコピペ可能なプロンプトテンプレート

最速の成果は、ログの引用を強制し、制約内に留め、不足があれば止めるプロンプトから生まれます。

You are helping me fix a CI failure.

Repo context (short):
- Language/framework:
- Test/build command that failed: <PASTE THE EXACT COMMAND>
- CI environment (OS, Node/Go/Python versions, etc.):

Failing output (verbatim, include the first error and 20 lines above it):
<PASTE LOG>

Constraints:
- Propose the smallest possible code change that makes CI pass.
- Do NOT rewrite/refactor unrelated code.
- Do NOT touch files you do not need for the fix.
- If behavior changes, make it explicit and justify why it is correct.

Stop rule (no guessing):
- If the log is incomplete or you need more info (missing stack trace, config, versions, failing test name), STOP and ask only the minimum questions needed.

Your response format (follow exactly):
1) Evidence: Quote the exact log lines that matter.
2) Hypothesis: Explain the most likely cause in 2-4 sentences.
3) Smallest fix: Describe the minimal change and why it addresses the evidence.
4) Patch: Provide a unified diff.
5) Follow-up: Tell me the exact command(s) to rerun locally to confirm.

Then, write ONE regression test (or tweak an existing one) that would fail before this fix and pass after it, to prevent the same failure class.
- Keep the test focused. No broad test suites.
- If a test is not feasible, explain why and propose the next-best guardrail (lint rule, type check, assertion).

二つの細かい点がやり取りを減らします：

• 正確な失敗コマンドと最初のエラーを含めること（最後の要約だけではない）。
• 失敗が複数ある場合は、まずどれを直すかを明示すること（通常はログの最も早い実際の失敗）。

最小修正に誘導してリライトを避ける方法

時間を失う最速の方法は、5つのことを一度に変える「クリーンアップ」変更を受け入れることです。事前に「最小」を定義してください：失敗したジョブが通る最小の差分で、リスクが最も低く検証が速いもの。

単純なルールが有効です：まず症状を直し、その後で本当に必要なら大きなリファクタを検討する。ログが1ファイル、1関数、1つの欠けたインポート、または1つのエッジケースを指しているなら、そこを狙ってください。「ついでに」編集は避けます。

本当に選択肢が必要なら、安全性を重視した「最小の修正」と、最速の「最小の修正」を2つだけ求めてください。選択肢は2つに絞るのが鍵です。

また、ローカル検証はCIと同じコマンドで行うよう要求してください。そうすれば数分で確認できます：

# CIが実行するのと同じユニットテストターゲットを走らせる
make test
# またはCIで使う正確なスクリプト
npm test

大きな変更を提案されたら、こう問い返してください：「問題のアサーションを直す最小のパッチを示して、無関係なフォーマットやリネームは含めないでください。」

再発を防ぐフォローアップテストの促し方

テストなしの修正は、同じ問題が再び起きないという賭けです。常に、修正前に失敗し修正後に通るフォローアップテストを依頼してください。

「良い」テストの要件を具体的に示します：

• どこに置くか、どの名前にするか、どんな振る舞いをカバーするか、なぜこれが再発を防ぐのかを短く説明する。

追加の指示例：

• 1つの回帰テストを書いて、現在の main ブランチでは失敗し、修正後に通るようにする。
• 失敗クラスを対象にし、単一の壊れた行だけをテストするのではないこと。
• テストの配置：<path or folder>、命名規約：<your convention>。
• ビルド/リンターの問題ならルールを強化するなどのチェックを追加する。
• なぜこのテストが同様のバグを将来検出できるかを2～3文で説明する。

例：APIハンドラーが空文字のIDを受け取るとパニックするケース。単にその行のテストではなく、空文字・空白・不正フォーマットなど複数の不正IDを検証するテストを求めます。最小の修正は 400 を返すガード句で、フォローアップテストは複数の無効IDに対する期待を検証して、将来のパースの掃除で同じ問題が戻らないことを保証します。

プロジェクトにテストの慣習があるならそれに従うよう指示し、ないなら近傍のテストに倣って可読で最小限のテストを書くように依頼してください。

再利用できるステップバイステップワークフロー

1) 失敗をそのまま渡す

エラーを含むログと、その上20～40行を貼り付けてください。失敗した正確なコマンドと主要な環境情報（OS、ランタイムのバージョン、重要なフラグ）も添えます。

その後、モデルに「何がどう失敗したか」を平易な英語（またはチームの言語）で要約してもらい、出力中のどの行がそれを証明するかを指させてください。ログを引用できなければ、十分には読んでいません。

2) まず最小のパッチを要求する

失敗したコマンドが通るための最小変更を提案させ、リファクタは拒否します。適用前に次を列挙させてください：

• 触るファイル名
• どの振る舞いが変わるか
• 何を変えないか

3) 同じコマンドを再実行し、ループを短く保つ

パッチを適用してCIと同じコマンドを再実行します。まだ失敗するなら新しい失敗出力のみを貼って繰り返します。コンテキストを小さく保つと応答が集中します。

4) 失敗クラスの回帰テストを追加する

グリーンになったら、修正前に失敗し修正後に通る1つの回帰テストを追加します。ターゲットを絞った1テストにしてください。

その後、テストを含めた状態で同じコマンドを再実行して、単にエラーを隠しただけでないことを確認します。

5) 綺麗なPRパッケージで終える

短いコミットメッセージとPR説明を求めます：何が失敗したか、何を変えたか、どう検証したか、どのテストが再発を防ぐかを含めるとレビューが速くなります。

現実的な例：失敗出力から修正とテストへ

よくある失敗：ローカルでは動いていたのに小さな変更でCIが落ちるケース。GoのAPIで、ハンドラーが日付のみ（2026-01-09）を受け入れるようになったが、コードがRFC3339のみをパースしていた場合の例です。

貼るべき短い抜粋の例：

--- FAIL: TestCreateInvoice_DueDate (0.01s)
    invoice_test.go:48: expected 201, got 400
    invoice_test.go:49: response: {"error":"invalid due_date: parsing time \"2026-01-09\" as \"2006-01-02T15:04:05Z07:00\": cannot parse \"\" as \"T\""}
FAIL
exit status 1
FAIL	app/api	0.243s

このログに対して、証拠を使うことと最小修正とテストを強制するプロンプトを使います：

You are fixing a CI failure. You MUST use the log to justify every claim.

Context:
- Language: Go
- Failing test: TestCreateInvoice_DueDate
- Log snippet:
<PASTE LOG>

Task:
1) Quote the exact failing line(s) from the log and explain the root cause in 1-2 sentences.
2) Propose the smallest possible code change (one function, one file) to accept both RFC3339 and YYYY-MM-DD.
3) Show the exact patch.
4) Add one regression test that fails before the fix and passes after.
Return your answer with headings: Evidence, Minimal Fix, Patch, Regression Test.

良い応答はパースレイアウトの不一致を指摘し、parseDueDate のような1関数（例えば invoice.go）を小さく変えて RFC3339 をまず試し、失敗したら 2006-01-02 のフォーマットにフォールバックする、という最小修正を示します。

回帰テストは防御的です：due_date: "2026-01-09" を送って 201 を期待するテストを書けば、将来フォールバックを消すとCIが同じ失敗で止まります。

時間を無駄にする一般的なミス（と回避法）

問題を切り取りすぎると時間を失います。CIログはノイズが多いですが、有用な部分は通常最終エラーの上20行程度にあります。

落とし穴の一つは最後の赤い行だけを貼ること（例：exit 1）。実際の原因はもっと前にあるかもしれません（環境変数の欠如、スナップショットの失敗、最初にクラッシュしたテスト）。対処法：最初のエラー行とそれより上のウィンドウを含めてください。

別の時間泥棒はモデルに「ついでに綺麗にしておいて」と許すことです。フォーマットや依存更新、リファクタはレビューしにくく副作用を生みます。対処法：最小の変更をロックし、無関係な変更は拒否します。

注意すべきパターン：

• 最後のエラー行だけを貼る：最初のエラーとコマンドを含める。
• 依存や無関係ファイルを変えさせる：最小差分のみを要求する。
• CIコマンドで検証しない修正を受け入れる：同じコマンドで再現確認する。
• バグが戻っても通るテストを書く：古いコードで失敗し、新コードで通るテストを要求する。
• フレークと実際の回帰を混同する：非決定性を取り除いてから扱う。

フレークを疑うならリトライで隠すのではなく、ランダム要素を削除してください（固定時刻、シード化されたランダム、分離された一時ディレクトリ）。

プッシュ前の簡単チェック

プッシュ前に短い正気のチェックを行ってください：変更が本物で最小で再現可能かを確認するのが目的です。

• 証拠：説明は正確な失敗行を引用しているか？
• 範囲：変更は必要な範囲だけに限定されているか？
• 因果関係：この変更でなぜ失敗→成功に反転するのか説明があるか？
• 再現：同じCIコマンドを実行しているか？
• 回帰：新しいテストは修正前に失敗し、修正後に通るか？

最後に、元の失敗ジョブより少し広めのセット（例：lint とユニットテスト）を走らせて、修正が他のターゲットを壊していないことを確かめてください。

このワークフローを習慣にする次のステップ

これを継続的に時間節約にするには、プロンプトと応答フォーマットをチームのプロセスにしてください。目的は再現可能な入力、再現可能な出力、そして「何でも直した」ように見せかける一時的な修正を減らすことです。

優れたプロンプトをリポジトリスニペットとして保存し、チームチャットにピン留めします。ワークフローの骨子：

• 失敗はタイプ別（lint, unit, integration, packaging, deploy）にラベリングする。
• 繰り返されるラベルには、それを早期に検出するテストやチェックを1つ追加する。
• 危険な実験はすぐ戻せるようにしておく（ロールバック可能にする）。

チャット中心のワークフローが好みなら、Koder.ai内で同じ修正とテストのループを回し、実験中はスナップショットを使い、準備ができたらソースをエクスポートして通常のリポジトリにマージできます。