CLAUDE.mdを「とりあえず」で済ませてる人に知ってほしい、指示精度が上がる7つの書き方

Claude Codeを使い始めると、まずCLAUDE.mdを作りますよね。プロジェクトの説明やコーディング規約をざっと書いて、「よし、これでOK」と。

ただ、CLAUDE.mdは書き方ひとつで応答精度がかなり変わります。公式ドキュメントを読み込むと、使いこなせていない機能がいくつも見つかるので、すぐ実践できるものを7つに絞りました。

1. /init で叩き台を自動生成する

白紙から書き始める必要はありません。Claude Codeのセッション内で /init を実行すれば、リポジトリを解析してビルドコマンド・テスト手順・規約を自動で拾い上げてくれます。

# Claude Code セッション内で
/init

すでにCLAUDE.mdがある場合は上書きではなく改善提案になるので、既存プロジェクトでも安全です。

環境変数 CLAUDE_CODE_NEW_INIT=1 を設定すると、CLAUDE.md・Skills・Hooksのどれを作るか対話形式で選べるようになります。

ここで生成された内容をベースに、Claude Codeが自力では見つけられない暗黙のルールやチーム固有の規約を手で書き足していくのが効率的です。

2. 200行を超えたら分割する

CLAUDE.mdはセッション開始時にコンテキストウィンドウへ丸ごと読み込まれます。長くなるほどトークンを消費し、 指示の遵守率も下がる というのが公式見解です。

目安はこのあたりです。

行数	状態
~100行	指示がよく効く。理想的
100~200行	構造化されていれば問題なし
200行超	遵守率低下のリスクあり

超えそうになったら、後述の @import や .claude/rules/ で外に出してください。「1ファイルに全部書く」のが一番やりがちな失敗です。

3. 曖昧な指示を具体的に書き換える

Claude Codeは「検証可能なレベルで具体的な指示」に強く従います。逆に言えば、ふわっとした記述はほぼスルーされます。

NG	OK
コードをきれいに書く	2スペースインデントを使用する
テストしてからコミットする	コミット前に npm test を実行する
ファイルを整理する	APIハンドラは src/api/handlers/ に配置する

判断基準はシンプルで、 「別の人がこの指示を読んで同じ行動を取れるか」 です。

# コーディング規約
- インデントは2スペース
- 変数名はcamelCase、定数はUPPER_SNAKE_CASE
- import文はアルファベット順

# テスト
- コミット前に `pnpm test` を実行すること
- テストは tests/ にソースと同じ階層構造で配置

「適当に」「いい感じに」がCLAUDE.mdに入っていたら、指示として機能していない可能性が高いです。

4. @import で既存ドキュメントを再利用する

CLAUDE.mdの中で @パス と書くだけで、別ファイルの内容を丸ごと取り込めます。

# CLAUDE.md
プロジェクト概要は @README.md を参照。
利用可能なスクリプトは @package.json を確認。

## Git運用
@docs/git-workflow.md

READMEやpackage.jsonの内容をCLAUDE.mdに手でコピーしている方は、この方法に切り替えるだけで二重管理から解放されます。相対パスはCLAUDE.mdの配置場所が基準で、最大5階層までの再帰importにも対応しています。

プロジェクトで初めて外部importを使う場合、承認ダイアログが表示されます。一度許可すれば以降は自動です。

5. .claude/rules/ でパス別にルールを分ける

.claude/rules/ ディレクトリにMarkdownファイルを置くと、CLAUDE.mdと独立してルールを管理できます。しかもYAMLフロントマターを使えば、 特定のファイルパスにだけ適用されるルール が書けます。

ディレクトリ構成の例です。

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md      # 全体共通
│       ├── testing.md         # テスト規約
│       └── frontend/
│           └── react.md       # React固有

パス指定付きルールはこう書きます。

---
paths:
  - "src/api/**/*.ts"
---

# APIエンドポイントのルール

- 入力バリデーションを必ず含める
- エラーレスポンスは標準フォーマットを使用
- OpenAPIドキュメントコメントを付与する

このルールは src/api/ 配下のTypeScriptファイルを触ったときだけ読み込まれます。フロントエンドのコードを編集しているときにAPIの規約がコンテキストに入ってくる、というムダがなくなります。

paths フロントマターなしのルールファイルは毎セッション読み込まれます。パス指定付きはオンデマンドなので、コンテキストの節約にもなります。

よく使うglobパターンをまとめておきます。

パターン	マッチ対象
**/*.ts	全ディレクトリのTypeScriptファイル
src/components/*.tsx	特定ディレクトリのReactコンポーネント
**/*.{ts,tsx}	TypeScript + TSXを一括指定
tests/**/*.test.ts	テストファイルのみ

モノレポで各チームが独立したルールを持ちたい場合にも使えますし、シンボリックリンクで複数プロジェクト間のルール共有もできます。

# 共有ルールをリンク
ln -s ~/shared-claude-rules .claude/rules/shared

6. CLAUDE.local.md で個人設定をGitから外す

CLAUDE.mdはチーム共有。では個人のローカル環境に依存する設定はどこに書くか。

CLAUDE.local.md をプロジェクトルートに作り、.gitignore に追加するだけです。

# CLAUDE.local.md

- ローカルAPI: http://localhost:3000
- テストDB: postgresql://localhost:5432/myapp_dev
- デバッグ時は `DEBUG=true pnpm dev` を使う

Git worktreeを複数使う方は注意点があります。CLAUDE.local.mdは作成したworktreeにしか存在しません。worktree間で共有するには、ホームディレクトリに置いたファイルを @import してください。

# CLAUDE.local.md
@~/.claude/my-project-preferences.md

7. Auto Memoryを定期的に確認する

Claude Codeにはセッション中の学びを自動保存する「Auto Memory」があります。~/.claude/projects/<project>/memory/ にMarkdownファイルとして記録され、次回セッションから自動で参照されます。

便利ですが、放置すると古い情報が残ってノイズになることがあります。/memory コマンドで定期的に中身を見ておくのがおすすめです。

項目	内容
保存先	~/.claude/projects/<project>/memory/
起動時読み込み	MEMORY.md の先頭200行 or 25KB
トピックファイル	必要時にオンデマンド読み込み
共有範囲	マシンローカル（同一リポジトリのworktree間は共有）
無効化	autoMemoryEnabled: false or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

不要なメモはファイルを直接編集・削除して構いません。すべてプレーンなMarkdownです。

配置場所の早見表

最後に、CLAUDE.md関連ファイルの配置場所を一覧にしておきます。

スコープ	配置場所	共有範囲	主な用途
組織	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	全社	セキュリティポリシー
プロジェクト	./CLAUDE.md or ./.claude/CLAUDE.md	チーム (Git)	規約・ビルド手順
ユーザー	~/.claude/CLAUDE.md	自分のみ	全プロジェクト共通の好み
ローカル	./CLAUDE.local.md	自分のみ	個人のプロジェクト固有設定
ルール	.claude/rules/*.md	チーム (Git)	パス別の詳細ルール

まとめ

CLAUDE.mdは「とりあえず書いて放置」から一歩踏み出すだけで、Claude Codeの応答精度が目に見えて変わります。まずは /init で骨格を作り、膨らんできたら .claude/rules/ と @import で分割する。このサイクルだけ意識すれば十分です。