Claude Code の /init が生成する CLAUDE.md の中身と、直すべき箇所

Claude Code を新しいリポジトリで使い始めるとき、最初に打つコマンドが /init です。実行すると Claude がコードベースを調べて CLAUDE.md を書いてくれますが、生成された内容をそのまま放置すると、長すぎて指示が効かなくなることがあります。

結論として、/init の出力は「たたき台」です。コードを読めば分かる内容は削り、Claude が推測できないコマンドや規約を書き足してから、/context で読み込みを確認します。

/init が何をするか

公式ドキュメントでは、/init は「プロジェクトを CLAUDE.md ガイドで初期化する」コマンドと説明されています。Claude がコードベースを分析し、見つけたビルドコマンド、テストの実行方法、プロジェクトの規約を CLAUDE.md に書き出します。

項目	挙動
生成先	プロジェクトルートの CLAUDE.md
書かれる内容	ビルドコマンド、テスト手順、コードベースから分かった規約
既存の CLAUDE.md がある場合	上書きせず、改善案を提示する
他ツールの設定	.cursor/rules/・.cursorrules・.github/copilot-instructions.md を読み、関連部分を取り込む
Codex / Gemini CLI の設定	見つかると /import での引き継ぎを提案する

対話型の /init

環境変数 CLAUDE_CODE_NEW_INIT=1 を設定すると、/init が複数段階の対話型になります。CLAUDE.md、スキル、フックのどれを用意するかを尋ね、サブエージェントでコードベースを調べ、不足を質問で補ってから、書き込み前に提案内容を確認できます。このモードでは AGENTS.md、.devin/rules/、.windsurf/rules/、.clinerules も読み込み対象になります。

CLAUDE_CODE_NEW_INIT=1 claude

起動後に /init を実行します。個人用の設定を選ぶと、CLAUDE.local.md の作成と .gitignore への追加も行われます。

生成された CLAUDE.md で削るべき内容

公式のベストプラクティスは「各行について、これを消すと Claude が間違えるか、と自問し、そうでなければ削る」ことを勧めています。目安は 1 ファイル 200 行未満です。/init はコードベースを読んで書くため、次のような「コードから分かる内容」が入りがちです。

• ディレクトリ構成の一覧、ファイルごとの説明
• 依存パッケージの一覧
• 言語の標準的な慣習(「クリーンなコードを書く」のような自明な項目)
• 長いアーキテクチャ解説やチュートリアル

これらは Claude が必要なときにコードを読めば分かるので、毎セッションのコンテキストを消費するだけになります。

書き足すべき内容

逆に、/init では拾えない「Claude が推測できないこと」を足します。公式の「含めるもの」の表を要約すると次のとおりです。

含める	例
推測できないコマンド	pnpm --filter api test のような特殊なテストコマンド
既定と異なるスタイル規約	「CommonJS ではなく ES モジュールを使う」
リポジトリの作法	ブランチ命名、PR の書き方
プロジェクト固有の設計判断	「API ハンドラは src/api/handlers/ に置く」
環境の癖	必須の環境変数、ローカル DB の起動が必要なこと
よくある落とし穴	「既存のマイグレーションは編集しない」

書き方は「検証できるくらい具体的」にします。「きれいに整形する」ではなく「インデントは 2 スペース」、「テストする」ではなく「コミット前に npm test を実行する」と書きます。

# コマンド
- テスト: `pnpm -r test`(単体は `pnpm --filter <pkg> test`)
- 型チェック: `pnpm typecheck`。一連の変更が終わったら必ず実行する

# 規約
- ES モジュール(import/export)を使う。require は使わない
- API ハンドラは `src/api/handlers/` に置く

# 作法
- ブランチ名は `feat/`, `fix/` で始める
- `prisma/migrations/` の既存ファイルは編集しない

毎回は使わない手順(リリース手順など)は CLAUDE.md ではなくスキルに切り出すと、必要なときだけ読み込まれます。特定のディレクトリにしか関係しない規約は、サブディレクトリの CLAUDE.md か .claude/rules/ のパス指定ルールに移します。

読み込みを確認する

編集後は、セッション内で /context を実行し、Memory files の一覧に CLAUDE.md があることを確認します。/memory は CLAUDE.md の一覧表示と編集、自動メモリの切り替えに使うコマンドで、実際に読み込まれたファイルの確認は /context が公式の案内です。

@path 記法で別ファイルを取り込むこともできますが、取り込んだファイルも起動時に読み込まれるため、コンテキストの節約にはなりません。記法の詳細は CLAUDE.md の @ インポート記法 を参照してください。

まとめ

• /init はコードベースを分析して、ビルドコマンド・テスト手順・規約を書いた CLAUDE.md を生成する。既存ファイルは上書きせず改善案を出す
• CLAUDE_CODE_NEW_INIT=1 で、スキルやフックも含めた対話型の初期化になる
• 生成後は、ディレクトリ構成や依存一覧などコードから分かる内容を削る。目安は 200 行未満
• 推測できないコマンド、既定と異なる規約、環境の癖、落とし穴を具体的に書き足す
• /context の Memory files で読み込みを確認し、長くなったら /doctor の削減案を使う