CLAUDE.md にこれを書くと AI 駆動開発の品質が上がる 8 つの項目

CLAUDE.md は Claude Code がセッション開始時に自動で読み込むプロジェクトメタ情報です。空欄でも動きますが、書く内容次第で「再現性のある品質」が大きく変わります。FIXIT の本リポジトリ (fixit-web) でも実運用している 8 項目のテンプレートを紹介します。

1. プロジェクト概要 (5〜10 行)

会社名・サイト URL・主要技術スタック・サービス概要を最初に書く。AI に「あなたは何のプロジェクトを触っているか」を 30 秒で把握させるための土台です。

「ESLint disable コメントは禁止」「as any は避ける」「// TODO を残さない」など、絶対に守ってほしい NG ルールを箇条書きで。AI は曖昧なベストプラクティスより、明示的な禁止条項に従いやすい性質があります。

npm run dev npm run build npm run lint npm run lint:text など、AI が自分でテスト・確認するときに使うコマンドを表で記載。これがないと毎回「何を実行すればいいですか?」と聞かれます。

「Next.js App Router、static export、Cloudflare Pages デプロイ」のような前提を 1 段落で。これに沿わない提案 (例: API Routes を使う) を AI 側で自動的に避けてくれます。

app/ src/ content/ public/ の役割を 1〜2 行ずつ添えたツリーを貼る。AI が「どこに何を書くべきか」を瞬時に判断できるようになります。

ライティング系プロジェクトでは「『AI 駆動開発』のスペース有無」「『リプレイス』固定」など、表記スタイルガイドへの参照を CLAUDE.md に書く。AI が記事を書くときの一貫性が圧倒的に上がります。

「1 コミット = 1 論理変更単位」「main 直 push 禁止、PR 必須」「conventional commits 形式」など、リポジトリ固有の運用を明文化。AI が PR 作成まで自走するときの暗黙の前提を共有できます。

SEO 戦略・採用計画・プロダクトロードマップなど、AI に「今フォーカスしているのはこれ」を伝えるための位置情報。Phase 1 完了、Phase 2 進行中、のような状態を更新し続けると、AI が古い文脈で提案する事故が減ります。

CLAUDE.md が 500 行を超えてくると、AI が読み込むトークンが増えてレスポンスが遅くなり、また「ノイズが多くて判断がブレる」傾向が出ます。

目安として 300 行以内 に収め、詳細は別 docs に切り出すのが運用しやすい。「docs/style-guide.md を参照」のようなポインタを置く形で、CLAUDE.md は索引として保つのがおすすめです。

「Phase 1 完了 (2025-04)」のような状態情報は時間とともに stale 化します。CLAUDE.md は コードと同じ頻度で更新する ドキュメントとして扱い、Phase 移行や仕様変更のタイミングで必ず見直すルールにしておくと、AI の判断が常に最新の文脈で行えます。

本リポジトリ (fixit-web) の CLAUDE.md は GitHub で公開しています。Next.js + Velite + textlint + 静的エクスポートという技術スタックでどう書いているか、参考になれば。

CLAUDE.md は「AI 駆動開発のリポジトリにおける最も投資対効果の高いドキュメント」と FIXIT では位置付けています。テンプレ通りに完璧を目指すより、まず 2〜3 項目から書き始めて、運用しながら追記するのがおすすめです。