Claude Codeの回答を読みやすくする：認知負荷を減らした3つの工夫

Claude Codeが作業を終えたあと、その回答を読むのにコードレビューと同じくらい集中力を使うことがありました。

繰り返し確認していたのは、次の3つです。

• 結論は何か？
• それぞれの処理はどうつながっているのか？
• 自分がやることはあるのか？

これらを見つけやすくするために、i-have-adhdスキル、図を使った説明、長い文章を避けた構造化された回答、という3つの工夫を始めました。

※本記事は英語から日本語へ ChatGPT を使って翻訳しています。

先に要点：取り入れた3つの工夫

読みにくかった理由	取り入れたもの	読みやすくなった点
長い説明の中に結論が埋もれる	i-have-adhdスキル	結論と次の行動が最初にわかる
処理同士のつながりをイメージできない	ラベル付きの小さな図	詳細を読む前に流れがわかる
必要な情報を探すために段落を読み返す	箇条書き・表・番号付きの手順	判断事項・変更点・作業を妨げている問題を見つけやすい

理解に必要な説明は残します。知らない用語は、回答が長くなっても説明してもらいます。

以下の例は、実際の作業で受け取ったClaude Codeの回答です。プロジェクト名とテーブル名は変更しています。
引用部分は日本語に訳しています。語数は英語の原文のものです。

1. スキルを使って、結論を見つけやすくする

きっかけは、Claude Codeのプラグインとして使えるi-have-adhdというスキルでした。

このスキルには、すぐ行動に移せる回答を最初に示す、手順に番号を付ける、不要な前置きを省く、といったルールがあります。

回答を読み終えてから「それで何をすればいいのか」を考え直す負担を減らしてくれます。

同じ質問に対する2つの回答です。左が元の回答、右が整理された回答です。どちらもMarkdownのまま表示しています。

元の回答（430語）

整理された回答（40語）

**はい、移しましょう。** 根拠を見ても妥 当な判断です。ただし、本当の障害が1つあ ります。   **すでにあるもの**（`admin-app`）   | 要素 | 状態 | |---|---| | `ADMIN` / `AREA_ADMIN` による認証 | 最 後まで接続済み。トークンはBFFセッション でサーバー側に保持 | | 画面40 申請一覧 | あり — `views/applications.ejs` | | 画面43 申請詳細＋承認/却下 | あり — `views/application.ejs`。`app.items[]` を待つ項目別セクションもすでにある | | 拠点QRコードの発行 | あり — `views/join-tokens.ejs`。npmの `qrcode` でQRを生成 | | バックエンド | `backend/src/adminApi.ts` — 今開いている ファイル |   **唯一の障害 — 設計上、JavaScriptを使わ ないアプリ**   `server.js:58` が `scriptSrc: ["'none'"]` を設定しています。確認済み： どのビューにも `<script>` タグは0個で、 `public/` には `app.css` しかありません。   6画面への影響：   | 画面 | JavaScriptが必要 | そのまま使え る | |---|---|---| | 40 一覧、41 拠点情報、43 審査、44 説明、 46 証跡 | 不要 — 通常のフォームPOST | は い | | 45 時刻付き承認 | 不要 — POST時にサー バーが時刻を記録 | はい | | **42 カメラでのQR読み取り** | **必要** | **いいえ** |   画面42の参照コード入力は通常のフォームで 動きます。JSが必要なのはカメラでの読み取 りだけで、そのためには `script-src` を緩 める必要があります。READMEによると、これ は意図的なセキュリティ方針です。   **コストをはっきり言うと：** 私が `/admin/*` に作った6ページは**移植ではな く破棄**になります。EJS＋サーバー描画の フォームは、React＋MUIと共通部分がありま せん。`registrationService` の契約とその モックはフロントエンドのTypeScriptなので、 これも移りません。作業量はEJSビュー約6つ とルートで、バックエンドはすでに40と43を カバーしています。   **そのまま残るもの：** `frontend` の利用 者向けフロー。機能は2つのリポジトリにま たがります（利用者向けはReact、スタッフ 向けはEJS）。これは現在の分担と同じです。   **私の推奨：** 移す。6画面のうち5画面は JS不要、2画面はすでに存在し、認証と拠点 ごとの範囲指定も完成しています。画面42は 別に決めてください。まず参照コード入力を 出し、カメラ読み取りはCSPの判断を含む別 の要望として扱います。   **スタイル調整の状況：** 利用者向けの読 み取り画面はデザイン見本と一致しました （中央の枠、オレンジの角、走査線、紺色の CTA、枠線付きの2つ目のボタン。計測済み： 原因はMUI Stackの子要素 `margin: 0` リセ ットが詳細度0,1,2で、私の0,1,0のルールに 勝っていたこと。32個のセレクターをすべて 二重にしました）。画面02〜08のキャプチャ は取りましたが、まだ**確認していません**。 開いて見るまでは正しいとは言いません。   **次：** 移行を進めるよう指示してくださ い。`/admin/*` の調整をやめ、利用者向け 画面の確認だけを終わらせます。

**はい。スタッフ向けページを`admin-app` に移しましょう。**   問題が1つあります。カメラでのQRコード読 み取りにはJavaScriptが必要ですが、このア プリはJavaScriptをすべて禁止しています （`server.js:58`）。参照コードの手入力は 問題なく使えます。   私が作成したReactのスタッフ向けページ6つ は、移植せず破棄することになります。   確認いただければ着手します。

短い回答には、結論・問題・失うもの・次の行動が1つずつ残っています。

関係のない進捗報告はなくなりました。

試すには、ターミナルで次のコマンドを実行し、Claude Codeで/i-have-adhdと入力します。詳しくは、プロジェクトのインストール手順を参照してください。

claude plugin marketplace add ayghri/i-have-adhd
claude plugin install i-have-adhd@i-have-adhd

毎回コマンドを入力せず、すべてのセッションでスキルを読み込むには、次のファイルを作成します。

touch ~/.claude/.i-have-adhd-always

2. つながりを理解したいときは、先に図を描いてもらう

誰がリクエストを送り、サーバーが何を返し、画面に何が表示されるのか。複数の要素を関連付けて理解する必要がある説明もあります。

そういうときは、先に小さな図を描いてもらいます。

たとえば、HTMLフォームとJavaScriptのfetch()を比較した回答は、次の図から始まっていました。

HTMLフォームで送信                     fetch()で送信
──────────────────────────          ──────────────────────────
[問い合わせページ]                     [問い合わせページ]
     │「送信」をクリック                     │「送信」をクリック
     │ ブラウザーが別ページへ遷移              │ JSがバックグラウンドで送信
     ▼                                    │ ページはそのまま
  POST /f/abc123                         POST /f/abc123
     │                                    │
     ▼ 302リダイレクト                      ▼ {"ok":true,...}
[完了ページ]                           [問い合わせページ]
 URLが変わる                            同じURLで「送信しました」と表示

左側は別のページへ移動し、右側は今のページの表示を更新します。

リクエストヘッダーやレスポンス形式の説明を読む前に、その違いがわかります。

ルールはシンプルです。

流れや関係を説明するときは、ラベル付きの小さな図を最初に1つ示す。
単純な回答や、値を1つ答えるだけのときは図を使わない。
表示環境が対応していればMermaidを使う。
対応していなければ、text指定のコードブロックに文字で図を描く。

3. 段落の代わりに、決まった形式で答えてもらう

見出しが付いていても、必要な情報を探さなければならない回答はあります。

そこで、質問に合わせて回答の形式を変えてもらうようにしました。

質問	回答の形式
これはできる？	結論 → 条件や制約
何が変わった？	変更点ごとに箇条書き
どの選択肢が合う？	小さな比較表
なぜ失敗する？	わかったこと → 影響 → 修正方法
どう進めればいい？	番号付きの手順

実際に、SQLクエリ1つの前後に6つの段落があり、全体で183語という回答がありました。

「too much prose（文章が多すぎる）」と返すと、次の回答は72語になりました。

内容は私のプロジェクト固有のものなので、ここでは回答の形だけ見てください。

元の回答（183語）

整理された回答（72語）

**必要ありません。この機能はApp Bとの紐 付けを一切使いません。**   このコードが読むのは1つのテーブルだけで、 対象も`system_a`だけです。   ```sql SELECT DISTINCT l.external_site_id AS office_id FROM site_system_link l WHERE l.canonical_site_id = ANY($1) AND l.system_name = 'system_a' ```   受け取る`canonical_site_id`はすでに特定 済みの値で、確認するのは「System Aのどの 事業所か」だけです。   App Bとの紐付けは、それより前にフェーズ1 の申請フローで使われます。ユーザーが選ん だ拠点を共通拠点に変換するためです。これ は同期処理が存在する前に行われ、この機能 を削除しても行われます。   **つまり、フェーズ2でリリース時に追加す るのは`system_a`との紐付けだけです。** 条件は、新しい共通拠点ではなく、申請がす でに特定している共通拠点に追加することで す。これが先ほど説明した初期データ投入ス クリプトの問題です。スクリプトは既存の共 通拠点に紐付けず、事業所ごとに新しい `canonical_site`を作成してしまいます。   私は「この機能が必要とするもの」と「この 機能が配信を作るために必要なもの」を混同 していました。正しいのは後者だけで、それ はApp Bとの紐付けそのものではなく、紐付 けをどこに追加するかの問題です。

**いいえ。必要ありません。**   - このコードが`site_system_link`から取 得するのは、`system_name = 'system_a'` のデータだけです。 - 入力として受け取る `canonical_site_id`は、すでに特定済み です。 - App Bとの紐付けはフェーズ1の役割です。 ユーザーが選んだ拠点に対応する共通拠点 を特定します。   **フェーズ2でリリース時に追加するものは1 つです。** `system_a`との紐付けを、新し い共通拠点ではなく、すでに存在する共通拠 点に追加します。初期データ投入スクリプト は新しい共通拠点を作成してしまうため、そ こが問題です。

私はこれを「no-prose」ルールと呼んでいます。開発中の報告では、段落よりも箇条書き・表・手順を優先してもらう、というルールです。

この形なら、回答を全部読まなくても必要な部分を見つけられます。

短い回答にも、理解に必要な説明は残す

文章を減らしてもらった結果、かえって理解しにくくなることもありました。

第2節のHTMLフォームとfetch()について、実際に受け取った3つの回答を比べると、こうなります。

回答	語数	読んだ感想
最初の回答	896	文章が多すぎる
スキルを有効にした短い回答	136	短すぎる。使ったことのないCloudflareの機能名が、説明なしで出てくる
順を追った詳しい説明	913	最後まで読めた

理解できた回答は、3つの中で最も長いものでした。

新しい概念ごとに見出しがあり、用語を使う前に意味が説明されていました。見出しの数も、最初の回答の2個に対して11個ありました。

第2節の図も、この詳しい説明に含まれていたものです。

今は、次のようにお願いしています。

• すでに理解している話題なら、短く答える。
• 学習中の話題なら、新しい概念ごとに節を分ける。
• 専門用語が初めて出てくるときは、平易な言葉で意味を説明する。

まず試せる、小さなCLAUDE.mdの設定例

私が使っている指示を短くまとめると、次のようになります。

## 回答のスタイル
- 結論、判断、または現在作業を妨げている問題から書き始める。
- 調査結果は箇条書き、手順は番号付きリスト、比較は表を優先する。
  長い段落で説明し続けない。
- 流れや関係を説明するときは、ラベル付きの小さな図を最初に示す。
  単純な回答には図を使わない。
- なじみのない用語は、最初に使うときに意味を説明する。
  新しい概念は無理に圧縮せず、それぞれ短い節に分ける。
- 私の入力が必要なときは、具体的な質問や依頼を最後に示す。

これらはモデルへの指示であり、毎回必ずこの形式になることを保証するものではありません。この違いは、Claude Codeの指示ファイルに関するドキュメントでも説明されています。

「結論を先に」「図にして」「文章が多すぎる」。何度も入力している修正依頼を、まず1つ、明確なルールとして書いてみてください。