結論から言うと、Claude Codeの出力精度を上げたいなら、指示を増やすんじゃなくて『減らす』のが正解だった。
自分はClaude Codeを使い始めた頃、とにかく細かく指示を書いていた。コーディングスタイル、命名規則、インデント、importの順番。気づけば指示だけで200行を超えていた。結果どうなったかというと、逆に精度が落ちた。指示同士が矛盾して、Claudeが混乱していたんだと思う。
この記事は、こんな人に向けて書いている。
- Claude Codeを使い始めたけど、毎回同じことを説明している
- CLAUDE.mdは作ったけど、何を書けばいいか分からない
- 指示を増やしたのに、なぜか精度が上がらない
ここで止まってる人ほど見てほしい。自分が試行錯誤して見つけた「書くべきこと」と「書かないこと」を全部まとめた。
CLAUDE.mdとは何か — Claude Codeの『設計図』になるファイル
CLAUDE.mdは、プロジェクトのルートに置くMarkdownファイルだ。Claude Codeはセッション開始時にこのファイルを自動で読み込んで、その内容をセッション全体の判断基準にする。
ポイントは「セッション全体に効く」という部分。Claude Codeがコードを調べるとき、実装を考えるとき、テストを実行するとき、すべてのフェーズでCLAUDE.mdの指示が影響する。たとえば「テストはpnpm testで実行する」と一行書いておくだけで、セッション中に何十回テストを実行しても毎回正しいコマンドが使われる。
逆に言えば、ここに矛盾した指示や曖昧な記述があると、セッション全体がグダグダになる。効くんですよ。地味な設定ファイルが。
Claude Codeのシステムプロンプトには、もともと約50個の組み込み指示が入っている。LLMが安定して従える指示の上限は150〜200個程度とされていて、それを超えると精度が落ち始める。つまりCLAUDE.mdに書ける「実質的な指示枠」は100〜150個しかない。この枠をどう使うかが、出力の質を左右する。
書くべき3つの柱 — 「何を」「なぜ」「どうやって」
CLAUDE.mdに書くべき内容は、大きく3つに分かれる。
柱1:「何を」 — プロジェクトの構造を伝える
Claude Codeは自分でコードを探索できるけど、プロジェクト全体の構造を把握するのは苦手だ。特にモノレポや複数サービスがあるプロジェクトだと、どのディレクトリが何を担当しているのか分からないまま作業を始めてしまう。
だから、プロジェクトの全体像を簡潔に書く。使っている言語、フレームワーク、ディレクトリ構成、主要なツール。ここは事実だけでいい。
自分の場合、「APIはPython、共通処理はcoreディレクトリ」くらいのシンプルな記述でも、Claude Codeの動きが明らかに変わった。何も書かないと、コードを読み始めるまでに無駄な探索時間が発生して、トークンだけが溶けていく。ナビなしで知らない街走ってたようなもんだった。
柱2:「なぜ」 — 設計判断の理由を伝える
ここが一番見落とされやすくて、一番効果が高い部分だ。
たとえば「DBのクエリはリポジトリパターンで書く」というルールがあるとする。「なぜ」が書いてないと、Claude Codeはルートハンドラに直接クエリを書くかもしれない。技術的には間違いじゃないけど、アーキテクチャとしては違反だ。
「テストしやすくするためにリポジトリパターンを採用している」と一文添えるだけで、Claude Codeは既存のリポジトリを探して、そのパターンに従ってコードを書くようになる。
自分が実際にやって効果が大きかったのは、「エラーハンドリングは共通モジュールに集約している。理由は、呼び出し元ごとに例外処理を書くとメンテが破綻するから」という記述だ。こういう「なぜ」があると、Claude Codeは新しい機能を追加するときも自然と共通モジュールを使ってくれる。指示してないのに。
これ、半年前に知ってたらどれだけ手戻りを減らせたか。
柱3:「どうやって」 — コマンドとワークフローを伝える
テストの実行コマンド、ビルドコマンド、デプロイ手順。これが書いてないと、Claude Codeはデフォルトのコマンドを試す。そして大体失敗する。
npm testじゃなくてpnpm testだとか、環境変数ファイルを事前にコピーする必要があるとか。自分の環境固有の手順をここに書いておく。
コミットメッセージの形式（Conventional Commitsなど）やブランチ戦略もここに含める。Claude Codeにコミットまでやらせるなら、この情報がないとカオスになる。自分はコミットメッセージのフォーマットを1行書いただけで、手動での書き直しがほぼゼロになった。
書かないことが一番大事 — 指示は増やすほど精度が落ちる
ここが急所だった。まさに。（気づくの遅すぎたけど）
リンターの仕事を奪わない
インデントのルール、セミコロンの有無、importの順番。こういうのはESLintやPrettier、Biomeに任せるべきだ。CLAUDE.mdに書くと、AIが毎回トークンを消費してスタイルを判断することになる。リンターなら0トークンで確実に統一できる。
自分も最初は「シングルクォートを使え」「インデントは2スペース」みたいなルールを20個くらい書いていた。全部消してリンター設定に移したら、トークン消費が目に見えて減った。LLMにやらせるな、ツールにやらせろ。
タスク固有の指示を入れない
CLAUDE.mdはセッションをまたいで全部のタスクに適用される。「今回のリファクタリングでは既存のAPIを壊さないように」みたいな指示は、次の全く別のタスクでも読み込まれて、無駄に判断を複雑にする。
タスク固有の指示はセッション中に直接伝えればいい。CLAUDE.mdには「常に適用すべきルール」だけを書く。この切り分けだけで、体感2割くらい応答の精度が上がった。
ドキュメントのコピペはしない
READMEの内容やAPIドキュメントをCLAUDE.mdに貼り付ける人がいるけど、やめたほうがいい。Claude Codeはファイルを読める。「APIドキュメントは/docs/api.mdを参照」と書くだけで、必要なときに自分で読みに行く。指示枠をドキュメントのコピペで埋めるのは、本当にもったいない。
階層構造を使いこなす — グローバルからディレクトリ単位まで
CLAUDE.mdは1箇所に置くだけじゃない。Claude Codeは階層的な設定ファイルをサポートしている。
~/.claude/CLAUDE.md— 全プロジェクト共通の個人設定- プロジェクトルートの
CLAUDE.md— プロジェクト固有のルール - サブディレクトリの
CLAUDE.md— ディレクトリごとの上書き CLAUDE.local.md— 個人用のローカル設定（.gitignoreに自動追加される）
自分はこの階層構造を知ったとき、ガラッと運用が変わった。それまで全部プロジェクトルートに書いていたのを、グローバル設定・プロジェクト設定・ディレクトリ設定に分離した。
グローバルには「日本語で応答する」「コミットメッセージは日本語」といった個人の好みを書いて、プロジェクトルートには技術スタックと設計方針を置く。そしてサブディレクトリには局所的なルールだけ書く。
これって、チーム開発における.eslintrcの継承と同じ考え方だ。近いファイルが優先される。一度この構造にしてしまえば、新しいプロジェクトを始めるときもグローバル設定は書き直さなくていい。地味だけど、積み重なると効いてくる。
CLAUDE.mdを整理して実際に変わったこと
自分はClaude Codeを実務で毎日使っている。コードのリファクタリングを依頼したり、新機能の設計を相談したり、既存コードの改善点を洗い出してもらったり。
以前はセッションのたびに「このプロジェクトはPythonで、この共通モジュールを使って、テストはこのコマンドで……」と毎回説明していた。100万回コピペする羽目になるところだった（体感）。
CLAUDE.mdを整理してからは、セッション開始直後から的確なコードが出てくるようになった。特に効果が大きかったのは「なぜ」のセクションだ。設計判断の理由を書いておくと、Claude Codeが新しいコードを書くときに既存のアーキテクチャに自然と合わせてくれる。
もう一つ大きかったのは、不要な指示を削ったこと。200行あったCLAUDE.mdを80行まで削った。指示を減らしたら精度が上がるという体験は、正直最初は信じられなかった。でも実際そうだった。LLMの指示枠は有限で、本当に大事なことだけを伝えたほうが効く。試した。変わった。もう戻れない。
まとめ
- CLAUDE.mdはClaude Codeの精度を左右する最重要ファイル。「何を」「なぜ」「どうやって」の3つを軸に書く
- 指示は増やすほど精度が落ちる。リンターで済むことやタスク固有の指示は入れない
- 階層構造を活用して、グローバル・プロジェクト・ディレクトリで設定を分離する
1つのファイルでここまで変わるツールは、そうそうない。まだCLAUDE.mdを雑に書いている人は、今日30分だけ時間を取って見直してみてほしい。
【PR】フリーランスエンジニアにおすすめのツール
シンVPS — 高性能VPSが月額数百円から。AIツールの実行環境や開発サーバーに。
ムームードメイン — 独自ドメインの取得・管理がシンプル。ブログやポートフォリオに。
コメント