0
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@locallab

Claude Code を 3 倍速にした 5 つの CLAUDE.md チューニング術

0
Posted at

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 チューニングの要点をまとめる。

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

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

参考リンク

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

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

興味を持っていただけたら、ぜひ各 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

0
2
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
2

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?