APC 技術ブログ

株式会社エーピーコミュニケーションズの技術ブログです。

株式会社 エーピーコミュニケーションズの技術ブログです。

トップ > AI駆動開発 > AIが書いたコードのレビュー、どこを見ればいいか② — 属人的レビューを仕組みに変える4つのレイヤー

AIが書いたコードのレビュー、どこを見ればいいか② — 属人的レビューを仕組みに変える4つのレイヤー

AI駆動開発 Platform Engineering Python

こんにちは。ACS事業部の越川です。

本記事は、同じACS事業部のメンバーによる前編「AIが書いたコードのレビュー、どこを見ればいいか」の後編です。

techblog.ap-com.co.jp

前編では2つの重要な論点が提示されました。

1つ目は「頻出スルー・エッジ重点」という分担論です。AIが得意な構文・スタイル・典型バグはツールに任せ、人間はエッジケース・組織固有の制約・本番前提の動的挙動に集中する、という方針です。

2つ目は「責任の分散」という問いです。コードレビューはバグを見つけるだけでなく、複数人で確認することで責任を分散する機能を持っていました。AIが大量のコードを生成する時代に、見る箇所を絞ることで責任分担を再設計できるのか。前編ではこの問いに「まだ答えが出ていない」と正直に書かれていました。

後編では、この2つの論点に対して仕組みで答えることを試みます。方針が正しくても、毎回レビュアーの意識に頼っていては定着しません。仕組みに埋め込むことで、誰がレビューしても同じ品質が出る状態を目指します。

前編の2つの問いに答える

問い1: AIに経緯が見えない — どう解決するか

元記事で指摘された核心的な課題があります。AIは「今あるコード」は読める。しかし「なぜそうなっているか」は読めません。設計判断の背景、過去に試して失敗した選択肢、法制度に由来する制約。これらはコードに書かれていないからです。

この課題に対する解決策は、AIが読める場所に経緯を書くことに尽きます。

問い2: 責任の分散 — 仕組みで再設計できるか

前編で提起された「AIが大量に書いたコードに対して、レビュアーの責任はどう変わるのか」という問い。

筆者の答えはこうです。レビューの対象をレイヤーで分け、各レイヤーの責任者を明確にする。 全行を人間が見る前提を捨て、代わりに「どのレイヤーを誰（人間 or AI or ツール）が責任を持つか」を定義します。

レイヤー 責任者 責任の取り方
構文・スタイル Linter / CI CIが通らなければマージできません。設定の妥当性は人間が担保
AIの出力品質 AI Code Review AIの指摘を人間が確認。見落としはインストラクションで改善
エッジケース・組織制約 人間レビュアー ここに集中するからこそ責任を持てる。見る範囲が明確

全部を見ようとするから責任が曖昧になります。見る範囲を絞るからこそ、その範囲に責任を持てる。 これが仕組みによる責任分担の再設計です。

経緯の状態 AIレビュー 人間レビュー
頭の中にしかない 見逃す 担当者が変わると見逃す
コード/ドキュメントに書いてある 文脈を持ってレビューできる 誰が見ても同じ基準で判断できる

AIに文脈を渡す4つのレイヤー

経緯や制約をAIに渡す方法は、粒度に応じて4つのレイヤーに分けられます。

レイヤー 場所 何を渡すか 具体例
1. コードの中 ソースコード 関数の仕様・制約の理由 型ヒント、コメント、docstring
2. リポジトリのルール ルートの設定ファイル プロジェクト固有のルール copilot-instructions.md、CLAUDE.md
3. CI/CD GitHub Actions 自動で弾ける基準 Linter、型チェック、テスト、セキュリティスキャン
4. レビュープロセス PRテンプレート・レビュー設定 人間が集中すべき観点 PRテンプレート、GitHub Copilot Code Review

レイヤー1: コードの中に文脈を埋め込む

型ヒント — AIへのガードレール

元記事でも触れられていたが、型ヒントはAIにとって「この関数は何を受け取って何を返すか」の仕様書になります。

# 型ヒントなし — AIは推測するしかない
def apply_discount(price, user_id):
    ...

# 型ヒントあり — AIが入出力を正確に把握できる
def apply_discount(price: int, user_id: str) -> int:
    ...

型ヒントがあれば、AIは型に反するコードを提案しにくくなる。コードを書く時点でレビューの品質が上がる。

コメントとdocstring — AIに理由を伝える

従来のコメントは人間のための補足でした。AI時代では、コメントはAIと人間の両方に向けたAPIドキュメントになります。

# 悪い例: AIにはわからない
RETRY_MAX = 3  # リトライ上限

# 良い例: AIが制約を理解できる
RETRY_MAX = 3  # SLAの99.9%達成に必要な上限値。変更する場合はインフラチームと要協議

マジックナンバーの再考

従来のコーディング規約では、マジックナンバーは定数化するのが鉄則でした。しかしAI時代では少し事情が変わります。

# 定数化（従来の正解）
DISCOUNT_PERIOD_DAYS = 30
if elapsed > DISCOUNT_PERIOD_DAYS:

# インラインのまま + コメント（AI時代の選択肢）
if elapsed > 30:  # 割引期間30日は消費者契約法に基づく。法改正時に要更新

定数名に抽象化すると、AIは定数の定義を追いに行く必要があります。コンテキストの消費が増えます。一方、値がそのまま書いてあってコメントで理由が添えられていれば、AIは1行で文脈を把握できます。

マジックナンバーは悪という従来の常識を否定しているのではありません。 定数化すべき場合（複数箇所で使う値、テストで差し替えたい値）は定数化する。ただし、1箇所でしか使わない業務制約由来の値は、コメント付きインラインの方がAIにとっても人間にとっても読みやすい場合があります。

レイヤー2: リポジトリのルールファイル

copilot-instructions.md — GitHub Copilotへのカスタムインストラクション

リポジトリのルートに .github/copilot-instructions.md を置くと、GitHub Copilotがコードレビュー時にこの内容を参照します。

# Copilot Instructions

## コーディング規約
- Python 3.11以上を前提とする。typing.Listではなくlist[int]を使うこと
- asyncio.gatherは最大100タスクまで。それ以上はバッチ分割すること

## 環境制約
- Dockerイメージはpython:3.12-slim。alpineは使用不可（ビルド依存の問題）
- Azure Functionsのタイムアウトは15分。長時間処理はDurable Functionsを使うこと

## レビュー観点
- N+1クエリのパターンが含まれていないか
- 外部APIのリトライ・タイムアウト設定が適切か

元記事で挙げられた「組織固有の制約」「環境依存の制約」を、このファイルに明文化しておきます。AIレビューがこの制約を踏まえた上で指摘を出してくれます。

CLAUDE.md / AGENTS.md — AIエージェントとの合意文書

Claude CodeやGitHub Copilot coding agentを使う場合、さらに詳細なルールをインストラクションファイルに書けます。

筆者の実案件では、以下を明文化しています。

  • プロジェクトメンバーと役割分担
  • Git操作の許可/禁止コマンド
  • ファイルの格納場所のルール
  • デプロイ手順

このファイルが育つほど、AIへの指示が短くなる。 毎回プロジェクトのルールを説明する必要がありません。仕組みで品質を担保します。

レイヤー2.5: Git履歴から経緯を読み取る

元記事で指摘された「AIに経緯が見えない」問題。実は、経緯の多くはGit履歴に既に記録されている。AIエージェントに読み取り系のGitコマンドを許可すれば、属人性の検証が可能になります。

コマンド わかること
git blame この行を最後に変更したのは誰か
git log --follow このファイルの変更履歴
git diff 何がどう変わったか
git show <commit> 特定のコミットで何をしたか
git log --oneline --grep="fix" バグ修正の経緯

例えば、AIエージェントがレビュー時に git blame で該当コードの変更履歴を確認し、コミットメッセージやPRの説明文を読めば、「なぜこうなっているか」を辿れます。

# この関数を最後に変更した人と理由を確認
git blame src/discount.py -L 42,50
git log --oneline -5 -- src/discount.py

ただし、これが機能するにはコミットメッセージとPRの説明文に理由が書かれていることが前提です。「fix bug」「update code」のようなコミットメッセージでは、AIが読んでも経緯はわかりません。

レイヤー1（コードのコメント）とレイヤー2（インストラクションファイル）に加えて、Git履歴という既存の資産をAIに活用させることで、経緯の可視性が大幅に上がる。

ただし、これは人間の行動を変える必要があるということでもあります。AIが読めるGit履歴を残すために、即座に取り組める具体的なアクションを挙げます。

コミットメッセージを変える

# 悪い例 — AIが読んでも経緯がわからない
git commit -m "fix bug"
git commit -m "update code"
git commit -m "修正"

# 良い例 — AIが「なぜ」を辿れる
git commit -m "割引計算のゼロ除算を修正: 未購入ユーザーの購入回数が0の場合に発生"
git commit -m "リトライ上限を3→5に変更: SLA 99.9%未達のため、インフラチームと協議の上で決定"
git commit -m "asyncio.gatherの並列数を100に制限: 本番で500並列時にOOM発生（Issue #234）"

何をしたかではなく、なぜしたかを書きます。未来のAIと未来の人間が、このコミットメッセージを頼りに判断します。

PR説明文を変える

# 変更内容ではなく、判断の経緯を書く

## なぜこの変更をするか
SLA 99.9%を満たすためにリトライ上限の見直しが必要。
現行の3回では障害時に復旧率が97%にとどまっている（監視ログ参照）。

## 他に検討した選択肢
- リトライ間隔を指数バックオフに変更 → 効果あるが応答遅延が許容範囲を超える
- サーキットブレーカー導入 → 将来的には検討。今回はリトライ上限の変更で対応

## 影響範囲
- リトライ増加により外部APIへの負荷が最大1.7倍に増える
- 外部API側の確認済み（Slack #infra-external 2026-03-25）

レビュアーが「なぜこの方法を選んだか」を理解でき、AIも同じ情報を読める。

コードコメントをAIが理解できる形にする

# 悪い例 — 人間にしか伝わらない
# ここは注意
TIMEOUT = 30

# 良い例 — AIも人間も判断基準がわかる
TIMEOUT = 30  # Azure Functionsの最大実行時間(15min)の半分。超過時は処理を分割すること

# 悪い例 — 経緯がない
# レガシー対応
def convert_old_format(data):

# 良い例 — 経緯があり、いつ削除できるかもわかる
def convert_old_format(data):
    """
    旧フォーマット（v1 API）からの変換処理。
    v1 APIは2026年9月にEOL予定。EOL後にこの関数と関連テストを削除すること。
    参照: https://docs.example.com/api/v1-deprecation
    """

これらは技術力の問題ではなく、習慣の問題です。 次のコミットメッセージを1行変えるだけで、その先のAIレビューの精度が変わります。

レイヤー3: CI/CDによる自動チェック

GitHub Actionsで、前編の「頻出スルー」部分を完全自動化します。

# .github/workflows/code-quality.yml
name: Code Quality
on: [pull_request]
jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Type Check
        run: mypy src/ --strict
      - name: Lint
        run: ruff check src/
      - name: Security
        run: bandit -r src/
      - name: Test
        run: pytest tests/ -v

これが通らないPRはマージできません。人間がレビューで「Typoがある」「型が合っていない」と指摘する時間はゼロになります。

さらに、GitHub CopilotのHooks機能を活用すれば、特定のコマンド実行前にmypyやRuffなどの静的解析を自動で走らせることも可能です。CIを待たずに、開発者の手元で問題を検出できます。Dockerイメージのビルド確認なども、hooksに組み込むことでPR作成前に担保できます。

レイヤー4: レビュープロセスの設計

PRテンプレート — レビュアーの負荷を下げる

元記事で提案された「動的検証ログ」をPRテンプレートに組み込む。

## 変更内容
<!-- 何を、なぜ変えたか -->

## エッジケース検証ログ
- [ ] 不正入力: pytest で再現確認済み
- [ ] 負荷: 本番データ量での動作確認済み
- [ ] 環境制約: Docker build 通過確認済み

## レビューしてほしい観点
- [ ] ビジネスロジックの妥当性
- [ ] 組織固有制約との整合性

何を変えたかだけでなく、なぜ変えたかを書く。 これがあれば、レビュアーはコードの意図を理解した上で「本番で大丈夫か」に集中できます。

GitHub Copilot Code Review — 自動レビューの活用

PRが作成されると、GitHub Copilotが自動的にレビューコメントを付ける設定ができます。Level 1〜3のチェックを通過した上で、AIが「この変更にはこういうリスクがある」と指摘してくれます。

人間のレビュアーは、AIの指摘を確認した上で、AIが見落とした部分だけに集中します。

4つのレイヤーの関係 — ガードレール思想の適用

PRがマージされるまでの流れを整理すると以下の通りです。

ステップ 担当 Pass Fail
1. CI/CD 自動 → 次のステップへ → 自動修正 or 差し戻し
2. Copilot Code Review AI → 次のステップへ → AIの指摘を確認・修正
3. 人間のレビュー 人間 → Approve → マージ → 人間の判断で修正 → 1に戻る

これは筆者がブログ執筆で運用しているガードレールと同じ構造です。

ブログのガードレール コードレビューのガードレール
Gemini Gemでセルフチェック CI/CDで自動チェック
ガードレールGemで最終チェック Copilot Code Reviewで自動レビュー
Slackで人間のフィードバック 人間のPRレビュー
公開可 / 修正後公開可 / 公開不可 Approve / Request Changes / Block

致命的なものだけ止め、残りはフィードバックで育てる。 この原則はコードでもドキュメントでも同じです。

「誰がレビューしても同じ品質」を目指して

元記事で提起された問いに戻る。AIが書いたコードのレビュー、どこを見ればいいか。

答えは人間にしか見えないところだ。構文・スタイル・典型バグはAIとツールが見る。人間はエッジケース・経緯・組織制約を見る。

しかし、この分担を個人の意識に頼っていては定着しません。だから仕組みに埋め込みます。

  • 型ヒントとコメントで、コードに文脈を埋め込む
  • copilot-instructions.mdで、AIにルールを渡す
  • GitHub Actionsで、構文チェックを自動化する
  • PRテンプレートで、レビュー観点を標準化する

仕組みがあれば、誰がレビューしても見るべきポイントが明確になります。 属人的なレビュー品質のばらつきがなくなり、チーム全体の底上げにつながる。

元記事の言葉を借りれば、PRレビューは「儀式」から「意味ある議論の場」に変わる。AIが増やしたコード量を、仕組みで管理する。これがAI時代のコードレビューのあり方だと考えています。

その先にあるもの — レビューの先にある問い

ここまで「AIが書いたコードを人間がどうレビューするか」を書いてきた。しかし、この問い自体が近い将来変わる可能性があります。

社内でもこんな議論が出ています。

AIエージェントの進化速度が速すぎること、そしてAIエージェントの強化プロセスをうまく作ることで、コードレビュー自体の機能の強化ができ始めている。

つまり、レビュー自体をAIエージェントが多層的に行う世界が見えてきています。エッジケースごとに専門のレビューエージェントを作り、それらを多重に組み合わせてレビューさせる。さらにその先には、レビューのフロー自体をケースに応じて自動的に構築するAgentic Workflowの世界があります。

人間のレビュアーが1行ずつコードを読む作業は、いずれほとんどいらなくなるかもしれません。

それでも「今」は人間のレビューが必要

ただし、現時点ではAIにレビューを完全に任せるのは難しいのも事実です。

社内でもこんな声があります。

エージェントのオーケストレーションは実際どうなのか、いけるのかの具体が求められている。案件の中でマルチエージェントの試行錯誤をしたくても、結果が出ないのが怖くて、結局対話型のAI支援開発をやってしまう。

この恐れは自然なものです。しかし、ここで本記事の原則が効きます。致命的なものだけ止め、残りはフィードバックで育てる。 完璧なAIレビューを最初から求める必要はありません。まずは小さく始めて、インストラクションファイルやレビュー基準をフィードバックで育てていけばいい。

フィードバックでは埋められない穴

ただし、正直に書いておくべきことがあります。フィードバックで育てられる品質と、そうでない品質がある。

例えば、社内のあるメンバーがブログを書いたとき、AIが出力した文章に「Haiku」とだけ書かれていました。正しくは「Claude Haiku」です。インストラクションに「技術スタック名は正式名称を使うこと」と書いてあっても、AIがそもそも何が正式名称なのかを正確に把握していなければ、ルールは機能しません。

品質の種類 例 フィードバックで改善できるか
構造的な見落とし エッジケース、組織制約の未考慮 できる（インストラクションに追記）
知識の精度 「Haiku」→「Claude Haiku」、正式名称の誤り 難しい（AIの学習データ・知識に依存）

筆者は以前、AI議事録の固有名詞誤変換を専用ツールではなくコーディングツールのインストラクションで解決する実践を記事にしました。

techblog.ap-com.co.jp

この記事で得た知見は、辞書（AをBに直すリスト）ではなくインストラクション（プロジェクトの文脈）を渡せば、AIは未登録の用語でも文脈から推測できるということでした。しかしそれでも100%ではありません。最終的には人間が固有名詞の正確性を確認する必要があります。

これはコードレビューでも同じです。AIに「Azure Functions」と書くべきところを「Azure Function」と書かれたら、Linterでは検出できません。インストラクションに正式名称一覧を書いても、AIが常に参照するとは限りません。固有名詞の正確性は、現時点では人間が最後に見るしかない領域です。

「全てをAIに任せきれない」は弱さではありません。仕組みで担保できる品質と、人間が最後まで責任を持つ品質を区別すること自体が、仕組みの設計です。

人間に残る仕事

では、AIレビューが成熟した先に、人間に残る仕事は何でしょうか。

  • 仕組み自体を正しく設計すること — ゴールデンパスやガードレールを作り、それが正しく機能しているかを担保する
  • AIエージェントを強化するプロセスとデータを設計すること — インストラクションファイルを育て、フィードバックループを回す
  • ビジネス課題をコンテキストに正確に落とすこと — 技術選定の理由を定義し、AIが判断できる形に翻訳する

これはコードを書くスキルでも、レビューするスキルでもありません。AIと協働するプロセスを設計するスキルです。この段階を設計できる人は、今後しばらくの間、確実に求められる存在になるでしょう。

ある識者がこう表現しています。エンジニアはコードの庭師（Gardener）になると。木を植えるのはAI。庭師は全体のバランスを見て、枝を剪定し、土壌を整えます。個々のコードではなく、コードが育つ環境を設計するのが人間の仕事になります。

技術の継承を仕組みで担保する

ただし注意すべきこともあります。AIにレビューを任せきりにすると、1〜2年は大丈夫でも、その後にどうにもできない崖が見えてくる可能性があります。技術の継承が途絶えると失われる——かつて月面に到達した技術が、取り組みが途絶えたことで継承されずに失われたように。

だからこそ、経緯をGit履歴に残し、インストラクションファイルに合意を明文化し、仕組みを育て続けることが重要です。仕組みは人が変わっても残ります。コードは古くなっても、なぜそう判断したかの記録は残り続けます。

本記事で提案した4つのレイヤーは、コードレビューの仕組み化であると同時に、技術の継承を仕組みで担保する方法でもあります。

お知らせ

私の所属する ACS 事業部では、開発者ポータル Backstage、Azure AI Service などを活用し、Platform Engineering ＋ AI の推進・内製化を支援しています。

www.ap-com.co.jp www.ap-com.co.jp www.ap-com.co.jp

また、GitHub パートナーとしてお客様に GitHub ソリューションの導入支援を行っています。 GitHub Copilot などのトレーニングなども行っておりますので、ご興味を持っていただけましたらぜひお声がけいただけますと幸いです。

一緒に働いていただける仲間も募集中です！ご興味持っていただけましたらぜひお声がけください。 ※求人名の冒頭に【ACSD】と入っている求人が当事業部の求人です」

www.ap-com.co.jp www.ap-com.co.jp

本記事の投稿者: 越川将人