生成AIの登場でコード生成の生産性は急速に高まっているとされてます。ホントか？ まぁほんとなんでしょう。実際、数分でコードを生成できる時代になりました。 ただ、そのような生産性の伸びに比べて、品質を確保する人間の負荷は変わっていません。バグがあったら「生成AIが悪いんです」なんて言えないし。なので、pull request（以下PR）のレビューについても、AIが書いたコードを結局のところ人間が見なければいけません。つらい。つらいね。そのレビューの生産性が全然追いついていないのが、今の開発現場の実情です。
僕のチームもこの問題に直面して、何とかならないかと思い立ちました。ビュアーの認知負荷を下げられるPR作成用カスタムslash command。Mermaid図で変更箇所を視覚化することで、テキストだけの説明より格段に理解しやすくなりますし、試してみた価値があると思っています。
- 生成AI駆動開発における PR レビューのボトルネック
- PR のための Claude Code カスタム slash command
- Mermaid 図による認知負荷の低減
- PR テンプレートと自動生成の実装
- 実際の改善効果
- まとめ
生成AI駆動開発における PR レビューのボトルネック
生成AIでコード生成が高速化した反面、レビューの生産性は全然上がっていません。これが今の開発現場の悩みです。
reviewerがPRを見たときの最初のハードルは、authorが「何を」「なぜ」やったのかをざっと理解し、頭の中にPRの地図を作ることではないでしょうか。これがないと、コードを1行ずつ読むしかなくなり、全体像が見えなくなります。結果、細かい指摘で終わって、本当に必要な構造的な問題が見落とされることもあります。
本来ならauthorが「このPRではこういった背景があって、こういう課題をこう解いた」と説明すればいいわけですが、authorも忙しい。毎回丁寧に説明文を書いていたら時間がありません。だからreviewerが勝手に汲み取るしかなくなり、reviewerの負荷が増えるばかりです。
この「reviewerの認知負荷が低くなるように、PRの説明をちゃんと書く」という部分を自動化したら、author側の負荷も下がるし、reviewer側も素早く全体像を掴められます。そういう考えで、このslash commandを作りました。
PR のための Claude Code カスタム slash command
作ってみたのは、Claude Codeのカスタムslash command /prです。このコマンド一発で、PRの説明を整形して作成・更新してくれるわけです。
主な機能は以下の通りです。
- PRテンプレートに従った構造化された説明の自動生成
- 変更箇所を視覚的に理解できるMermaid図の自動追加
- 既存PRの自動更新対応
- GitHub MCP Serverを活用したGitHub APIへのシームレスなアクセス
プロンプトは以下の記事をめちゃくちゃ参考にさせていただきました。
Mermaid 図による認知負荷の低減
PR説明が文字だけだと、reviewerは脳内でコード全体の流れを組み立てなければいけません。特にデータフロー変更とか責任分離の修正みたいに複雑な変更があると、認知負荷がぐっと上がります。疲れるし、見落としも増えます。
ここで活躍するのがMermaid図です。フローチャートやアーキテクチャ図で「こうなる」というのを目で見せてやれば、reviewerはあっという間に全体像を掴めるはず。以下は、このslash commandが自動生成するMermaid図の例です。
処理フロー全体が目で見えると、reviewerはまず全体像を掴んでから、細かいコードを読むという流れになります。つまり、効率的に読めるようになるわけです。
PR テンプレートと自動生成の実装
このslash commandの仕掛けは、以下のPRテンプレート構造を基盤としています。
前提（なぜこのPRが存在するのか）
- 背景（背景要因）
- 課題（Problem）
目的（このPRが達成するゴール）
- 背景と課題を踏まえたうえでの目的明示
変更内容（What）
- レビュアーが迷いづらい書き方で「変えた事実」を列挙
- 単なるコードdiffではなく「どこがどう変わったか」というレベルの説明
変更のスコープ（どこまで含む／含まない）
- 本PRに含めた範囲
- あえて含めなかった範囲
動作確認方法
- テスト実行手順の具体化
リスク・注意点
- レビュアーが気づきづらい箇所の明示
このslash commandが動くからくりは、このテンプレート構造を自動で抽出して、gitの情報（diff、コミット履歴）と合わせてPR説明を作ってくれるわけです。同時に、変更の性質に応じたMermaid図も自動生成されます。だからreviewerの認知負荷ががっと下がる…下がってほしいな。
GitHub MCP Server と Docker outside of Docker
ちなみに、Zennの記事ではghコマンドを使ってPRを作成していたんですが、僕のチームは結構環境がバラバラなので、GitHub MCPサーバを使うようにしています。
GitHub MCPサーバはコンテナで提供されているのですが、devcontainer上で動かすとコンテナ作成都度、毎回新しくdocker pullが走って、時間がかかります。ghcr.ioからのPULL、なぜかdocker hubからのpullとは比較にならないくらい時間がかかった。なんなんだ一体。
ここで役に立つのがDocker outside of Docker（DooD）という仕組みです。
DooDは要するに、devcontainer内のコマンドがホスト側のDockerデーモンにアクセスして、その中のイメージを流用するわけです。初回こそイメージのダウンロードがかかりますが、2回目以降はホスト側のキャッシュを使うから、起動がめちゃくちゃ速くなります。devcontainerを立ち上げるたびにdocker pullが走るなんて大変ですからね。
.devcontainer.jsonにfeatureで入れるだけ。
"features": { "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {} },
実際の改善効果
ここまでで実感できるのが、このslash commandの効果です。Before/Afterで見ると、こんな感じです。実際の時間は嘘っぱちで、これはClaudeが勝手にそう言っていた。
まとめ
レビューボトルネックを解決するのは待ったなしの課題です。このslash commandをなんとかその一助にしたい。実はチームで使っているのはGitLabなので、これをGitLab用に移植すれば良いはず。
効果をまとめます。
- Authorの負荷軽減: コマンド一発でPR説明が出来上がります。説明文を毎回手書きする大変さから解放されます
- Reviewerの認知負荷低減: 構造化された説明とMermaid図で、全体像をさっと掴められます。細かい指摘に時間を使わずに済みます
- チーム全体の効率化: Authorも説明作成に時間をかけず、Reviewerも素早く理解できます。
GitHub MCP ServerとDocker outside of Dockerの組み合わせで、devcontainerの開発環境も安定して、高速にClaude CodeのAI機能を使えます。
