最近、私がプロジェクトに対して行う変更の大部分は、Claude Code や Codex が作成してくれた PR(Pull Request)という形を取っています。PR は私の作業単位です。複数のコミットをまとめ、機能が完成するまでイテレーションを重ね、意思決定を記録し、最終的に完成した成果物をマージするために使っています。昨今のコーディングエージェント(coding agent)は、PR の説明文を書くのが非常に得意です。
仕事の説明があまりにも上手すぎる
問題は、彼らがあまりに上手すぎることです。エージェントが生成する PR の説明は、正確かつ詳細を極めています。問題そのもの、詳細な解決策、そしてその解決策を検証するために踏んだ手順まで説明してくれます。しかし、これは消化するには情報量が多すぎるのです。
必ずしも粗悪なゴミ(slop)というわけではありませんが、読んだ感じはまさにそれなのです!
どの PR が AI によるものかは一目で分かります。他の AI 生成テキストと同様、私の最初の反応は大抵「長すぎて読む気がしない(I’m not reading all of that)」です。どれほど正確で有益な情報であったとしても、自分が読むのにかかる時間のほうが、作者がそれを書くのにかけた時間よりも長いかもしれないと思った瞬間、急速に興味が失せてしまいます……たとえその主導した作者が自分自身だったとしても!
私が求めているのは、人間による編集上の判断です。誰かがほんの少しでもこの PR について考え、人間の手でレビューされた簡潔な要約を提示してほしいのです。それがあれば、この PR が何をするものなのか、もっと時間を割いて見る価値があるのかを大局的な視点から把握できます。
手間がかからず、かつ非常に快適な方法を見つけたと思います。
大半の内容を details/summary タグの中に隠す
HTML の <details><summary> 要素は、折りたたみ可能な見出し(summary)としてレンダリングされ、展開すると長文のテキストを表示できます。コードは次のようになります。
<details> <summary>Claude Opus 5.5</summary> <h2>The hook</h2> Plugins implement <code>register_agent_reference_types(datasette)</code>...</details>レンダリング後の見た目は以下のようになります:

最も重要なのは、GitHub Markdown が <details><summary> をネイティブにサポートしている点です。Issue のコメントや PR の説明にこれらのタグを直接書き込むだけで、GitHub は詳細を自動的に隠し、概要行と展開用の矢印だけを表示してくれます。
私は、自分が生成する AI PR でこの手法を使い始めました。
私の PR の冒頭の段落は、変更全体を大まかに説明するものとして慎重に選んでいます。人間の読者が最短時間で読めるようなテキストで、素早く全体像を把握できるようにするためです。
新機能をすばやく説明するには画像が一番手っ取り早いことも多いので、スクリーンショットを添えることもあります。
その後に、エージェントが書いた完全な「長文」を <details><summary> で囲みます。コンテキストを明確にするため、通常はモデル名(多くは思考深度/エフォートレベルも併記)を summary のテキストにします。例えば「Claude Opus 5.5 Medium」といった具合です。
これで、私の PR からは AI 特有のゴミ感(slop 感)がすっかり消えました!すべての情報はそのまま残っていますが、読者はエージェントが書いた長大な詳細に圧倒されることなく、人間によって厳選された最もコアな重要情報をひと目で把握できます。
冒頭の紹介文を必ずしも自分で一から書くわけではありません。エージェントがすでに意図通りの内容を出力しているものの、膨大なテキストの中に埋もれてしまっている場合もあります。私が読者に対して約束しているのは、「この短い冒頭文は私という人間の判断力を反映したものであり、本当に時間をかける価値のある情報が何であるかを明確に伝えている」ということです。
以下は、私が最近このパターンを適用した実例と、その際に使用した導入文です:
- datasette PR #3052: Redesign row page as a vertical list of fields - 「行詳細ページはこれまで、単一行を 1 行だけのテーブルとして表示していました。列数が多いテーブル(例えば 46 列ある GitHub の
reposテーブルなど)の場合、コンテンツが右側に大きく延びてしまい、ページの大部分に余白ができていました」(この後にスクリーンショットが続く) - datasette PR #3043: Pagination bar showing which rows are on the current page - 「複数ページにまたがるテーブルページで、現在どの位置にいるかが明確に表示されるようになり、ページの上部と下部の両方にナビゲーションが追加されました」(スクリーンショット付き)
- datasette PR #3042: Load edit-tools.js on demand via a small loader - 「
edit-tools.js(約 220KB)はこれまで、何も編集できないユーザーも含め、すべてのテーブル、行、データベースページで読み込まれていました。これを、編集権限を持つユーザーが編集機能と初めてインタラクションした際(編集リンクにマウスホバーした際を含む)にのみ、オンデマンドで読み込むように変更しました」 - datasette-agent PR #51: register_agent_reference_types plugin hook - 「プラグインが新しい
register_agent_reference_types(datasette)プラグインフックを介して、チャット入力欄の#タグに独自のアイテムタイプを追加できるようにしました」——上の画像のとおり。 - llm PR #1838: Add llm openai endpoint add/list/remove/path commands - 「
extra-openai-models.yamlに記録された内容を管理するコマンドを追加しました。これにより、手動で YAML を編集することなく、コマンドラインから OpenAI 互換エンドポイントを保存できるようになります」——この後に--helpの出力が続く。
覚えるためのコツ
私は以前、この 2 つのタグの順序がどちらだったか(<details><summary> なのか <summary><details> なのか)をしょっちゅう忘れていました。
そこで役に立ったコツが 2 つあります。
まず 1 つ目、そして最も明確な点として、<summary> は明らかに詳細(details)を要約(summarize)するためのものです。クリックして展開できる 1 行のテキストに対応するタグなので、必然的に <details> 要素がそれ以外のすべてを内包することになります。
もうひとつのより優れたコツは、この 2 つのタグを常に「details-summary」と発音することです。
「details-summary」は 2 音節の後に 3 音節が続きます。「summary-details」という 3 + 2 の組み合わせよりも、はるかに口になじんで言いやすいのです。
「details-summary」と何度か声に出して言ってみてください。二度とタグの順序を間違えなくなるはずです。
(それでも、GitHub が Markdown エディタにこのためのボタンを追加してくれたらいいのにとは思っています。スマホのキーボードでわざわざタグを打ち込む手間が省けますし、より多くの GitHub ユーザーにこの機能の存在を知ってもらえるからです。)