はじめに

こんにちは、godslewです。普段はAndroidエンジニアとしてアプリ開発をしています。

AIコーディングツールの普及で開発速度は上がりましたが、その分PRの数も増え、レビュワーの負担が大きくなっていないでしょうか。

PRの数が増えてレビュワーが追いつかず、レビュー待ちで開発が止まる
AI生成コードは量が多く、人間が全ファイルを丁寧に見きれない
レビューで指摘した知見がチームに共有されず、同じ問題が別のPRで繰り返される

自分が携わっているAndroidプロジェクトでは、Claude Codeのサブエージェントやスラッシュコマンドを組み合わせて、PRの作成からレビュー、修正、さらにはドキュメントへの知見反映までを自動化する仕組みを作りました。

この記事では、その仕組みの全体像と、各フェーズで何をやっているかを紹介します。

動作環境:

Claude Code（ローカル開発・スラッシュコマンド・サブエージェント）
Claude Code Action（GitHub Actions上でのClaude Code実行）
GitHub Actions（CI/CDパイプライン）

具体例はAndroid（Kotlin/Compose）プロジェクトでの運用ですが、ワークフローの考え方自体は汎用的です。ただし、サブエージェントの定義やルールドキュメントの設計はツールチェーンやプロジェクト構成に合わせた調整が必要になります。

全体の流れ

まず、PRワークフローの全体像です。

ポイントは、人間のレビューの前にAIレビューと自動修正のループを回すこと。AIはdiff全体を一度に見るので、人間のレビューで起きがちな「1回目で見落とした箇所を2回目で指摘する」という往復が減ります。人間のレビュワーに渡る時点で、よくある指摘事項はすでに潰されている状態を目指しています。

Phase 1: PR作成 ― テンプレートに沿って自動生成

PRの作成には、Claude Codeのスラッシュコマンド（.claude/commands/に定義）を使っています。

やっていることはシンプルです。

現在のブランチを確認して、ベースブランチからの差分を把握
PRテンプレートを読み込み、変更内容に基づいて本文を生成
gh pr create でPRを作成

手動でPR本文を書く手間を省くのが主な目的です。とはいえ、PRの説明文は「レビュワーが変更の意図を理解できるか」が重要なので、生成された内容には必ず目を通すようにしています。

変更が大規模になった場合は、PR分割を検討するためのサブエージェントも用意しています。1つのPRが肥大化するとレビューの質が落ちるので、「この変更はこう分けたほうがいい」という提案を出してくれるのは実用的です。

Phase 2: AIレビュー ― 10のサブエージェントが並列で走る

ここがこのワークフローの核です。

レビュー用のスラッシュコマンドを実行すると、10種類の専門サブエージェントが並列に起動して、それぞれの観点からPRを分析します。

サブエージェント	何を見るか
可読性チェッカー	コードの可読性
アーキテクチャチェッカー	設計パターン、モジュール依存関係
パフォーマンス分析	メモリ、UI描画、I/O
セキュリティ監査	認証、データ保存、ネットワーク通信
テストカバレッジ分析	カバレッジ、未テストのコードパス
バグ検出	バグ、ロジックエラー、エッジケース
ドキュメントチェッカー	ドキュメント更新の必要性
型構造レビュー	型安全性、ドメインモデルの設計
アセット再利用チェック	既存コンポーネントの再利用漏れ
PR説明文レビュー	PR説明文の品質

それぞれのエージェントは独立して並列に動くので、直列に実行するよりも大幅に時間を短縮できます。人間が同じ観点を全部チェックしようとしたら、かなりの時間がかかるでしょう。

レビュー結果はGitHubのPRレビューとして投稿されます。各エージェントの結果を集約して、クリティカルな問題（バグ、セキュリティ、パフォーマンス、アーキテクチャ違反）が1件でもあれば COMMENT、なければ APPROVE という判定です。非クリティカルな指摘（テスト不足、ドキュメント未更新など）はコメントとして残しつつも、APPROVE 扱いにしています。

なお、REQUEST_CHANGES は使わないようにしています。AIの判断でPRをブロックするのは、まだ早いと考えているためです。

レビューのルールとして、ポジティブなフィードバックやnit（些末な指摘）は出さないようにしています。「ここいいですね！」みたいなコメントは嬉しいですが、ノイズになるので。指摘すべきことだけをコメントする、というのは人間のレビューでも意識したいところです。

サブエージェントの実装

サブエージェントは .claude/agents/ にMarkdownで定義します。フロントマターでメタ情報を指定し、本文にプロンプトを書く構成です。

<!-- .claude/agents/readability-checker.md -->
---
tools: Glob, Grep, Read
model: opus
---

あなたはKotlinコードの可読性を専門にレビューするエージェントです。

## レビュー手順
1. `docs/rules/readability.md` を読み、プロジェクト固有ルールを確認する
2. 対象コードを検査する
3. 各issueについて、場所・該当ルール・改善案を報告する

ポイントは、エージェント自体にレビュー基準をハードコードしないことです。基準は docs/rules/ 配下のルールドキュメントを参照させます。こうすることで、Phase 4のドキュメント自動更新でルールが追加・修正されれば、次回のレビューから自動的に反映されます。エージェントの定義を書き換える必要はありません。

Phase 3: 自動修正 ― 指摘を受けて即座に対応

レビューで指摘が出たら、修正用のスラッシュコマンドで自動修正を試みます。

処理の流れは以下のとおりです。

PRのレビューコメントを全て収集（Review body、Review comment、Issue commentの3種類）
各指摘をCritical → Performance → Architecture → Readability → Styleの優先度で分類
自動修正可能なものはコードを修正してコミット・プッシュ
自動修正できないもの（設計判断が必要、大規模リファクタリングが必要など）はレポートとして報告

修正後、PR本文の末尾に「自動修正履歴」セクションが追記されます。何が直って、何が手動対応必要なのかが一目で分かるようになっています。

## 🤖 自動修正履歴

**修正件数**: 3/5

### 修正済み
- readability: 変数名をcamelCaseに修正
- performance: 不要なrecompositionを抑制するための安定性アノテーション（`@Stable`）付与
- architecture: Repository層のcoroutine scopeを修正

### 手動対応が必要
- テスト追加（理由: 新しいテストケースの設計判断が必要）
- API設計の見直し（理由: 破壊的変更を伴うため判断が必要）

修正が終わったらレビューコマンドを再実行して再レビューをかけることもできます。指摘→修正→再レビューのループがGitHub上で完結するのがこの仕組みの要点です。

Phase 4: ドキュメント自動更新 ― レビューの知見をチームに還元する

個人的に一番気に入っている仕組みです。レビューで得た知見が次のレビューの精度向上に直結するので、使うほど効果が上がっていきます。

ドキュメント更新用のコマンドを実行すると、PRのレビューコメントからプロジェクト全体に適用できる汎用的な学びを抽出し、ルールドキュメントに反映するPRを自動で作成します。

マージ後に限らず、レビューコメントが付いた時点でいつでも実行可能です。レビュー中に「これはルール化すべきだ」と感じたら、その場で回せます。

たとえば、あるPRで「Composeのrememberの使い方が間違っている」という指摘があった場合、その知見がCompose関連のルールドキュメントに追記されます。Phase 2で述べたように、サブエージェントはこの docs/rules/ を参照してレビューするため、次に同じパターンのコードが出てきたときに自動的に指摘できるようになります。

抽出の際には、以下のような基準で採用・除外を判断しています。

採用: 「ViewModelでStateFlowを公開するときはprivate MutableStateFlowをバッキングフィールドにする」のような、プロジェクト全体で繰り返し適用されるパターン
除外: 「この変数名をuserIdに直して」のような、そのPR固有の修正指示

何でもドキュメントに入れると逆に使い物にならなくなるので、汎用性のある知見だけを残すようにしています。

もちろん、ドキュメント更新のPRも人間がレビュー・承認します。AIが抽出した知見が必ずしも正しいとは限らないので、誤ったルールが蓄積されるのを防ぐためのゲートは必要です。

ドキュメントに何を書くかも重要です。言語仕様や一般的なベストプラクティスはLLMが既に学習済みなので、そうした内容との重複は避け、プロジェクト固有のルールを重点的に記載します。

書くのはチーム固有の暗黙知です。「このプロジェクトではこういう判断基準で設計する」「過去にこのパターンで問題が起きたからこう書く」といった、コードベースを長く触っている人の頭の中にしかなかった知識を形式化することに意味があります。

この仕組みによって、レビューで得た知見が自然にプロジェクトのルールとして蓄積されていくサイクルが生まれました。

実際に運用してみて

この仕組みを回し始めて感じたことをいくつか。

なお、ここまでのコマンドはGitHub上でも使えます。PRやIssueのコメントで @claude とメンション（Claude Code Action経由）すれば、ローカル環境を開かずにコード修正やレビューを依頼できます。

良かった点:

人間のレビュワーが「このimport不要だよね」みたいな機械的な指摘から解放された
レビュー待ちの時間が実質的になくなった。AIレビューは数分で返ってくる
ドキュメントが陳腐化しなくなった。レビューの知見が自動で反映されるので、常に最新のルールが載っている状態を保てる

注意していること:

AIレビューはあくまで一次フィルター。設計の妥当性やビジネスロジックの正しさは、最終的に人間が判断する
REQUEST_CHANGES を使わないのは意図的。AIの誤判定でPRが不必要にブロックされるのを防ぐため
自動修正の結果は必ず差分を確認する。意図しない変更が混入していないかのチェックは人間の責任

まとめ

PRのワークフローを「作成 → AIレビュー → 自動修正 → 人間レビュー → ドキュメント更新」というパイプラインとして整備したことで、レビューの品質と速度を両立できるようになりました。

特に、レビューの知見がドキュメントに還元されて、次のレビューの精度が上がっていくフィードバックループが回り始めたのは大きな収穫です。チームの暗黙知が自然に形式知に変わっていく感覚があります。

Claude Codeのサブエージェント（.claude/agents/）やスラッシュコマンド（.claude/commands/）は、こうした「繰り返し発生する定型作業」の自動化と相性が良いです。全部を一度に導入する必要はないので、まずはレビューの自動化あたりから試してみると効果が実感しやすいと思います。