Claude Codeレビュー運用チェックリスト: PR公開前に失敗を潰す実践手順

最初の3行でレビューの深さを固定する

Claude Codeに「このPRをレビューして」とだけ頼むと、返ってくるのは読みやすさの感想になりがちです。モデルが弱いのではなく、レビュー対象、壊れて困る挙動、実行済みの検証、残った不安を渡していないことが原因です。

この記事では、出荷前にClaude Codeレビューを使うための運用手順をまとめます。ここでいうレビュー運用とは、AIに自由に感想を言わせることではありません。差分を小さく切り、リスクを名前で呼び、検証ログを残し、最後に人間が判断できる形で指摘を受け取る一連の流れです。

初心者向けに言い換えると、差分は「今回変えた部分」、レビューゲートは「公開前に必ず通す関門」、検証レシートは「何を実行してどうなったかの証拠」です。Claude Codeの基本は公式のClaude Code overviewとcommon workflowsを確認し、GitHub側のレビュー権限や状態はGitHub pull request reviewsを基準にします。npmコマンドを使う場合はnpm scriptsの挙動も押さえておくと、レビュー結果の再現性が上がります。

この運用は、観点をさらに細かく分けたClaude Codeコードレビュー チェックリストと、証跡の残し方を扱うverification receipt workflowと一緒に使うと効果が出ます。

全体像: Claude Codeに渡す前に人間が整理する

Claude Codeレビューの質は、プロンプトの文章力よりも入力の整理で決まります。先に以下の4点を短く書くと、AIの出力は「雰囲気」から「欠陥探し」に変わります。

渡す情報	目的	悪い例	良い例
Scope	何を変えたかを限定する	いろいろ直した	記事下CTAのリンク、文言、モバイル余白だけ
Risk	壊れた時の影響を言う	たぶん大丈夫	購入導線、相談導線、内部リンクが壊れると売上に影響
Evidence	実行した検証を残す	手元で確認	npm run build成功、360px幅でCTAクリック確認
Handoff	次の判断を明確にする	見てください	P1/P2/P3で指摘、残リスク、追加テスト案を返す

flowchart LR
  A["Diff"] --> B["Scope and risk"]
  B --> C["Claude Code review"]
  C --> D["Human decision"]
  D --> E["Fix, verify, or ship"]
  E --> F["Review receipt"]

重要なのは、Claude Codeを最終承認者にしないことです。Claude Codeは見落としを減らす補助担当です。公開するか、差し戻すか、追加検証をするかは、PRの責任者が決めます。

レビュー前チェックリスト

レビュー依頼の前に、まず作業ツリーと実行コマンドを揃えます。以下はNode系プロジェクト向けの例ですが、Railsならbundle exec rspec、Goならgo test ./...に置き換えます。

git status --short
git diff --stat
git diff --name-only
npm run build
npm run test -- --runInBand

次に、PR本文かレビュー依頼メモへ貼れる形でチェックリストを作ります。これは.github/review-checklist.mdやチームWikiに置けます。

# Claude Code Review Checklist

## Scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] No unrelated formatting, dependency, or generated files are mixed in.

## Risk
- [ ] Risk level is marked as low, medium, or high.
- [ ] User-facing routes, forms, auth, billing, analytics, and CTA paths are named.
- [ ] Rollback or recovery steps are written for high-risk changes.

## Evidence
- [ ] Build, test, lint, or typecheck commands are listed with results.
- [ ] Manual checks include browser width, account state, and actual URL when relevant.
- [ ] Screenshots, logs, or console output are attached for UI and integration changes.

## Review output
- [ ] Findings come first, ordered by severity.
- [ ] Each finding has file reference, reproduction condition, and expected fix.
- [ ] Residual risk is written even when no blocker is found.

このチェックリストの狙いは、Claude Codeに「きれいに説明して」と頼むのではなく、「危険を見つけて、根拠を付けて、次の作業に変換して」と頼むことです。

そのまま使えるレビュー依頼文

レビュー依頼は短くても構いませんが、出力形式は厳しく指定します。特に「findings first」と「severity order」を入れると、前置きの長い感想を避けやすくなります。

Review this diff with a bug-finding mindset.

Scope:
- Only review the files changed in this PR.
- Do not rewrite code yet.

Prioritize:
1. behavioral regressions
2. security, privacy, or permission mistakes
3. missing tests or weak verification
4. broken mobile layout, internal links, product CTA, or training CTA

Return:
- Findings first, ordered by P1/P2/P3 severity
- File and line references when possible
- Why each issue matters to users or revenue
- Checks I should run next
- Residual risk if no blocker is found

「Do not rewrite code yet」を入れるのは、レビューと修正を混ぜないためです。最初のパスでClaude Codeが勝手に直し始めると、どの指摘が本当に重要だったのかが見えなくなります。レビューで合意してから、別タスクとして修正を依頼します。

実務でよく使う3つ以上のレビューケース

1つ目はCTAと収益導線の変更です。記事下の無料PDF、/products/、/training/へのリンクを触った時は、リンク先、文言、順番、モバイル表示、トラッキングイベントを同時に見ます。失敗例は、リンク文言だけ確認して、実際の遷移先が古いGumroad商品だったケースです。Claude Codeには「CTA flow」「product match」「mobile width」を明示します。

2つ目は認証、権限、個人情報の変更です。ログイン状態、管理者だけが見られる画面、メールアドレスや支払いIDを扱う処理は、コードの美しさよりも「漏れないか」「権限をすり抜けないか」が優先です。落とし穴は、UIでボタンを隠しただけでサーバー側の認可を確認しないことです。レビュー依頼には、誰が実行できるべきか、拒否されるべきユーザーは誰かを書きます。

3つ目は多言語記事の更新です。日本語では自然でも、英語や韓国語のfrontmatterの日付が古い、コードフェンスが閉じていない、内部リンクだけ未翻訳、という事故が起きます。Claude Codeには「10 locale files only」「preserve slug and heroImage」「scan mojibake」と明示します。これはbug report templateと組み合わせると、壊れた言語だけを切り分けやすいです。

4つ目はビルドエラーやテスト失敗の差し戻しです。Claude Codeにログ全文を渡すより、最後の100行、失敗コマンド、直前の差分、再現手順を渡す方が精度は上がります。落とし穴は、ビルドを直すついでに関係ない依存更新を混ぜることです。レビューでは「修正範囲が失敗原因に閉じているか」を必ず見ます。

失敗例と落とし穴

よくある失敗は「全体を見てください」という依頼です。範囲が広すぎるため、Claude Codeは安全な一般論に寄ります。対策は、対象ファイル、変更目的、触ってはいけない領域を最初に書くことです。

次の失敗は、検証コマンドを書かないことです。npm run buildが成功したのか、型だけ通ったのか、ブラウザ確認をしたのかが不明だと、レビューは推測になります。レビュー前に実行できなかった場合も、「未実行: 理由は依存未インストール」のように正直に残します。

収益導線では、PCだけで確認してスマホ幅を見ない事故が多いです。CTAボタンが折り返して読みにくい、カード全体が横スクロールする、 /products/ と /training/ の順番が本文の温度感と合わない、という問題はコード差分だけでは見逃されます。

セキュリティでは、秘密情報をプロンプトへ貼る失敗があります。APIキー、トークン、顧客メール、支払いIDは、Claude Codeに渡す前に伏せます。ログを渡す時は、最小の再現部分だけにします。

レビューコメントにも粒度があります。悪いコメントは「ここが微妙です」で止まります。良いコメントは、どのファイルのどの変更が、どの利用者行動に、どの程度の影響を持つかを書きます。たとえば「モバイルでCTAが押しにくい」より、「360px幅で価格カード下の相談ボタンが折り返し、指で押す領域が狭くなる。収益導線なのでP1」と書いた方が、修正者は迷いません。

優先度はP0からP3に分けると運用しやすいです。P0は漏洩、データ破壊、決済不能、公開停止のように即時対応が必要なもの。P1は収益導線、主要導線、認証、フォーム送信の不具合。P2は読みにくさ、補助導線、テスト不足、限定条件での崩れ。P3は表記ゆれや軽微な改善です。Claude Codeには「P0/P1だけ先に出して」と頼むと、長い指摘リストに埋もれずに済みます。

レビューの最後には、必ず「今回は見ていないもの」を書きます。これがないレビューは、読者に過剰な安心を与えます。たとえば、ビルドは通ったが本番URLは見ていない、スマホ表示は見たが広告表示は見ていない、CTAリンクは確認したがanalyticsイベントは未確認、という形です。未確認項目が明確なら、次のClaude Codeセッションや人間レビューにそのまま渡せます。

この未確認リストが短くなるほど、公開判断は速くなります。レビューは指摘を増やす作業ではなく、迷いを減らす作業です。

検証レシートを機械的に確認する

最後に、レビュー結果を「見た気がする」で終わらせないための小さなNodeスクリプトです。review-policy.jsonとreview-receipt.mdを用意し、必要な見出しと実行済みコマンドがあるかを確認します。

{
  "requiredSections": ["Scope", "Risk", "Checks run", "Findings", "Residual risk"]
}

#!/usr/bin/env node
const fs = require("node:fs");

const receiptPath = process.argv[2] || "review-receipt.md";
const policyPath = process.argv[3] || "review-policy.json";
const receipt = fs.readFileSync(receiptPath, "utf8");
const policy = fs.existsSync(policyPath)
  ? JSON.parse(fs.readFileSync(policyPath, "utf8"))
  : { requiredSections: ["Scope", "Risk", "Checks run", "Findings", "Residual risk"] };

const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
const missingSections = policy.requiredSections.filter((name) => {
  const heading = new RegExp(`^## ${escapeRegExp(name)}\\b`, "m");
  return !heading.test(receipt);
});

const hasCheckedCommand = /^- \[(x|X)\] `(npm|pnpm|yarn|node|pytest|go test|cargo test)/m.test(receipt);

if (missingSections.length || !hasCheckedCommand) {
  for (const section of missingSections) console.error(`Missing section: ${section}`);
  if (!hasCheckedCommand) console.error("Missing checked command evidence such as - [x] `npm run build`");
  process.exit(1);
}

console.log("Review receipt passed.");

# Review receipt

## Scope
Article CTA links and mobile layout only.

## Risk
Medium: product and training links affect revenue.

## Checks run
- [x] `npm run build` passed
- [x] mobile CTA path checked at 360px

## Findings
- P2: Product CTA text and destination mismatch on one locale.

## Residual risk
Analytics event names were not checked in production.

このスクリプトは完璧な品質保証ではありません。ただし、レビューの最低限の証跡が欠けたまま公開する事故を減らせます。チームでは、この形をPRテンプレート、Claude Codeのレビュー依頼、CIの軽いチェックに分けて使うと運用しやすいです。

次の導線

個人で始めるなら、まず無料Claude Codeチートシートで日常コマンドと安全な依頼文を固定します。レビュー、デバッグ、トリアージのプロンプトを毎回書き直しているなら、Prompt Templatesや/products/の教材で型を揃えた方が早いです。

チームで導入する場合は、単にプロンプトを配るだけでは足りません。CLAUDE.md、権限、レビューゲート、検証レシート、誰が最終承認するかを決める必要があります。実際のリポジトリに合わせて運用を設計するなら、/training/から相談するのが自然です。

実際に試した結果、Masaの小さな記事更新では「レビューして」だけの依頼より、Scope、Risk、Checks run、Residual riskを先に書いた依頼の方が、CTAリンクの不一致、モバイル幅の見落とし、未実行テストの指摘が明確になりました。Claude Codeレビューは魔法の承認者ではありませんが、人間が公開判断をする前の見落とし発見には十分使えます。