Claude Code Skills × Bedrockで実現するドメイン特化のPR自動レビュー
はじめに
こんにちは、ブランドソリューション開発本部ZOZOMO部FBZブロックの池上 寛登です。2026年3月にZOZOへ入社し、Fulfillment by ZOZO（以下、FBZ）のバックエンド開発を担当しています。
FBZに参画してまず直面したのは、ドメイン知識の壁でした。中でも強く実感したのが、コードレビューの場面です。Pull Request（以下、PR）のレビューには、判断の根拠がドキュメントに載っていない「暗黙知の壁」がありました。既存メンバーの指摘は的確ですが、新規参画者の自分には同じ品質でレビューする難しさがありました。
この課題を解決するために、暗黙知を形式知としてガイドライン化し、Claude Code SkillsとAmazon Bedrockに組み込んだPR自動レビュー基盤を作成しました。本記事では、その仕組みと設計判断を紹介します。
目次
背景：FBZにおけるPRレビューの課題
FBZはZOZOTOWNの倉庫リソースを活用し、外部のブランドが運営する自社ECへ物流・決済・返金などの機能を提供するフルフィルメントサービスです。在庫同期・注文管理など、扱うドメインは多岐にわたります。
さらにFBZは複数のリポジトリで構成されており、リポジトリごとに採用言語やアーキテクチャが異なります。PRレビューで見るべき観点もリポジトリごとに大きく変わるため、レビュアーには横断的な知識が求められます。
実装やレビューの参考になるようなガイドラインは存在したものの、リポジトリごとに保存場所が異なり、内容の鮮度や粒度も統一されていませんでした。結果として、判断はレビュアー個人の経験知に大きく依存し、次の3つの課題が顕在化していました。
- レビュアーごとに観点が異なり、レビュー品質にばらつきが出る
- 新規参画者がドメイン知識をキャッチアップするまでに時間を要する
- 同じアンチパターンの指摘が、異なるPRで繰り返し発生する
アプローチの全体像
これらの課題に対し、ガイドラインを中心に据えたPR自動レビュー基盤を構築しました。
取り組みは大きく次の3層に分かれます。
- ガイドラインの設計：暗黙知を形式知へ落とし込み、レイヤー別ファイルとNG/OKペアで定義する
- 実行基盤の構成：Claude Code Actionを実行し、関連するガイドラインを読み込んでPRをレビューする
- ガイドライン更新の自動提案：過去のレビューコメントからガイドラインの更新提案を自動生成し、ルールの陳腐化を防ぐ
それぞれを順に説明します。
ガイドラインの設計
暗黙知の収集
ガイドラインに落とし込む暗黙知は、PRのレビューコメントから収集しました。当初はSlack（コミュニケーションツール）の議論やConfluence（社内Wiki、ADR）の設計メモからも抽出を試みました。しかしFBZの場合は設計判断や指摘の根拠の多くがPRのレビュー会話に蓄積されていたため、最終的にPRを主な情報源とすることにしました。
過去のPRレビューを横断的に分析し、次の観点に該当する指摘をルール化しました。
- 同種の指摘が繰り返し発生している
- 既存のドキュメントではカバーされていない
- チーム全体で共有すべき設計判断が含まれている
レイヤー別ガイドラインの作成
収集した暗黙知をルール化するため、ドメインで頻出する論点を抽出し、アーキテクチャレイヤーごとのファイルへ分割しました。具体的には、レイヤー責務・データ整合性・エラー設計・テスト/コーディング規約・インフラ/セキュリティといった観点で章を分け、全章で前提となる共通ファイルを別途用意しています。
各ルールはNG/OKペアの形式で記述しています。形式を統一することで、LLMがルールの境界を判定しやすくなります。
# NG: 呼び出し元で税率や端数処理をハードコードしている
total = round(price * 1.1)
# OK: ドメイン共通の計算ロジックを通し、税率や端数ルールを一元化できている
total = PriceCalculator.with_tax(price)
変更パスに応じた参照ルールの選択
レビュー時にガイドラインを全て読み込むと、コンテキストが肥大化して精度も落ちます。そこで、変更ファイルのパスから参照すべきガイドラインを対応付ける表を定義しました。
この対応表は SKILL.md に記述しており、LLMが変更ファイル一覧と対応表を照らし合わせて、該当する章だけを動的にロードすることを実現しています。
'app/service/**': layer-rules/layer-responsibility.md
'app/dataaccess/**': layer-rules/data-integrity.md
'tests/**': layer-rules/test-and-coding.md
実行基盤の構成
実行基盤の全体像は以下のとおりです。図中の各要素については、次節以降で順に解説していきます。
実行環境
基盤としてはGitHub Actions上で動作するClaude Code Actionを採用し、モデル呼び出し先にはAmazon Bedrockを選びました。
ガバナンス要件として、社外のサービスへソースコードを送信せず、社内AWSアカウントに閉じた状態でモデルを利用する必要があったためです。GitHub ActionsからはOIDCでAWSにAssumeRoleし、Bedrockの推論プロファイル経由でClaudeモデルを呼び出します。これによりIAM・ログ・モデル呼出のすべてを社内環境に閉じた構成で運用できます。
PRサイズに応じたモデル選択
PRのサイズに応じて、レビューに使うモデルを動的に切り替えています。PRサイズは、差分の行数と変更ファイル数の組み合わせで判定しています。Opusは検証段階で精度向上の幅がコストに見合わなかったため、採用していません。SonnetとHaikuの使い分けで、精度・コスト・レイテンシをバランス良く確保できました。
| PRサイズ | モデル | 設計判断 |
|---|---|---|
| 小規模・単一ファイル | Claude Haiku | 軽量な判定で十分な品質を確保できるため、コストとレイテンシを優先する |
| 中〜大規模 | Claude Sonnet | レビュー本処理の標準モデル。大規模PRでは影響範囲の調査で往復回数が増えるため、ターン上限（LLMがツール呼び出しを連続で行える回数の上限）を引き上げて対応する |
2段レビューによる誤検知抑制
LLMによる自動レビューで課題となるのが、誤検知（False Positive）と見逃し（False Negative）です。誤検知が多ければBotの指摘は信頼されなくなり、見逃しが多ければ自動レビュー自体の意義が失われます。
この課題に対し、単一セッション内でペルソナを切り替えながら2段でレビューする仕組みを取り入れました。
Reviewer Passは「網羅的に拾うペルソナ」として候補を出し切り、Validator Passは「批判的に再検証するペルソナ」として根拠を再確認します。役割を意識的に分離することで、互いに独立した判断が成立します。検証段階で複数のレビュー方式を比較したところ、この方式が最も誤検知を抑えられました。
Confidence（確信度）閾値と Severity（重要度）ラベル
Validator Passでは、各指摘に対してチェック項目を採点し、合計値をその指摘のConfidenceとして算出します。チェック項目は「根拠コードを再読み込みしたか」「PR説明文を踏まえているか」「影響範囲を確認したか」などです。
指摘にはImportant・Pre-existing・Nitの3種類のSeverityを付与し、それぞれに投稿するためのConfidence閾値を設けています。Importantは厳しめ、Nitは緩めの閾値です。閾値を満たさない候補は、たとえReviewer Passで挙がっていても投稿しません。
Severityはコメント先頭に[Important]のようなテキストラベルとして付与します。PR作成者はラベルを見て対応の優先度を判断できます。
ai-reviewedラベルによる再レビュー
不要な再実行を避けてコストを抑えるため、レビュー完了時にPRへai-reviewedラベルを付与しています。PR作成者は修正後にラベルを外すだけで、必要なときだけ再レビューを起動できます。
また再レビュー時はノイズ抑制のため、ブロッキング相当の指摘であるImportantとPre-existingのコメントのみを投稿するよう制御しています。
ガイドライン更新の自動提案
ガイドラインは、コードベースや設計判断の変化に追従できないため、時間の経過とともに陳腐化します。これを避けるため、直近のレビューコメントと既存ガイドラインを照らし合わせ、追加・修正・削除を含む更新提案を起票するワークフローを毎月実行するようにしました。
また、ガイドライン更新時の判断基準を統一するため、追記場所・文体・重複チェック手順をまとめたメタガイドラインを別ファイルで用意しています。これにより、ガイドラインの一貫性を保つことができます。
効果
運用開始からまだ日が浅いですが、現時点で見えている効果は次のとおりです。
ドメイン固有のアンチパターン検出
ガイドラインに沿ったレビューが行われるため、レイヤー責務・データ整合性・エラー設計といったドメイン色の強い論点も、自動レビューで捕捉できるようになりました。
実装品質の向上
今回の対応でプロジェクトにおける暗黙知を形式知化できました。例えばこのガイドラインを .claude/rules/ に配置することで、開発時のClaude Codeも同じルールを参照する効果を期待できます。
新規参画者にとってのドメインリファレンス
副次効果として、ガイドラインは新規参画者の学習リファレンスとしても機能しています。私自身もこのガイドラインで「FBZのService層はどう書くのが正解か」を確認しながら実装を進めてきました。
まとめ
本記事では、Claude Code SkillsとAmazon Bedrockを組み合わせてFBZドメインに特化したPR自動レビュー基盤を構築した取り組みを紹介しました。
ドメイン知識を抱えるチームでPRレビューの自動化を検討している方は、ぜひ参考にしてみてください。
ZOZOでは、一緒にサービスを作り上げてくれる方を募集中です。ご興味のある方は、以下のリンクからぜひご応募ください。