Claude Code を使った Prompt-to-PR ワークフロー：小さな差分

Prompt-to-PRが大きな一発プロンプトより優れている理由

大きな一発プロンプトは、数十ファイルに渡る関係のないリファクタや、理解する時間がないままの大きな変更を生みがちです。出力が技術的に正しくても、何がどう変わったのか把握しづらいためレビューがリスクに感じられます。

小さな差分はそれを防ぎます。変更が限定的かつ焦点を絞っていると、数分で読み切れて誤りを早期に検出でき、意図せぬ箇所を壊しにくくなります。レビュワーは小さなPRをより信頼し、マージが早く、コメントのやり取りも少なくなります。

Prompt-to-PRはシンプルなループです:

• 1つの小さな変更を、境界を明確にして要求する。
• 差分を確認し、意図に合っているか確かめる。
• 通常のチェック（テスト、lint、ビルド）を実行する。
• 何か失敗したら、正確なエラーとコンテキストで再プロンプトする。
• マージ準備が整うまで繰り返す。

このリズムは、失敗を最後の驚きではなく迅速なフィードバックに変えます。Claude Code にバリデーションルールの調整を頼むならその1つのルールだけに留めてください。テストが失敗したら、失敗出力を貼り付けてテストを通すための最小の修正を頼み、モジュール全体を書き換えさせないでください。

ひとつだけ変わらないことがあります: 最終的なコードはあなたが責任を持ちます。モデルは早く打つローカルのペアプログラマだと扱い、自動操縦機だとは考えないでください。何を入れるか、何を残すか、いつPRを開くのが安全かはあなたが決めます。

リポジトリとローカルのペアリング準備

クリーンなベースラインから始めてください。ブランチが古い、あるいは既にテストが失敗している状態だと、あらゆる提案が推測になってしまいます。最新をpullしてリベースやマージを行い、現在の状態が健全であることを確認してから依頼しましょう。

「ローカルペアプログラマ」設定とは、Claude Code がリポジトリ内のファイルを編集する一方で、ゴール・ガードレール・すべての差分はあなたが管理する、という意味です。モデルはコードベースを知らないので、ファイル、制約、期待される振る舞いを明確に示してください。

最初のプロンプトの前に、どこでチェックを実行するか決めておきます。ローカルでテストを実行できれば数分でフィードバックが得られ、反復が小さく保てます。一部のチェックがCIでしか走らない（特定のlintルール、長いテストスイート、ビルド工程など）なら、どのタイミングでCIに頼るかを決めておき、毎回の小さな変更後に待つことがないようにしてください。

簡単な事前確認:

• ブランチを更新し、アプリがビルドまたは起動することを確認する。
• ローカルで速いチェックを実行する（lint、ユニットテスト、型チェック）。
• CI専用のチェックとその所要時間を把握する。
• 問題を再現できるか、欠けている機能をはっきり見られるか確認する。
• 変更を簡単に元に戻せるようにしておく（クリーンな状態、小さなコミット）。

作業中は小さなスクラッチパッドを開いておき、"API変更なし"、"後方互換を保つ"、"Xモジュールのみを触る" といった制約や決定事項を書き留めておいてください。テストが失敗したら、正確な失敗メッセージもそこに貼ります。そのスクラッチパッドが次のプロンプトの最高の入力になり、セッションが逸れるのを防ぎます。

小さな差分につながるプロンプトの書き方

小さな差分は意図的に狭く書かれたプロンプトから始まります。マージ可能なコードへの最短ルートは、レビューに1分で目を通せる1つの変更であって、理解に1時間かかるリファクタではありません。

良いプロンプトは1つのゴール、1つのコード領域、1つの期待結果を示します。変更がどこに入るか（ファイル、フォルダ、モジュール）指示できないと、モデルは推測し、差分が広がります。

差分を小さく保つためのプロンプトの形:

• ゴール: 変更したい単一の振る舞い。
• 場所: 触っていいファイルやコンポーネント。
• 制約: 何を変えてはいけないか。
• 受け入れ条件: 「完了」の定義。
• 差分サイズ: 動作するために最小限の変更を明示的に要求する。

境界が秘密兵器です。"ログインバグを直して" ではなく、何を維持すべきかを明記してください: "APIの形を変えない"、"公開関数の名前を変えない"、"フォーマットのみの編集禁止"、"新しい依存は避ける"。それによりペアプログラマにどこで工夫すべきでないか伝えられます。

変更がまだ不明瞭なら、コードを求める前に計画を求めてください。短い計画は作業をステップに分け、最初の小さな一手を承認する機会を与えます。

Goal: Fix the null crash when rendering the profile header.
Location: src/components/ProfileHeader.tsx only.
Constraints: Do not change styling, props, or any exported types.
Expected outcome: If user.name is missing, show "Anonymous" and no crash.
Diff constraint: Minimal diff. No refactors. No unrelated formatting.
If unclear: First reply with a 3-step plan, then wait for approval.

チームで作業するならレビュー制約も加えてください: "~30行以内の変更に抑える" や "どうしても必要でない限り1ファイルのみ"。これにより差分のスキャンが容易になり、何かが失敗したときの次のプロンプトが鋭くなります。

各反復に適した作業単位の選び方

各ループは1つの小さく検証可能な変更に集中させてください。ゴールを1文で説明でき、どのファイルが変わるか予測できるならそれは適切なサイズです。

良い作業単位の例: 1つの実行パスのバグ修正（再現手順とガード付き）、単一の振る舞いに対するテスト修正、振る舞いを保つリファクタ（名前変更、関数抽出、重複除去）、エラーメッセージやバリデーションルールの改善など。

各ループに時間制限を設けてください。10〜20分で明確なプロンプトを書き、差分を適用し、簡単なチェックを実行するには十分です。20分を過ぎてまだ探索中なら、作業単位を小さくするか調査モード（ノート、ログ、失敗テスト）に切り替えてそこで止めてください。

始める前に「完了」を定義してください:

• 変更は意図したファイルと振る舞いの範囲内であること。
• 1つのチェックで動作が確認できること（テスト、lint、簡単な実行）。
• 新しい警告やノイズの多いフォーマット変更がないこと。
• 差分を2文で説明できること。

スコープが拡大し始めたら早めに止めてください。"ついでに"と言い始めたら次の反復が見つかっただけです。それはフォローアップとして切り出し、現在の小さな差分をコミットして続けましょう。

チェックを走らせる前に差分をレビューする

テストやビルドを実行する前に、レビュワーの目で差分を読みましょう。ここでワークフローがクリーンに保たれるか、あるいは「なぜあのファイルを触った？」と感じるかが決まります。

まずClaude Codeに、変更点を平易な言葉で要約するよう依頼してください: 触ったファイル、振る舞いの変更点、変えていないこと。もしモデルが明確に説明できないなら、差分はおそらくやり過ぎです。

次に自分でレビューします。まず範囲をざっと確認し、次に意図に沿って読む。探すべきはスコープの逸脱: 無関係なフォーマット、余計なリファクタ、シンボルの名前変更、要求していない変更などです。

簡単な事前チェック:

• 変更ファイルは要求通りか？
• 付随的な編集（空白の増減、無関係なリファクタ）はないか？
• 要求していない新しい振る舞いは入っていないか？
• 新しい依存や設定変更には正当な理由があるか？
• レビュワーが他の5つのファイルを読まずに理解できるか？

差分が予想より大きければ、テストで何とかしようとせずにロールバックして小さなステップを再要求してください。例えば: "まず失敗するテストだけ追加して。リファクタはなし。" 小さな差分は失敗を解釈しやすくし、次のプロンプトを正確にします。

小さな変更ごとにチェックを実行する

小さな差分が効果を発揮するのは、すぐに検証する場合だけです。目標は短いループです: 少し変えて、少しチェックして、文脈が新しいうちに間違いを捕まえること。

まずその変更で「壊れていること」を検出できる最速のチェックを実行してください。フォーマットやimportを変えたならlintや整形を最初に。ビジネスロジックを触ったら対象ファイルやパッケージの最小限のユニットテストを走らせる。型やビルド設定を編集したら素早くコンパイルをする。

実用的な順序:

• Lintやフォーマット。
• 変更箇所に関係するターゲットユニットテスト。
• ビルドや型チェック。
• 基本が通ったら遅いスイート（統合、E2E）。

何かが失敗したら、修正する前に2つを記録してください: 実行した正確なコマンドとフルのエラー出力（そのままコピー）。その記録が次のプロンプトを特定させ、"まだ失敗する"ループを防ぎます。

範囲を狭く保ってください。lintとテストの両方が失敗したら、まずlintを直して再実行し、その後テストに取り掛かる。"簡単な掃除"とクラッシュ修正を同時にやらないでください。

チェックが通るまで失敗を貼って再プロンプトする

チェックが失敗したら、その失敗出力を次のプロンプトに使ってください。最速のループは: エラーを貼る → 診断を得る → 最小の修正を適用 → 再実行、です。

失敗は逐語的に貼り付け、まず最もありそうな原因を尋ねてください。Claude Code は正確な行番号やメッセージに基づく方が当たりが良いので、推測ではなく具体的な情報でアンカーしてください。

既に試したことを一文で加えると同じループを回すのを防げます。重要な制約（"公開APIは変えない"、"振る舞いは維持する、ただしクラッシュを直して"）を繰り返し伝え、チェックが通る最小のパッチを求めてください。

提案された修正が振る舞いを変えるなら、新しい振る舞いが正しいことを証明するテストを要求してください。ハンドラが500ではなく400を返すようになったなら、古いコードでは失敗し新しい修正で通る1つの焦点を絞ったテストを求めましょう。これにより作業が正直になり、PRの信頼性が高まります。

チェックが通り、差分が1つのアイデアに見えるところで止めてください。モデルが無関係なコードを改善し始めたら、"失敗しているテストだけ直して。クリーンアップ不要。" と再プロンプトしてください。

PRをレビューしやすく、マージしやすくする

PRは何が、なぜ、どうやって動作を確認するかが明確だと最速でマージされます。このワークフローでは、PRは短い物語のように読むべきです: 小さなステップ、明確な理由。

コミットは反復に合わせて整えてください。1つの振る舞い変更を求めたならそれを1コミットにまとめ、テストの失敗を直したなら次のコミットにする。レビュワーは経緯を追えて、余分な変更が紛れ込んでいないことを信頼できます。

コミットメッセージはファイル名ではなく意図を書くべきです。"セッション切れ時のログインリダイレクトを修正" は "auth middlewareを更新" より優れています。ユーザー向けの結果を示すとレビュワーは推測に時間を使いません。

リファクタと振る舞い変更は同一コミットに混ぜないでください。変数名の変更やヘルパーの移動は別にするか、今はスキップしてください。ノイズはレビューを遅らせます。

PRの説明は短く具体的に:

• 何が変わったか（1–2文）。
• なぜ変えたか（バグや要求）。
• テスト方法（正確な手順、必要なフラグやデータ）。
• 何を変えていないか（期待設定）。
• リスクやロールバックメモ。

例: 顧客レコードがnullで課金ページがクラッシュする不具合。コミット1でガードと明確なエラーステートを追加。コミット2でnullケースのテストを追加。PR説明: "Billingを開き、プロフィールのない顧客を読み込むと新しい空状態が表示されることを確認"。こんなPRはレビュワーが素早く承認できます。

作業を遅らせる一般的な落とし穴

このリズムが崩れるのはスコープが静かに広がるときです。"失敗するテストを直して" が "モジュール全体のエラーハンドリングを改善" になり、急に大きな差分をレビューするハメになります。目標は常に1つ、1つの変更セット、1セットのチェックです。

もう一つの遅延は、見た目が良いからといってリファクタを受け入れてしまうことです。名前変更やファイル移動、スタイル変更はレビューにノイズを生み、実際の振る舞いの変化を見つけにくくします。

よくある落とし穴:

• モデルが "ついでに" と無関係なファイルに触ることを許す。
• 症状（余分なnullチェック）を直してテストが指す根本原因を見ないこと。
• ログの末尾だけを貼り、最初のエラーを隠すこと。
• チェック前に差分を素早く確認しないこと。
• 「まだ失敗する」とだけ言って再プロンプトすること（正確なコマンドと出力を添えない）。

具体例: テストが "expected 400, got 500." と失敗したとき、スタックトレースの最後だけを貼ると一般的な try/catch の提案が返ることが多いです。完全なテスト出力を貼れば本当の問題が見つかるかもしれません: バリデーションが欠けている、という小さく焦点を絞った修正につながります。

コミットする前に差分をレビュワーの目で読み直してください。各行が要求に応えているか、1文で説明できるか問うてください。できなければ余分な変更を元に戻し、より狭い要求で再プロンプトしましょう。

例: 数ループでマージ可能なPRにするバグ修正

ユーザー報告: "設定ページが保存後にデフォルトに戻ることがある。" mainをpullしてテストを実行すると1つの失敗が出るか、あるいはテストがない場合は再現手順が明確になります。

これをループとして扱います: 小さな1つの要求、1つの差分、そしてチェック。

まずClaude Codeに最小限の有用なコンテキストを与えます: 失敗テスト出力（または再現手順）、疑っているファイルパス、ゴール（"リセットを直して振る舞いは変えない"）。診断と最小パッチを求め、リファクタは要求しないでください。

その後短いループで作業します:

1. ループ1（最小パッチ）: バグを修正するためにもっとも可能性の高い最小の変更を適用します。ガード条件、欠けたnullチェック、誤ったデフォルト値、依存リストの不備などに留めます。

差分をレビューしてからチェックを実行します。

2. ループ2（正確な失敗をフィードバック）: テストが失敗したら、正確な失敗出力をClaude Codeに貼ります。ファイル名、行番号、アサーションメッセージを含め、"最小の変更でこの失敗を直すには？" と尋ねます。

もしチェックが通ったが回帰が心配なら、カバレッジを追加します。

3. ループ3（テスト追加または調整）: パッチがないと失敗するテストを追加し、パッチがあれば通るようにします。バグに焦点を絞ったテストを保ち、再度チェックを実行します。

まとめとして小さなPR説明を書く: バグの内容、原因、何を変えたか。"Xファイルのみを触る" や "リセットケースのテストを1つ追加" のようなレビュワーノートを入れると安心してレビューできます。

PRを開く前の簡潔チェックリスト

PRを開く直前に、作業がレビューしやすく安全にマージできるか最終確認をしてください。

• 差分は元のゴールに合致しており、数分で理解できる小ささか。
• 関連するチェック（テスト、lint、型チェック、ビルド）を実行して通っている。チームのCIで同じセットが走るか確認する。
• バグや機能に対する適切な安全網（可能ならテスト）を用意しているか、あるいはテスト不要の明確な理由があるか。
• PR説明が具体的で、何を変えたか・なぜ変えたか・検証手順が明確か。
• 無関係な編集（フォーマット、スタイル変更、不要なリファクタ）が含まれていないか。

例: ログインバグを修正したが20ファイルのフォーマットを変更してしまったなら、フォーマットのコミットを元に戻してください。レビュワーはログイン修正に集中できるべきです。

どれかが満たされていなければ、もう一度小さなループを回してください: 小さな差分を作り、チェックを再実行し、PR説明を更新する。最後の1ループが何時間ものやり取りを節約することがよくあります。

次のステップ: このリズムを習慣にする

一貫性があれば良いセッションが確実なワークフローになります。デフォルトのループを決めて毎回同じように回してください。一週間続ければ、プロンプトが短くなり差分がレビューしやすくなるのが実感できるはずです。

シンプルなルーチン:

• 1つの小さな成果を選ぶ（1つのバグ、1つのエッジケース、1つの関数）。
• 1つの小さな差分と簡潔な説明を求める。
• 差分をレビュワーの目で読み、ローカルでチェックを実行する。
• 正確な失敗出力とファイル名で再プロンプトする。
• チェックが通り、変更が明確になったら止める。

個人的なプロンプトテンプレートがあれば規律を保てます: "必要なことだけを変える。最大2ファイルまで。公開振る舞いは変えない。実行するコマンドと成功の定義を教えて。"

Koder.ai 内で開発している場合でも同じループをチャットで使えます。Planning mode は最小のマージ可能スライスを見定めるのに適しており、スナップショットとロールバックは実験が逸れたときに素早く回復するのに役立ちます。

変更が安定したらソースコードをエクスポートして通常のローカルツールやCI、チームレビューにかけてください。エンドツーエンドでの実運用検証が必要な場合はデプロイして確認します。

このループをデフォルトにしてください。小さなプロンプト、小さな差分、頻繁なチェック、迅速な修正が積み重なって、最良の意味で「退屈な」PRにつながります。