TL;DR
CLAUDE.mdのベストプラクティスを体現する自動生成スキル「claude-md-creator」を作りました。
- 60行以下のコンパクトなCLAUDE.mdを自動生成
-
- WHY/WHAT/HOW構成で本質のみを記載
-
- 詳細は
@path/to/file構文で外部インポート
- 詳細は
なぜ作ったのか
Claude Codeを使っている方なら、CLAUDE.mdの重要性はご存じだと思います。このファイル1つでClaude Codeの性能が大きく変わります。
しかし、良いCLAUDE.mdを書くのは意外と難しいんです。
よくある失敗パターン
-
情報を詰め込みすぎる
-
- エッジケースを全部書こうとする
-
- 結果的に関係の薄い内容が増え、重要な指示が埋もれる -
/initコマンドで自動生成に頼る -
- 汎用的すぎて、プロジェクト固有の情報が反映されない
-
- 本当に必要な情報が欠けている -
構造化されていない
-
- 何がどこに書いてあるかわからない
-
- Claude側も情報の優先度を判断しにくい
ベストプラクティスとは
CLAUDE.mdのベストプラクティスは以下の3点に集約されます。
1. 100行未満（できれば60行以下）
少ないほど効きます。普遍的に適用可能な内容だけを厳選します。
2. WHY/WHAT/HOWの3構成のみ
| セクション | 内容 | 例 |
|---|---|---|
| WHY | プロジェクトの存在意義、対象者、言語 | 1年後も変わらない本質 |
| WHAT | 技術スタック、スキル、ディレクトリ構造 | コンポーネントの一覧 |
| HOW | 開発コマンド、環境変数、変更ログ | 外部ファイルへの参照 |
3. 詳細は外部インポート
@path/to/file構文で詳細ドキュメントをインポートします。CLAUDE.mdには参照のみを記載し、本体は別ファイルに分割します。
詳細は @path/to/import構文で追加ファイルをインポート:
- ガイドライン @docs/GUIDELINES.md
- - リファレンス @docs/REFERENCE.md
- ```
## claude-md-creatorスキルの設計
このスキルは上記のベストプラクティスを**そのまま体現**しています。
### スキル構成
plugins/claude-md-creator/
├── .claude-plugin/ # プラグイン設定
├── skills/
│ └── claude-md-creator/
│ ├── SKILL.md # スキル定義（本体）
│ ├── PRINCIPLES.md # WHY/WHAT/HOW設計原則
│ ├── TEMPLATES.md # CLAUDE.mdテンプレート
│ └── WORKFLOW.md # 作成ワークフロー
└── README.md
スキル自体も「60行以下」「WHY/WHAT/HOW」「外部インポート」の原則に従っています。メタ的ですね。
### 作成フロー
スキルは以下の手順でCLAUDE.mdを生成します。
1. **プロジェクト理解**: WHY（存在理由）、対象者、言語を確認
1. 2. **構成要素の特定**: スキル一覧、共通リファレンス、詳細ドキュメントの場所
1. 3. **外部ドキュメント設計**: 詳細情報の配置先を決定
1. 4. **CLAUDE.md作成**: テンプレートに従い60行以下で生成
### 生成されるCLAUDE.mdの例
```markdown
# CLAUDE.md
## WHY: このプロジェクトについて
[1-2文でプロジェクトの存在意義を説明]
**対象者**: [誰のためか]
**言語**: [使用言語]
## WHAT: 含まれるもの
| スキル名 | 概要 |
|---------|------|
| skill-1 | 一行説明 |
| skill-2 | 一行説明 |
> 各スキルの詳細は `path/to/[skill-name]/SKILL.md` を参照
## HOW: 使い方
- 原則 @docs/PRINCIPLES.md
- - リファレンス @docs/REFERENCE.md
- ```
## 使い方
### インストール
```bash
/plugin marketplace add masayan/masayan-uni-code-plugins
/plugin install claude-md-creator@masayan-uni-code-plugins
実行
Claude Code内で以下を入力するだけです。
/claude-md-creator
スキルが対話的にプロジェクトの情報をヒアリングし、最適なCLAUDE.mdを生成します。
まとめ
「厳選した情報だけ」がClaude Codeの性能を最大化します。
- 60行以下に抑える
-
- WHY/WHAT/HOWの3構成のみ
-
- 詳細は外部インポート
このベストプラクティスを自動化したのがclaude-md-creatorです。ぜひ試してみてください。