ノートPCとコーヒー、メモ帳が置かれたデスク
設計と運用

Claude CodeのPR説明を<details>で畳む運用手順と効果測定

目次を見る

Claude CodeやCodexのようなコーディングエージェント(AIが自律的にコードを生成・編集するツール)にPRを作らせているチームに向けて、レビュー負荷を下げる具体策を整理します。PR(Pull Request、変更内容をレビューしてマージ依頼する単位)の説明文が長すぎて読み飛ばされる問題は、CI/CDパイプライン全体のリードタイムにも影響します。レビューが滞ればマージが遅れ、デプロイ頻度という品質メトリクスにも響くからです。

現在のAIエージェントは、PR説明文を書く能力が高すぎるという逆説的な課題を抱えています。問題の背景、解決方法、検証手順まで正確かつ網羅的に書いてくれます。ところがその正確さと網羅性が、人間のレビュアーにとっては「読む気を失わせる文字の壁」になってしまいます。内容が信頼できるかどうかと、読もうと思えるかどうかは別問題です。

ここで有効なのが、HTMLの<details><summary>要素を使ってAI生成の長文を折りたたみ、人間が選んだ要約だけを最初に見せる方法です。GitHubのMarkdownはこのタグをそのままサポートしているため、PR説明文やIssueコメントに直接埋め込めます。以下、実際に試せる手順を順番に示します。

前提条件

  • GitHub(またはGitHub Markdownを解釈するGitLab等)でPRを運用している
  • Claude CodeやCodexなど、PR説明文を自動生成するエージェントを使っている、もしくは導入を検討している
  • レビュアーがPR説明文の長さに不満を感じている、またはレビュー遅延が発生している

特別なツールのインストールは不要です。GitHub Markdownの標準機能だけで完結します。

手順1: 折りたたみ構文を確認する

まずは基本構文を手元のIssueコメントやPR説明文で試してみます。

<details>
<summary>Claude Opus 5.5 Medium</summary>

## The hook
Plugins implement `register_agent_reference_types(datasette)`
...

</details>

<summary>に書いた文字列が折りたたみ時の見出しとして表示され、クリックすると</details>までの内容が展開されます。順番を<summary><details>と逆にすると正しく動作しないので注意が必要です。覚え方としては「summaryが先に見える小さい箱、detailsはそれを包む大きい箱」とイメージすると混同しにくくなります。

手順2: PR説明文のテンプレートを作る

次に、人間が書く要約部分とエージェント生成部分を分けるテンプレートを用意します。

## 変更内容
{{ここに1〜3文で、何が課題でどう直したかを人間が書く}}

{{必要ならスクリーンショットを1枚}}

<details>
<summary>{{モデル名 例: Claude Opus 5.5 Medium}}</summary>

{{エージェントが出力した詳細な説明をそのまま貼る}}

</details>

冒頭の要約は「人間が読んで30秒で理解できる分量」を基準に書きます。実例として、テーブルの行ページ再設計PRでは「行ページは1行のテーブルとして表示されており、46列あるGitHubリポジトリのテーブルでは右に大きくスクロールし、画面の大部分が空白になっていた」という1〜2文の説明に、スクリーンショットを添えるだけで十分だったケースがあります。別の例では、JavaScriptファイルの遅延読み込み化PRで「編集機能を使えないユーザーにも220KB前後のedit-tools.jsが毎回読み込まれていた。今後は編集可能なユーザーが編集機能に初めて触れた時だけ読み込む」という説明で要点を伝えています。

手順3: summaryにモデル名と設定値を入れる

<summary>のラベルには、使用したモデル名と推論の強度(エフォートレベル)を入れておくと、レビュアーが「どの程度の思考過程を経て生成されたコードか」を一目で判断できます。「Claude Opus 5.5 Medium」のような表記がその例です。これはAIコード生成の信頼度を評価する簡易的な品質シグナルとしても機能します。

手順4: CIやレビュールールに組み込む

PRテンプレート機能(.github/PULL_REQUEST_TEMPLATE.md)に、この折りたたみ構造を初期状態で埋め込んでおくと、チーム全体で運用が揃います。レビュープロセスのガイドラインに「要約は3文以内」「詳細は必ずdetailsタグ内に格納する」といったルールを明文化しておくと、人によって運用がばらつくのを防げます。

動作確認の方法

実際にGitHub上でPRを開き、以下を確認します。

  • <summary>で指定した文字列だけが初期表示され、右側に展開用の矢印アイコンが出ているか
  • クリックすると詳細な説明文が展開され、再クリックで折りたためるか
  • モバイル版GitHubやGitHub CLIのgh pr viewでも表示が崩れていないか

gh pr view --webでブラウザを開き、レンダリング結果を目視確認するのが最も確実です。

ハマりやすいポイント

<details>タグの直後やタグ内の最初の行に空行を入れないと、中のMarkdown記法(見出しやコードブロック)が正しく解釈されないことがあります。GitHub Markdownのパーサーは、HTMLタグの中にMarkdown構文を混ぜる際、空行の有無で挙動が変わる場合があるため、タグの直後に1行空けてから本文を書き始めるのが安全です。

PR説明文は「正確さ」より「人間が読もうと思えるかどうか」で評価が変わります。要約と詳細を分離する運用は、レビュー速度という品質メトリクスに直接効いてきます。

導入前に確認すること

この運用はツールの新規導入を伴わないため、今日のPRから試すことができます。

  • 直近のAI生成PRを1件選び、冒頭に1〜3文の人間要約を追加して<details>で残りを畳んでみる
  • チームのPRテンプレートに折りたたみ構造をデフォルトで組み込む
  • レビューにかかる時間が体感で短縮されたか、次のスプリントで振り返る

小さな変更ですが、レビュー負荷が減ればマージまでのリードタイムが縮み、結果としてリリースサイクル全体の速度にも良い影響が期待できます。

参考

Hide your slop PR descriptions behind <details><summary>

AI 駆動開発のご相談は forva AI へ。

まずはお気軽にどうぞ。