Claude Codeを使っていて「なぜかAIが余計なことをする」「毎回同じ注意をしなければいけない」と感じるなら、CLAUDE.mdを正しく設定できていない可能性が高い。Anthropic公式ドキュメントとコミュニティのベストプラクティスから、本当に効くCLAUDE.md設計術を解説する。
CLAUDE.mdとは何か
CLAUDE.mdは、プロジェクトルートに置くマークダウンファイル。Claude Codeが起動するたびに自動的に読み込み、セッション全体の「ルール」として機能する。チームリポジトリにコミットすれば、全員が同じAI挙動を共有できる。
書くべきこと vs 書かなくていいこと
| 書くべき | 書かなくていい |
|---|---|
| AIが推測できないBashコマンド | コードから推測できること |
| 既存の慣習と異なるコードスタイル | AIが既に知っている標準規約 |
| テストコマンドと実行方法 | 変更頻度の高い詳細情報 |
| プロジェクト固有のアーキテクチャ | 長い解説・チュートリアル |
| 開発環境の特殊設定 | 「きれいなコードを書け」的な自明なこと |
実際に効くミニマルCLAUDE.mdテンプレート
# Project: [プロジェクト名]
Stack
– Framework: Next.js 15 (App Router)
– Styling: Tailwind CSS v4
– Language: TypeScript strict mode
– Database: Supabase (PostgreSQL)
– Deploy: VercelRules (ALWAYS follow these)
– Never modify files outside the scope I specify.
– Prefer editing existing files over creating new ones.
– Never create README or documentation files unless asked.
– Run after every code change.
– Ask before installing any new package.Avoid
– Default exports
– type in TypeScript
– Inline styles
– Class components in React
コミュニティが発見した「CLAUDE.mdの法則」
Product HuntとMediumで広く共有されているベストプラクティス：
- 300行以内に収める。超えるとAIが無視し始める
- コマンドは早めに書く。 のようにフラグ付きで
- 例外なき制約は「ALWAYS」「NEVER」で書く
- 「Ask before」パターンを使う（何かをする前に確認させる）
- バージョンを明記する（「React project」ではなく「React 19, Next.js 15.2」）
AIをインタビュアーにして仕様書を作るプロンプト
大きな機能を作る前に、これをCLAUDE.mdに追加するか、最初の指示として使う：
I want to build [brief description]. Interview me in detail using questions. Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don’t ask obvious questions, dig into the hard parts I might not have considered. Keep interviewing until we’ve covered everything, then write a complete spec.
AIが質問してくれることで、自分が考えていなかった問題点が浮き上がる。
AGENTS.mdとの違い
AGENTS.mdはGitHub Copilotなど他のAIツールも参照する汎用フォーマット。60,000以上のオープンソースプロジェクトで採用されている。Claude Code専用ならCLAUDE.md、複数のAIツールを使うチームならAGENTS.mdを採用するのが現在の主流。
まとめ
CLAUDE.mdは「AIへの永続的な指示書」。一度正しく設定すれば、毎回同じことを説明する必要がなくなる。特に効果的なのは「やってはいけないこと」の明示。AIは制約がないと良かれと思って余計なことをする——CLAUDE.mdはその暴走を防ぐ最初の防壁だ。
