はじめに
仕事でClaude Codeを毎日のように使っています。
コードの調査やバグの原因究明はかなり優秀で、正直もう手放せません。
ただ、ひとつだけ困っていることがありました。
返ってくる説明が難しい。
専門用語とカタカナ語が並んだ、たぶん正しいことを言っている文章。
でも読み解くのに時間がかかって、結局自分でコードを追い直すことになる。
それでは何のために聞いたのかわかりません。
毎回「もっと簡単に説明して」とお願いするのも面倒なので、CLAUDE.mdに説明の仕方のルールを書いておくことにしました。
CLAUDE.mdとは
Claude Codeがセッション開始時に自動で読み込む指示ファイルです。
「毎回口頭で言っているお願い」を置いておく場所だと思ってください。
今回のルールは「自分が読みやすいかどうか」という個人の好みの話で、プロジェクトを問わず効いてほしいので、全プロジェクトに適用される ~/.claude/CLAUDE.md に置いています。
実際に書いたルール
# 説明の仕方
- できる限り平易な言葉で説明する。専門用語・カタカナ語は避けるか、使うときは一言で言い換えを添える。
- 結論を先に、短い文で。長い前置きや遠回しな表現はしない。
- たとえ話や具体例を使って、イメージしやすく説明する。
- 技術的な正確さ(ファイル名・行番号・コミットID・関数名などの根拠)は、本文で読みやすさを優先しつつ、末尾に「備考」としてまとめて残す。本文を平易にするために根拠を削ってはいけない。
例:
(本文) xxx
**備考**
- 原因:
- 修正:
それぞれのルールの意図
1. 平易な言葉で説明する
ポイントは「専門用語を禁止する」のではなく「使うなら言い換えを添えさせる」ところです。
完全に禁止してしまうと、今度は遠回しな説明になって逆に長くなります。
用語そのものは使ってもらいつつ、初出で一言補足してもらうくらいがちょうどいいバランスでした。
2. 結論を先に
放っておくと「まず前提を整理します」から始まりがちです。
知りたいのは結論なので、先に言ってもらいます。
3. たとえ話を使う
抽象的な仕組みの話は、身近なものに置き換えてもらうと理解しやすくなります。
4. 根拠は「備考」に退避する ← これが本命
このルールがなかったら、この取り組みは失敗していたと思います。
単に「簡単に説明して」とだけ書くと、Claudeは読みやすさを優先して根拠を削ってしまいます。
ファイル名も行番号も消えた、雰囲気だけわかる説明が返ってくる。
これでは裏取りができず、結局コードを追い直すことになります。
なので、役割を分けました。
- 本文 … 理解するためのもの。平易でよい
- 備考 … 検証するためのもの。正確でなければならない
わかりやすさと正確さはトレードオフになりがちですが、置き場所を分ければ両立できます。
本文で「何が起きているか」を掴んでから、備考でコードを確認しに行ける。
この流れになってから、調査のスピードが明らかに変わりました。
使ってみて感じたこと
よかったこと
- 読み解く時間が減った。そのまま理解できるので、読み返しが不要になった
- 「わかった気になっているだけ」に気づきやすい。備考のコードを見て納得できなければ、本当は理解できていないということ
注意点
- たとえ話は正確ではありません。あくまで理解の入り口として使い、最終的な判断は必ず備考のコードを確認してから行う、という前提を崩さないようにしています
- ルールは短く保つのがコツです。公式ドキュメントでも、指示は具体的かつ簡潔なほど一貫して守られるとされています。あれこれ書き足すと守られにくくなります
- 効いていないと感じたら、
/memoryでどのファイルが読み込まれているか確認できます
おわりに
念のため書いておくと、これは「難しいことを理解しなくて済むようにする」取り組みではありません。
むしろ逆で、理解に取りかかるまでの時間を短くするための補助です。
平易な説明はあくまで入り口で、最終的には備考のコードを読み、用語の意味を自分で調べて、腹落ちさせる必要があります。
たとえ話だけで納得して終わらせてしまうと、次に似た問題が出たときに何も残っていません。
実際、たとえ話で「わかったつもり」になったあとに備考を読んで、全然わかっていなかったと気づくことも普通にあります。
その上で、入り口が低いことには価値があると思っています。
短いルールで毎日の読み解きが軽くなるなら、試してみる価値はあるはずです。