CLAUDE.md は Claude Code がセッション開始時に自動で読み込むプロジェクトメタ情報です。空欄でも動きますが、書く内容次第で「再現性のある品質」が大きく変わります。この記事では、書くべき 8 項目、コピーして使えるテンプレート全文、行数の目安、そして書かないほうがよいことまでを整理します。
結論｜3 つだけ押さえる
長く書く前に、要点は 3 つです。
- コードを読んでも分からないことだけを書く。関数の中身やディレクトリ名は読めば分かるので不要です。書くのは、プロジェクト固有のコマンド、意識的に選んだ制約、過去に繰り返し間違えられた箇所です
- 200〜300 行に収める。長いほど個々の指示は薄まります。詳細は別ファイルへ切り出し、CLAUDE.md は索引として保ちます
- 最も効くのは落とし穴 (Gotchas) の項目。一般論より、そのプロジェクトでしか起きない罠のほうが価値があります
最初から完璧を目指す必要はありません。概要と絶対遵守ルールの 2 項目から始め、困った場面を見つけるたびに足していくのが続けやすい進め方です。
そのまま使えるテンプレート
まず全体像です。汎用的な Web アプリケーションを想定した雛形なので、プロジェクトに合わせて中身を差し替えてください。
# CLAUDE.md
このファイルは AI コーディングエージェントがこのリポジトリで作業する際の
ガイダンスです。
## プロジェクト概要
社内向けの在庫管理 Web アプリ。TypeScript + React + Node.js で構築し、
社内の Kubernetes クラスタで稼働している。利用者は倉庫スタッフ約 40 名。
## 絶対遵守ルール
- `any` 型を使わない。型が分からない場合は `unknown` で受けて絞り込む
- Lint の disable コメントで警告を消さない。原因を直す
- 破壊的なマイグレーションを書かない。カラム削除は 2 段階リリースで行う
- 認証まわりのコードは変更前に必ず確認を取る
## コマンド
| コマンド | 用途 |
| --------------- | ------------------------ |
| `pnpm dev` | 開発サーバー (port 3000) |
| `pnpm test` | ユニットテスト |
| `pnpm lint` | Lint と型チェック |
| `pnpm db:reset` | ローカル DB の初期化 |
変更後は `pnpm test` と `pnpm lint` を通してからコミットすること。
## アーキテクチャ
- フロントは React (Vite)、状態管理は TanStack Query のみ。Redux は使わない
- API は Node.js (Fastify)、DB は PostgreSQL、ORM は Prisma
- 認証は社内 SSO (OIDC)。独自のセッション管理は追加しない
## ディレクトリ構成
```
src/
api/ Fastify のルート定義。1 ファイル 1 リソース
domain/ ビジネスロジック。ここに DB や HTTP の知識を持ち込まない
infra/ Prisma クライアント、外部 API の呼び出し
ui/ React コンポーネント
prisma/ スキーマとマイグレーション
```
## 落とし穴 (Gotchas)
- 在庫数は `stock` テーブルではなく `stock_snapshot` の最新行を見る。
`stock` は履歴用で現在値ではない
- テストは `pnpm test` で通っても CI で落ちることがある。タイムゾーンが
原因なので、日時を扱うテストは必ず UTC で書く
- `pnpm db:reset` はシードデータも消える。復旧は `pnpm db:seed`
## コミット運用
- 1 コミット = 1 論理変更単位
- `main` への直接 push は禁止。ブランチを切って PR を出す
- コミットメッセージは `feat:` `fix:` などの prefix を付け、本文は日本語
## 現在の状況
2026 年 7 月時点。入出庫の機能は完成済み、棚卸し機能を実装中。
レポート機能は未着手。このまま貼って動きます。以下で各項目の狙いと、書くときのコツを補足します。
1. プロジェクト概要 (5〜10 行)
何のプロジェクトか、誰が使うか、どんな技術で動いているかを最初に書きます。AI に「あなたはいま何を触っているのか」を最短で把握させるための土台です。
長く書く必要はありません。5 行から 10 行で十分です。ここが長いと、後続の重要な指示が相対的に薄まります。
## プロジェクト概要
社内向けの在庫管理 Web アプリ。TypeScript + React + Node.js で構築し、
社内の Kubernetes クラスタで稼働している。利用者は倉庫スタッフ約 40 名。利用者の人数や規模感を書いておくと、「この規模なら過剰な最適化は不要」といった判断の材料になります。
FIXIT
Hayate前提やルールを書いておくと、AI が同じ土台で判断できるんです。
FIXITHayate最初は概要と NG ルールの 2 つで十分です。運用しながら足していきましょう。
2. 絶対遵守ルール (NG リスト)
守ってほしい制約を箇条書きにします。ここでのコツは、推奨ではなく禁止の形で書くことです。曖昧な推奨より、明示的な禁止のほうが従われやすい傾向があります。
## 絶対遵守ルール
- `any` 型を使わない。型が分からない場合は `unknown` で受けて絞り込む
- Lint の disable コメントで警告を消さない。原因を直す
- 破壊的なマイグレーションを書かない。カラム削除は 2 段階リリースで行う書き方のポイントが 2 つあります。
代替を添える。 「any を使わない」だけだと手が止まります。「unknown で受けて絞り込む」まで書くと、迷わず次へ進めます。
検証できる形にする。 「読みやすいコードを書く」は判定できません。「1 行 120 文字を超えない」なら判定できます。判定できない指示は守られたかどうかも分からないため、そもそも書く価値が薄くなります。
3. コマンド一覧 (主要 5〜7 個)
AI が自分で確認するために使うコマンドを表にします。これが無いと、毎回「どうやってテストを実行しますか」と聞かれます。
| コマンド | 用途 |
| --------------- | ------------------------ |
| `pnpm dev` | 開発サーバー (port 3000) |
| `pnpm test` | ユニットテスト |
| `pnpm lint` | Lint と型チェック |
| `pnpm db:reset` | ローカル DB の初期化 |すべてのスクリプトを書き写す必要はありません。AI が実際に打つものに絞ります。目安は 5 個から 7 個です。
あわせて「変更後は何を通すか」を 1 行添えると効きます。「変更後は pnpm test と pnpm lint を通してからコミットすること」と書いておくだけで、確認を省略されにくくなります。
4. アーキテクチャの主要技術と方針
技術選定の前提を書きます。ここで効くのは、採用しているものより採用していないものの明示です。
- フロントは React (Vite)、状態管理は TanStack Query のみ。Redux は使わない
- API は Node.js (Fastify)、DB は PostgreSQL、ORM は Prisma
- 認証は社内 SSO (OIDC)。独自のセッション管理は追加しない「Redux は使わない」「独自のセッション管理は追加しない」のような否定形があると、一般的には妥当でもこのプロジェクトでは困る提案を避けられます。世の中の標準的な解と自社の方針がずれている箇所ほど、書く価値があります。
5. ディレクトリ構成 (ツリー図)
どこに何を置くかを示します。ファイル名の羅列ではなく、各ディレクトリの責務を 1 行ずつ添えるのがコツです。
src/
api/ Fastify のルート定義。1 ファイル 1 リソース
domain/ ビジネスロジック。ここに DB や HTTP の知識を持ち込まない
infra/ Prisma クライアント、外部 API の呼び出し
ui/ React コンポーネントdomain/ の行にある「ここに DB や HTTP の知識を持ち込まない」が、この項目でいちばん働く部分です。ディレクトリ名だけならコードを見れば分かりますが、レイヤーの境界に関する意図はコードからは読み取れません。
6. 落とし穴 (Gotchas)
この項目が最も効きます。 そのプロジェクトでしか起きない罠を、具体的に書きます。
## 落とし穴 (Gotchas)
- 在庫数は `stock` テーブルではなく `stock_snapshot` の最新行を見る。
`stock` は履歴用で現在値ではない
- テストは `pnpm test` で通っても CI で落ちることがある。タイムゾーンが
原因なので、日時を扱うテストは必ず UTC で書く
- `pnpm db:reset` はシードデータも消える。復旧は `pnpm db:seed`書くきっかけは簡単です。同じ指摘を 2 回したら、ここに足します。 レビューで「またこれか」と思った瞬間が追記のタイミングです。
一般的なベストプラクティスは、AI が既に知っています。価値があるのは、このプロジェクトを触った人しか知らない事情のほうです。
7. コミット運用ルール
リポジトリ固有の運用を明文化します。AI が PR の作成まで自走する場合、ここが無いと毎回ずれます。
- 1 コミット = 1 論理変更単位
- `main` への直接 push は禁止。ブランチを切って PR を出す
- コミットメッセージは `feat:` `fix:` などの prefix を付け、本文は日本語コミットメッセージの言語や形式は、チームによって割れる部分です。書いておかないと英語で生成されたり、形式が揺れたりします。
8. 現在の状況
いま何にフォーカスしているかを書きます。実装済み・実装中・未着手が分かると、的外れな提案が減ります。
## 現在の状況
2026 年 7 月時点。入出庫の機能は完成済み、棚卸し機能を実装中。
レポート機能は未着手。ただしこの項目は最も腐りやすい部分です。日付を添えておき、フェーズが変わったら必ず更新してください。更新しないくらいなら、書かないほうが害がありません。
行数の目安｜短いほど守られる
分量の目安には複数の流儀があります。
| 目安 | 出どころ | 考え方 |
|---|---|---|
| 60 行前後 | 一部の開発チーム | 本当に効く指示だけに絞り込む |
| 200 行程度 | Anthropic の推奨 | 標準的な目安 |
| 300 行以内 | コミュニティの運用 | 実務で扱いやすい上限 |
共通しているのは「短いほど守られる」という経験則です。長くなるほど読み込むトークンが増えて応答が遅くなり、指示同士が競合して判断がぶれます。
300 行を超えたら、詳細を別ファイルへ切り出します。
表記ルールの詳細は docs/style-guide.md を参照。
デプロイ手順は docs/deploy.md を参照。こうして CLAUDE.md 側を索引に寄せると、本体を短く保ったまま情報量を確保できます。必要になった時点で AI が参照先を読みに行くため、常時読み込むトークンも抑えられます。
書かないほうがよいこと
足すことより、書かない判断のほうが難しい部分です。
| 書かない | 理由 |
|---|---|
| 一般的なコーディング作法 | すでに知っている。ノイズになる |
| 言語やフレームワークの基本 | 同上 |
| コードを読めば分かること | ディレクトリ名、関数の実装など |
| 抽象的な心構え | 「品質を意識する」などは判定できない |
| 個人の好み | チームの合意事項を書く場所 |
| 認証情報や秘密の値 | リポジトリにコミットされるため危険 |
判断に迷ったら、**「コードを読んでも分からないか」**を基準にしてください。読めば分かることを書いてもトークンを消費するだけです。
失敗例と対処
書きすぎて守られなくなる
500 行を超えたあたりから、指示が守られにくくなります。応答も遅くなります。
対処は切り出しです。詳細を docs/ へ移し、CLAUDE.md には参照だけを残します。切り出す優先順位は、参照頻度の低いものからです。デプロイ手順や表記ルールは、必要なときだけ読めば足ります。
古い情報が残って判断を誤らせる
「Phase 1 完了」のような状態は、書いた瞬間から古くなり始めます。放置すると、AI が古い前提で提案してくる原因になります。
対処は 2 つです。1 つは日付を添えること。もう 1 つは、フェーズ移行や仕様変更のタイミングで必ず見直すルールにしておくことです。CLAUDE.md をコードと同じ頻度で更新するドキュメントとして扱うと、この事故は起きにくくなります。
書いたのに守られない
まず量を疑ってください。長ければ切り出します。次に書き方です。曖昧な表現は検証できる形に直します。
それでも守られない項目は、CLAUDE.md ではなく Lint やテストで機械的に止めるほうが確実です。「any を使わない」は Lint ルールで止められます。人にも AI にも同じ基準で効くので、ルール化できるものはそちらへ寄せるのが本筋です。
コツ
最初から 8 項目を完璧に揃える必要はありません。概要と絶対遵守ルールの 2〜3 項目から書き始め、運用で困った場面を見つけるたびに追記していくのが続けやすいやり方です。
運用のコツ｜レビューの指摘を移していく
CLAUDE.md を育てる最も簡単な方法は、レビューで 2 回同じ指摘をしたら書き足すというルールです。
同じ指摘が繰り返されるということは、その情報がコードからは読み取れないということです。まさに CLAUDE.md に書くべき内容です。逆に、1 回で済んだ指摘は書く必要がありません。
効果の測り方も同じ軸で見ます。厳密な数値は不要で、「以前は毎回言っていたことを言わなくなった」という体感で十分に判断できます。減らない項目があれば、書き方が曖昧か、Lint で止めるべき性質かのどちらかです。
CLAUDE.md は「AI 駆動開発のリポジトリにおける最も投資対効果の高いドキュメント」だと考えています。テンプレート通りに完璧を目指すより、まず 2〜3 項目から書き始めて、運用しながら追記していくほうが結果的に早く効きます。
関連
- 組織導入: Claude Code を実務に導入する完全ガイド
- AI 駆動開発の TDD: AI 駆動 TDD で品質を担保する
- 初期設定: Claude Code セットアップガイド