CLAUDE.md ベストプラクティス完全ガイド｜60行以下で性能最大化

要約

CLAUDE.mdのベストプラクティスは以下の3点に集約される。

1. 100行未満（できれば60行以下）に抑える - 少ないほど効果が高い
2. WHY/WHAT/HOW構成のみで書く - プロジェクトの本質だけを記載
3. プログレッシブディスクロージャーで外部インポート - 詳細はagent_docsに分割し、必要なときだけ読み込む

これらを自動化する「claude-md-creator」スキルも公開している。

この記事を読むことで得られるメリット

• CLAUDE.mdの効果を最大化できる
• 失敗パターンを避けられる
• 構造化された書き方を習得できる
• 自動生成ツールで時間を短縮できる

この記事を読むのにかかる時間

約8分

環境

• Claude Code（バージョン問わず）
• claude-md-creatorスキル（オプション）

CLAUDE.mdとは何か

CLAUDE.mdは、Claude Codeに対してプロジェクト固有の指示を与えるための設定ファイルである。プロジェクトのルートディレクトリに配置することで、Claude Codeがコードを理解し、適切な提案を行うための文脈を提供する。

配置可能な場所は3つある。

CLAUDE.mdの内容は、Claude Codeのすべての応答に影響を与える。そのため、このファイルの品質がClaude Codeの性能を大きく左右する。

よくある失敗パターン

CLAUDE.mdを書く際によくある失敗パターンを3つ紹介する。

失敗パターン1: 情報を詰め込みすぎる

最も多い失敗は、あらゆる情報をCLAUDE.mdに詰め込もうとすることである。

copy# やってしまいがちな例
- このエッジケースではこうする
- あのエッジケースではああする
- この関数はこう呼び出す
- このライブラリの使い方は...
（200行以上続く）

問題点は以下の通りである。

• 関係の薄い内容が増え、重要な指示が埋もれる
• Claude Codeが情報の優先度を判断しにくくなる
• 書いてあっても無視されやすくなる

エッジケースを全て網羅しようとしないこと。関係の薄い内容が常に含まれると、不要な部分が無視されるだけでなく、性能が低下しやすい傾向にある。

失敗パターン2: /initコマンドに頼りすぎる

Claude Codeには/initコマンドでCLAUDE.mdを自動生成する機能がある。しかし、これに頼りすぎるのは問題である。

自動生成の問題点は以下の通りである。

• 汎用的すぎて、プロジェクト固有の情報が反映されない
• 本当に必要な情報が欠けている
• 不要な情報が含まれていることが多い

/initは出発点としては有用だが、必ず手動でカスタマイズする必要がある。

失敗パターン3: 構造化されていない

情報が羅列されているだけで、構造化されていないCLAUDE.mdも問題である。

copy# 構造化されていない例
プロジェクトはReactを使用。
npm run devで起動。
テストはJestを使う。
APIはaxiosで呼ぶ。
状態管理はRedux。
...

問題点は以下の通りである。

• 何がどこに書いてあるかわからない
• 必要な情報を探すのに時間がかかる
• Claude Code側も情報の優先度を判断しにくい

3つのベストプラクティス

上記の失敗パターンを避け、CLAUDE.mdの効果を最大化するためのベストプラクティスを紹介する。

原則1: 100行未満（できれば60行以下）

少なければ少ないほど効果が高い。これがCLAUDE.mdの最も重要な原則である。

目安として、100行未満を目指す。可能であれば60行以下に抑えることを推奨する。

理由は以下の通りである。

• 情報が少ないほど、各指示が確実に適用される
• 普遍的に適用可能な内容のみを厳選することで、品質が向上する
• Claude Codeの処理効率も向上する

行数を減らすためのテクニックとして、詳細は外部ファイルにインポートする方法がある（原則3で詳述）。

原則2: WHY/WHAT/HOW構成

CLAUDE.mdはWHY/WHAT/HOWの3セクションのみで構成する。

この構成の利点は以下の通りである。

• 1年後も変わらない本質的な情報のみを記載できる
• 構造が明確で、必要な情報を素早く見つけられる
• Claude Codeが情報の種類を判断しやすい

具体例を示す。

copy# CLAUDE.md

## WHY: このプロジェクトについて

AI・テクノロジー関連の技術ブログを管理するリポジトリである。
エンジニア向けに、最新技術の解説記事を日本語で提供する。

**対象者**: エンジニア
**言語**: 日本語

## WHAT: 含まれるもの

| ディレクトリ | 用途 |
|--------------|------|
| tech-blog-writing/ | テックブログ記事の作成 |
| note-writing/ | note記事の作成 |
| x-post-creation/ | X投稿の最適化 |

## HOW: 使い方

詳細は @path/to/import構文で追加ファイルをインポート:
- ガイドライン @agent_docs/GUIDELINES.md
- リファレンス @agent_docs/REFERENCE.md

原則3: プログレッシブディスクロージャーで外部インポート

CLAUDE.mdを短く保つために、詳細は外部ファイルに分割し、プログレッシブディスクロージャー（段階的開示）で必要なときだけ読み込む設計にする。

プログレッシブディスクロージャーとは

すべての情報を一度に提示するのではなく、必要なタイミングで必要な情報だけを開示する設計パターンである。CLAUDE.mdでは、@path/to/file構文を使用することで、追加のマークダウンファイルを必要なときにインポートできる。

Claude Codeは参照されたファイルを必要に応じて読み込む。常にすべてが読み込まれるわけではないため、処理効率が向上する。

ディレクトリ構成のベストプラクティス

分割したファイルは、**agent_docs**のような分かりやすいディレクトリに配置する。

copyproject/
├── CLAUDE.md              # 60行以下のエントリーポイント
├── agent_docs/            # Claude Code用ドキュメント
│   ├── GUIDELINES.md      # コーディングガイドライン
│   ├── ARCHITECTURE.md    # アーキテクチャ説明
│   ├── SECURITY.md        # セキュリティルール
│   └── REFERENCE.md       # API・ライブラリリファレンス
└── src/

ディレクトリ名のポイントは以下の通りである。

• agent_docs、claude_docsなど、用途が明確な名前を使う
• docsだと人間向けドキュメントと混同しやすいため避ける
• プロジェクトルート直下に配置し、見つけやすくする

CLAUDE.mdでの参照方法

copy## HOW: 使い方

詳細は @path/to/import構文で追加ファイルをインポート:
- ガイドライン @agent_docs/GUIDELINES.md
- アーキテクチャ @agent_docs/ARCHITECTURE.md
- セキュリティ @agent_docs/SECURITY.md

この方法の利点

• CLAUDE.mdを60行以下に抑えられる - 本質のみを記載
• 必要なときだけ読み込まれる - 処理効率が向上
• ドキュメントの保守性が向上 - 関心の分離ができる
• ファイル単位で更新できる - 変更の影響範囲が限定される

実践例: claude-md-creatorスキル

上記のベストプラクティスを自動化するスキル「claude-md-creator」を作成した。このスキルは、ベストプラクティスをそのまま体現している。

GitHub

GitHub - masayan1126/masayan-uni-code-plugins: Claude Code plugins for documentation and development workflows

スキルの設計思想

claude-md-creatorは、以下の原則に基づいて設計されている。

1. 60行以下のCLAUDE.mdを生成 - 厳選した情報のみを出力
2. WHY/WHAT/HOW構成を強制 - 本質的な情報のみを記載
3. 外部インポートを推奨 - 詳細は別ファイルへ

スキル自体も「60行以下」「WHY/WHAT/HOW」「外部インポート」の原則に従っている。メタ的な設計である。

スキル構成

copyplugins/claude-md-creator/
├── .claude-plugin/          # プラグイン設定
├── skills/
│   └── claude-md-creator/
│       ├── SKILL.md         # スキル定義（本体）
│       ├── PRINCIPLES.md    # WHY/WHAT/HOW設計原則
│       ├── TEMPLATES.md     # CLAUDE.mdテンプレート
│       └── WORKFLOW.md      # 作成ワークフロー
└── README.md

スキル定義（SKILL.md）も短く保ち、詳細はPRINCIPLES.md、TEMPLATES.md、WORKFLOW.mdに分割している。

作成フロー

スキルは以下の手順でCLAUDE.mdを生成する。

1. プロジェクト理解: WHY（存在理由）、対象者、言語を確認
2. 構成要素の特定: スキル一覧、共通リファレンス、詳細ドキュメントの場所
3. 外部ドキュメント設計: 詳細情報の配置先を決定
4. CLAUDE.md作成: テンプレートに従い60行以下で生成

対話的にプロジェクトの情報をヒアリングし、最適なCLAUDE.mdを生成する。

生成されるCLAUDE.mdの例

copy# CLAUDE.md

## WHY: このプロジェクトについて

[1-2文でプロジェクトの存在意義を説明]

**対象者**: [誰のためか]
**言語**: [使用言語]

## WHAT: 含まれるもの

| スキル名 | 概要 |
|---------|------|
| skill-1 | 一行説明 |
| skill-2 | 一行説明 |

> 各スキルの詳細は `path/to/[skill-name]/SKILL.md` を参照

## HOW: 使い方

詳細は @path/to/import構文で追加ファイルをインポート:
- 原則 @agent_docs/PRINCIPLES.md
- リファレンス @agent_docs/REFERENCE.md

生成されたCLAUDE.mdは必ず60行以下であり、WHY/WHAT/HOW構成に従っている。詳細ドキュメントはagent_docsディレクトリに配置され、プログレッシブディスクロージャーで必要なときだけ読み込まれる。

インストール方法

以下のコマンドでインストールできる。

copy/plugin marketplace add masayan/masayan-uni-code-plugins
/plugin install claude-md-creator@masayan-uni-code-plugins

使い方

Claude Code内で以下のコマンドを実行する。

copy/claude-md-creator

スキルが対話的にプロジェクトの情報をヒアリングし、最適なCLAUDE.mdを生成する。

まとめ

CLAUDE.mdのベストプラクティスは以下の3点に集約される。

1. 100行未満（できれば60行以下）に抑える
2. WHY/WHAT/HOW構成のみで書く
3. プログレッシブディスクロージャーで外部インポートする

詳細情報はagent_docsのような分かりやすいディレクトリに分割し、@path/to/file構文でCLAUDE.mdから参照する。Claude Codeは必要なときだけこれらのファイルを読み込むため、処理効率と情報の精度が両立できる。

特に「少なければ少ないほど効果が高い」という点は重要である。エッジケースを全て網羅しようとせず、普遍的に適用可能な内容のみを厳選しよう。

自動化したい場合は、「claude-md-creator」スキルを活用することで、ベストプラクティスに従ったCLAUDE.mdを簡単に生成できる。