Claude CodeでPull Request品質を上げる実践ガイド

Pull Requestは、GitHub公式ドキュメントでも「提案、レビュー、マージを行う場」と説明されるチーム開発の中心です。ところがClaude Codeで実装速度が上がるほど、PR説明が薄い、差分が大きい、テスト証跡がない、レビューコメントへの返答が雑、という別の問題が目立ちます。AIで速く書いたコードほど、人間が理解できる形に梱包しないと、マージ直前で止まります。

この記事では、Claude Codeを「PR本文を書く便利ツール」ではなく、PR品質を守るレビュー補助として使う手順をまとめます。diffは変更差分、CIは自動テストやビルドの門番、diff-size budgetはPRの大きさ上限、handoffは次の担当者に渡す引き継ぎメモ、という意味で扱います。関連する基礎はコードレビューガイドとテスト戦略も合わせて読むと流れがつかみやすいです。

flowchart LR
  A["Claude Codeで実装"] --> B["PRテンプレートを埋める"]
  B --> C["差分サイズをCIで制限"]
  C --> D["テスト証跡と安全確認"]
  D --> E["レビュー引き継ぎ"]
  E --> F["リリースノート"]

公式情報は、GitHub Pull Requests、PRテンプレート、GitHub Actions workflow syntax、protected branches、Actionsのsecrets、Claude Code docsを参照します。コミット分類を使う場合だけ、Conventional Commitsも確認してください。

良いPRの条件をテンプレートに固定する

Claude Codeに毎回「いい感じにPR説明を書いて」と頼むと、PRごとに粒度がぶれます。先に.github/pull_request_template.mdを置き、必須情報を入力欄として固定します。GitHubはリポジトリ内のPRテンプレートをPR本文へ自動表示できるので、レビュー文化をコードベースの一部にできます。

## 変更内容
<!-- 何を変えたか。実装、設定、ドキュメントを分ける。 -->

## 背景と判断理由
<!-- Issue、障害、ユーザー要望、代替案を1-3文で書く。 -->

## レビューしてほしい箇所
- [ ] ビジネスロジック
- [ ] UI/UX
- [ ] DB/API契約
- [ ] セキュリティ/プライバシー

## テスト証跡
- [ ] 自動テスト:
- [ ] 手動確認:
- [ ] スクリーンショット/録画:

## 差分サイズ
- 変更ファイル数:
- 追加/削除行数:
- 分割しなかった理由:

## セキュリティと運用
- [ ] secret、token、個人情報を含まない
- [ ] ログに個人情報や認証情報を出さない
- [ ] 権限、環境変数、feature flagの影響を確認した
- [ ] ロールバック方法を書いた

## レビュアーへの引き継ぎ
<!-- 先に読むファイル、迷った点、残課題、後続PRを書く。 -->

このテンプレートの価値は、Claude Codeの出力を受け入れる前に空欄を見つけられることです。特に「分割しなかった理由」と「ロールバック方法」が空のPRは、実装が正しくても運用レビューで止まりがちです。

Claude CodeにPR本文を書かせるプロンプト

テンプレートを置いたら、Claude Codeにはテンプレートを埋める役割だけを渡します。専門用語を初出で説明させ、推測した内容には「未確認」と書かせるのが重要です。AI生成文をそのまま貼るのではなく、事実だけを残す運用にします。

git diff origin/main...HEAD | claude -p "
このdiffを読み、.github/pull_request_template.mdの形式でPull Request本文を日本語で作成してください。

条件:
- diffに書かれていない事実を断定しない
- テストを実行した証拠がなければ「未実行」と書く
- 専門用語は初出で短く説明する
- レビュアーが最初に見るべきファイルを3つ以内に絞る
- secret、token、個人情報、ログ出力のリスクを確認する
- 最後に「人間が確認すべき未確定事項」を箇条書きにする
"

私の運用では、Claude Codeに「レビューしてほしい箇所」を必ず作らせるようにしてから、レビューコメントが抽象論から具体的な行へ移りました。レビュアーに「全部見てください」と渡すより、「認可判定はこの関数、UI崩れはこの画面、DB移行はこのファイル」と渡すほうが早いです。

差分サイズをCIで止める

大きすぎるPRは、レビュー品質を下げます。Claude Codeは広範囲を一気に直せるため、命名修正、整形、実装、テスト、ドキュメントが1本のPRに混ざりやすいです。そこでdiff-size budget、つまり「このPRは何ファイル・何行まで」という上限をCIに入れます。

Nodeプロジェクトなら、まずscripts/check-pr-size.mjsを追加します。lockfileや生成物を除外して、実際にレビューすべき差分だけを数えます。

#!/usr/bin/env node
import { execFileSync } from "node:child_process";

const [range = "origin/main...HEAD", maxLinesRaw = "700", maxFilesRaw = "35"] =
  process.argv.slice(2);
const maxLines = Number(maxLinesRaw);
const maxFiles = Number(maxFilesRaw);

const ignored = [
  /^package-lock\.json$/,
  /^pnpm-lock\.yaml$/,
  /^yarn\.lock$/,
  /^dist\//,
  /^coverage\//,
];

function numeric(value) {
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : 0;
}

const output = execFileSync("git", ["diff", "--numstat", range], {
  encoding: "utf8",
}).trim();

let files = 0;
let lines = 0;

for (const row of output.split(/\r?\n/).filter(Boolean)) {
  const [added, deleted, file] = row.split("\t");
  if (ignored.some((pattern) => pattern.test(file))) continue;
  files += 1;
  lines += numeric(added) + numeric(deleted);
}

if (files > maxFiles || lines > maxLines) {
  console.error(
    `PR is too large: ${files} files / ${lines} changed lines. ` +
      `Budget is ${maxFiles} files / ${maxLines} lines.`,
  );
  console.error("Split formatting, generated files, and behavior changes into separate PRs.");
  process.exit(1);
}

console.log(`PR size OK: ${files} files / ${lines} changed lines.`);

次にGitHub Actionsで実行します。GitHub Actionsのworkflowは.github/workflows配下のYAMLで定義します。protected branchesのrequired status checksにこのjobを入れると、基準を満たさないPRをマージ前に止められます。

name: PR quality

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: read

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Run project checks
        run: |
          npm run lint --if-present
          npm test --if-present

      - name: Enforce PR size budget
        run: node scripts/check-pr-size.mjs "origin/${{ github.base_ref }}...HEAD" 700 35

上限はチームで調整します。私の基準では、初回導入は700行・35ファイル程度から始め、リファクタリングPRは例外ラベルを要求します。大切なのは、AIに「分割案を出して」と頼む前に、機械的な予算を明文化することです。

テスト証跡をPRの本文に残す

PR品質は「テストしたか」ではなく「レビュアーがテスト結果を再現できるか」で決まります。Claude Codeにはテスト実行もできますが、実行していないテストまで成功扱いにさせてはいけません。本文にはコマンド、結果、手動確認、未確認の理由を分けます。

claude -p "
このブランチのPRに載せるテスト証跡を作ってください。

出力形式:
## 自動テスト
- コマンド:
- 結果:
- 失敗した場合の原因:

## 手動確認
- 確認した画面/API:
- 入力データ:
- 期待結果:
- 実際の結果:

## 未確認
- まだ確認していない項目:
- マージ前に誰が確認すべきか:

事実だけを書き、実行していないコマンドを実行済みのように書かないでください。
"

ユースケースは3つあります。1つ目はUI変更で、スクリーンショット、画面幅、アクセシビリティ確認を本文に残します。2つ目はAPI変更で、互換性、失敗レスポンス、ログ出力を残します。3つ目はバッチや移行で、dry run、ロールバック、実行時間の見込みを残します。この3種類を区別するだけで、レビュアーは自分の専門領域から見始められます。

セキュリティとプライバシーをPR単位で確認する

Claude CodeでPRを作ると、環境変数名、ログ、サンプルデータ、スクリーンショットに機密情報が混ざることがあります。Actionsのsecretsは便利ですが、PR本文やテストログに値を書いてよいわけではありません。GitHubのsecretsドキュメントに沿って、値はsecrets contextで扱い、ログに出す必要がある値はマスクします。

PR前の確認では、少なくとも次をClaude Codeに尋ねます。

この差分をセキュリティとプライバシー観点でレビューしてください。

確認項目:
1. secret、token、API key、cookie、session idが含まれていないか
2. 個人情報、メールアドレス、顧客ID、住所、課金情報がログやfixtureに出ていないか
3. 権限チェックがUIだけでなくサーバー側にもあるか
4. GitHub Actionsのpermissionsが広すぎないか
5. エラー時に内部パスや認証情報を返さないか
6. スクリーンショットに実データが写っていないか

重大度をHigh/Medium/Lowで付け、修正案を具体的なファイル名つきで出してください。

落とし穴は、AIが「問題ありません」と早く結論を出すことです。私は必ず「疑わしいが断定できない箇所」も出させます。セキュリティレビューでは、確信よりも保留の列挙が役に立ちます。

レビュー引き継ぎとコメント返信を整える

handoff、つまり引き継ぎが弱いPRは、レビュアーが最初から読み直すことになります。Claude Codeには、PR本文、差分統計、レビューコメントを渡して、次の担当者向けの短いメモを作らせます。

PR_NUMBER=123
{
  gh pr view "$PR_NUMBER" --comments
  gh pr diff "$PR_NUMBER" --stat
} | claude -p "
このPull Requestのレビュー引き継ぎメモを作成してください。

含める内容:
- 変更の目的を2文以内
- 最初に読むべきファイルを3つ以内
- 既に対応済みのレビューコメント
- 未対応または判断待ちのコメント
- CI、手動テスト、リリース時の注意

レビュアーが5分で状況を把握できる長さにしてください。
"

レビューコメントへの返信も同じです。「修正しました」だけでは不十分です。どのファイルをどう直したか、追加テストは何か、反映しなかった指摘があるなら理由は何かを書きます。反対意見への返信をClaude Codeに下書きさせる場合も、根拠のない断定や長すぎる説明は削ります。

リリースノートまでPRからつなげる

PRはマージで終わりではありません。ユーザー向けの変更、社内運用向けの変更、破壊的変更をリリースノートへ渡す必要があります。Conventional Commitsを使っているチームなら、feat、fix、docsなどの分類を手がかりにできます。ただし、分類は補助であり、ユーザーに伝わる言葉へ直す作業は別です。

gh pr list --state merged --base main --limit 20 \
  --json number,title,body,mergedAt \
  | claude -p "
次回リリースノートの下書きを日本語で作成してください。

分類:
## 新機能
## 修正
## パフォーマンス
## ドキュメント
## 開発者向け変更

条件:
- PR番号を残す
- ユーザーに影響がない内部変更は短くする
- 破壊的変更、移行作業、feature flagを強調する
- PR本文に根拠がない内容は書かない
"

リリースノートに使えないPR本文は、そもそもレビューにも使いにくいです。PR本文を書く時点で「この変更を後でユーザーにどう説明するか」を意識すると、実装理由が整理されます。

AI生成のうるさいPRを避ける

Claude Codeを使ったPRで一番多い失敗は、ノイズが多いことです。たとえば、関係ない整形、命名の一括変更、未依頼のリファクタリング、実行していないテストの記載、AIっぽい長文の説明です。これらはレビュー時間を増やし、重要な変更を埋もれさせます。

避けるためのルールは単純です。整形だけの変更は別PRにする。生成コードは最小差分にする。PR本文には事実だけを書く。Claude Codeの提案を採用した理由を1文で説明する。大きい変更は「機械的変更」「振る舞い変更」「テスト追加」に分ける。これだけで、AIを使っていても人間がレビューしやすいPRになります。

比較すると次のようになります。

悪いPR	良いPR
「Claudeが全体を改善しました」	「認可チェックをserver/auth.tsへ集約しました」
2,000行の整形と実装が混在	整形PRと機能PRを分離
テスト未実行なのに「問題なし」	未実行項目と担当者を明記
レビュー観点が空	読む順番と危険箇所を指定

ClaudeCodeLabの収益導線に組み込む

このPR品質フローは、記事制作や受託開発の収益導線にも使えます。ClaudeCodeLabで研修、テンプレート販売、実装相談を扱うなら、PRテンプレート、CLAUDE.md、CIチェック、レビュー引き継ぎをセットで提供すると価値が伝わりやすくなります。CLAUDE.mdテンプレートやチーム引き継ぎルールへ内部リンクを置き、さらに研修・相談へ自然につなげると、読者は「記事を読んで終わり」ではなく「自分のチームに導入する」段階へ進めます。

実務で導入するなら、最初から全部を自動化しないでください。1週目はPRテンプレート、2週目は差分サイズCI、3週目はレビュー引き継ぎ、4週目はリリースノート、という順番が現実的です。いきなり厳しいゲートを入れると、チームはAIではなくルールを嫌いになります。

この記事で紹介した内容を実際に試した結果

この記事の手順を小さなNodeプロジェクトで試したところ、最も効果が大きかったのはPRテンプレートと差分サイズチェックの組み合わせでした。Claude CodeにPR本文を作らせるだけでは説明が長くなりがちでしたが、テンプレートで入力欄を固定すると、未実行テスト、セキュリティ確認、レビューしてほしいファイルが自然に残りました。700行・35ファイルの予算を入れると、整形と実装を分ける判断もしやすくなりました。

まとめ

Claude CodeでPull Request品質を上げるコツは、AIに自由作文をさせることではありません。テンプレートで必要情報を固定し、CIで差分サイズを止め、テスト証跡を本文に残し、セキュリティとプライバシーをPR単位で確認し、レビュアーへ短く引き継ぐことです。AI生成PRの速度を活かすには、人間がレビューしやすい形へ整える仕組みが必要です。