TL;DR

CLAUDE.md の書き方次第で Claude Code の応答精度・速度・トークン消費量が大きく変わる
「禁止事項の明示」「コンテキスト圧縮」「ツール使用制約」の 3 軸が特に効く
本記事では実際に試した 5 つのチューニングパターンをコード例付きで紹介する

はじめに

Anthropic が提供する Claude Code は、プロジェクトルートに CLAUDE.md を置くことでエージェントの動作をコントロールできる。しかし「とりあえず書いておけばいい」という認識のままでは、トークンを食い潰すだけの冗長な指示になりがちだ。

本記事では、Claude Code の公式ドキュメントと実際の試行錯誤を通じて見えてきた 「ちゃんと効く」5 つのチューニングパターン を紹介する。

前提: CLAUDE.md が読まれるタイミング

Claude Code は以下のタイミングで CLAUDE.md を読み込む。

タイミング	対象
セッション開始時	プロジェクトルートの `CLAUDE.md`
ディレクトリ移動時	各サブディレクトリの `CLAUDE.md`
`/import` コマンド実行時	任意パスの md ファイル

つまり、ファイルが長くなるほどコンテキストウィンドウを占有し、実作業に使えるトークンが減る。「できるだけ詳しく書く」は逆効果になりうる。

チューニング 1: 禁止事項をトップに固める

Claude Code は「何をすべきか」より「何をしてはいけないか」の指示に対して特に忠実に動く。
やってほしくない操作を冒頭に ## 禁止事項 セクションとして固めると、誤操作率が下がる。

## 禁止事項 (絶対に守ること)

- `git push --force` は実行しない
- `DROP TABLE` / `DELETE FROM` を無確認で実行しない
- `.env` / `.env.local` の内容をコンソールに出力しない
- 本番ブランチ (`main` / `production`) への直 commit は行わない

ポイント: 箇条書きの動詞を「〜しない」に統一すること。「〜してください」系の肯定形と混在させると優先度が曖昧になる。

チューニング 2: ツール使用のスコープを絞る

デフォルト状態の Claude Code は必要以上に多くのファイルを Read しようとする。
CLAUDE.md で「参照してよいパス」を明示すると探索コストが減り、応答が速くなる。

## ファイル参照ルール

- 参照 OK: `src/`, `tests/`, `docs/`
- 参照 OK (読み取り専用): `package.json`, `Cargo.toml`, `pyproject.toml`
- 参照禁止: `infra/`, `secrets/`, `.github/workflows/`
- 不明な場合は作業前にユーザーに確認する

あわせて、特定の Bash コマンドを許可リスト化しておくとさらに効果的だ。

## 実行可能コマンド (許可リスト)

- `cargo test` / `cargo clippy` / `cargo fmt`
- `npm run test` / `npm run lint` / `npm run build`
- `git status` / `git diff` / `git log --oneline -20`

上記以外のコマンドは実行前にユーザーの承認を得ること。

チューニング 3: コンテキスト圧縮のための「用語辞書」

プロジェクト固有の略語・レイヤー名・命名規則を辞書として先出しすると、Claude Code が「この変数は何か」を都度推論しなくて済む。

## プロジェクト用語定義

| 用語 | 意味 |
|---|---|
| `UC` | ユースケース層 (`src/usecase/`) |
| `AR` | 集約ルート (DDD 用語・`src/domain/`) |
| `DTO` | リクエスト/レスポンス型 (`src/dto/`) |
| `Repo` | リポジトリインターフェース (`src/repository/`) |

命名規則:
- ファイル名: `snake_case.rs`
- 型名: `PascalCase`
- 定数: `SCREAMING_SNAKE_CASE`

これにより、「UC に新しいメソッドを追加して」という短い指示でも正しいパスに手が届くようになる。

チューニング 4: 「Think Before Act」プロンプトでハルシネーションを減らす

コード生成前に設計ステップを踏ませることで、一発目のコード品質が上がりリトライ回数が減る。

## 作業フロー (実装系タスク)

1. **影響範囲の確認**: 変更対象ファイルとその依存先を列挙する
2. **設計メモ**: 変更方針を 3 行以内で述べる
3. **実装**: コードを書く
4. **セルフレビュー**: 型エラー・命名規則・禁止事項に違反がないか確認する
5. **報告**: 変更したファイルと変更理由を一覧で示す

ステップ 2 を省略して直接コードを書き始めることを禁止する。

「ステップ 2 を省略するな」という 禁止形 を入れているのが肝。肯定形の「〜してから実装する」だけでは飛ばされることがある。

チューニング 5: サブディレクトリ CLAUDE.md で役割分離する

モノレポや大型プロジェクトでは、ルートの CLAUDE.md をすべての役割で肥大化させるより、サブディレクトリに責務別 CLAUDE.md を置く方が管理しやすい。

project-root/
├── CLAUDE.md          # 全体共通ルール (禁止事項・用語辞書)
├── frontend/
│   └── CLAUDE.md      # Next.js / TailwindCSS 固有ルール
├── backend/
│   └── CLAUDE.md      # Rust / axum 固有ルール
└── infra/
    └── CLAUDE.md      # 参照禁止を明示 (Claude Code は入らない)

infra/CLAUDE.md の中身はこれだけでよい。

## このディレクトリについて

このディレクトリは Claude Code の作業対象外です。
ファイルの読み取り・変更・コマンド実行は一切行わないでください。
作業が必要な場合はユーザーに確認を取ること。

Claude Code はディレクトリに入った際にこの指示を読み、自動で手を止める。

効果の比較 (定性)

観点	チューニング前	チューニング後
誤操作 (強制プッシュ等)	週 1〜2 件発生	ほぼゼロ
不要ファイルの探索	50〜100 ファイル read	20〜30 ファイルに絞られる
1 タスクあたりのターン数	平均 4〜6 ターン	平均 2〜3 ターン
ハルシネーション率 (体感)	高め・型エラー多発	設計メモ後は大幅改善

数値はあくまで筆者の環境での体感値であり、プロジェクト規模・複雑さによって変わる。

まとめ

CLAUDE.md チューニングの要点をまとめる。

禁止事項をトップに固める — 肯定形と混在させず「〜しない」で統一
ツールスコープを絞る — 参照 OK / 禁止パスを明示してコスト削減
用語辞書を先出しする — プロジェクト固有語を定義してコンテキスト節約
Think Before Act を強制する — 設計メモを禁止形で義務化
サブディレクトリで役割分離する — モノレポは責務ごとに CLAUDE.md を分割

ファイルサイズの目安として、ルートの CLAUDE.md は 80 行以内に収めることを意識すると、肥大化を防ぎやすい。

参考リンク

✍️ 本記事の著者: 合同会社ジモラボ

ジモラボは、八王子を拠点に AI を活用した SaaS を多数開発しています。本記事の技術検証もそうした開発過程の副産物です。

🌐 公式サイト: https://locallab.jp
🔍 AI SEO 最適化 SaaS: lookupai.jp
📺 YouTube: @locallab_llc
✉️ お問い合わせ: info@locallab.jp

興味を持っていただけたら、ぜひ各 SNS のフォローもお願いします！

投稿前セルフレビュー

チェック項目	結果
§4-A〜4-D 競合再現・個人情報・環境変数・社内コードの記述なし	✅ YES
コード断片は公式仕様準拠の学習用最小例のみ	✅ YES
OSS ライセンス明記 (今回はコード例のみ・OSS 引用なし)	✅ YES (該当なし)
数値・ベンチマークの出典 URL 記載 (定性比較のみ・出典は筆者体感と明記)	✅ YES
タイトルに数字入り (「3 倍速」「5 つ」)	✅ YES
タグは Qiita 慣習に合致 (kebab-case 推奨)	✅ YES (下記タグ案参照)
末尾プロフィール + lookupai リンクあり	✅ YES
lookupai への自然な誘導 1〜2 箇所 (過剰宣伝なし)	✅ YES
誤字脱字・コードブロック言語指定 OK	✅ YES

推奨タグ (Qiita):
claude-code / AI / 開発効率化 / プロンプトエンジニアリング / markdown