テックエイド
AI・開発生産性

Claude Codeに同じ前提を毎回書くのをやめる｜CLAUDE.mdで渡すプロジェクトメモリの設計

#CLAUDE.md #Claude Code #プロジェクトメモリ #AI文脈設計 #受託開発
Claude Codeに同じ前提を毎回書くのをやめる｜CLAUDE.mdで渡すプロジェクトメモリの設計

「このプロジェクトはモノレポで、Node 20、PNPM、テストは Vitest、CI は GitHub Actions、コミットメッセージは Conventional Commits……」。Claude Code に依頼するたびに、こうした前提を貼り直していませんか。
本人だけならまだいい。チームに展開した瞬間、メンバーごとに渡す前提がバラつき、出力品質が安定しなくなります。「同じことを聞いているのに、人によって全然違うコードが返ってくる」状態は、たいていプロンプトのうまさではなく、前提の固定化が設計されていないことが原因です。

この問題に Claude Code が用意している答えが CLAUDE.md です。リポジトリのルートに置くだけでセッション開始時に自動で読み込まれ、プロジェクト固有の文脈として常に効き続けます。ただし、ただ存在させるだけでは効果はほとんど出ません。「再利用可能な前提集」として設計することで初めて、毎回の貼り直しから解放されます。

本記事では、テックリードが受託開発の現場で CLAUDE.md を設計するときの構造ルールを、4つのブロックに分けて整理します。

なぜ「ファイル指定」より「前提の固定化」が成果差を生むのか

Claude Code の活用ノウハウは「どのファイルを読ませるか」「どんなプロンプトを書くか」に偏りがちです。しかしチームで使うと、本当に効くのは別のレイヤーにあります。

それがプロジェクト前提の固定化です。

たとえば「このリポジトリはバックエンドが NestJS で、認証は Auth0 で、DB は PostgreSQL、ORM は Prisma」という事実は、案件が続くかぎり何百回でも同じです。これを毎回プロンプトに書くのは、関数の引数に毎回マジックナンバーを直書きするのと同じ筋の悪さがあります。

CLAUDE.md はこの「定数」を切り出す場所です。1回書けば、Claude Code はそのリポジトリでの作業中ずっと同じ前提で動きます。つまり、プロンプト1発の書き方を磨く前に、前提集を整える方が投資効率が高いのです。

なお、Claude Code への個別の依頼そのものを再現性高く書く方法は別記事で扱っています。あわせて読むと、永続前提（CLAUDE.md）と単発依頼（プロンプト）の役割分担がはっきりします。

→ 関連記事：Claude Codeへの依頼を4要素で書く｜目的・制約・出力形式・反証条件で手戻りを止める

CLAUDE.md を構成する4ブロック

実運用で機能している CLAUDE.md は、おおむね次の4ブロックで構成されています。

  1. プロジェクト概要（What）
  2. 規約（How）
  3. 禁止事項（Don’t）
  4. 呼び出し方・参照ルール（When）

順番にも意味があります。AI に文脈を渡すときは、「全体像 → 標準 → 例外 → 起動条件」の順で並べた方が判断のブレが減ります。

ブロック1：プロジェクト概要（What）

最初の数十行で「このリポジトリは何で、誰が、何のために触っているのか」を固めます。書くべき要素は次の通りです。

  • プロジェクトの目的を1〜2文で（例：「toB SaaS の請求基盤」）
  • 関係者の前提（受託か自社か、開発フェーズ、リリース状況など）
  • 技術スタックの要点（言語、主要フレームワーク、DB、デプロイ先）
  • ディレクトリ構成の超ざっくり版（深掘りしない）

ここで重要なのは、詳細を書きすぎないことです。README.md をコピーしないでください。AI が判断するために必要な「定数」だけに絞ります。詳細仕様は別ファイルに置き、後述の「呼び出し方」ブロックで参照させます。

ブロック1の記述例です。

## プロジェクト概要

toB SaaS の請求基盤。受託開発フェーズ（2025年4月〜）、本番稼働中。

**関係者前提**
- 発注元: 株式会社〇〇 経理部（最終受益者）+ IT部門（窓口）
- 開発体制: 当社3名（PM・バックエンド・フロント）、本番リリース権限は PM が持つ

**技術スタック**
- バックエンド: Node 20 / NestJS / TypeScript strict
- DB: PostgreSQL 15（ORM: Prisma）
- フロント: Next.js 14 App Router
- CI/CD: GitHub Actions → Xserver（rsync）

**ディレクトリ構成（超概要）**
- `src/` — アプリ本体（`modules/` 配下がドメイン分割）
- `prisma/` — スキーマとマイグレーション
- `docs/` — 仕様書・ API ドキュメント（詳細はここを読む）

ブロック2：規約（How）

開発標準・コーディング規約・運用ルールを書きます。チームで合意済みのものだけを書くのがコツです。「個人の好み」を混ぜると、後でメンバー間で摩擦が起きます。

書くべき例

  • インデント、命名、ファイル分割の方針
  • コミットメッセージとブランチ戦略
  • テスト方針（必須カバレッジ、モックの扱い）
  • レビュー前のセルフチェック項目
## 規約

- TypeScript strict モードを前提とする
- import は絶対パス（`@/` プレフィクス）を優先する
- 1関数あたり40行以内を目安にし、超える場合は分割を検討する
- Conventional Commits を使う（feat、fix、chore、refactor、test、docs）
- PR には Issue 番号を `Closes #123` 形式で書く

このブロックがあるかないかで、Claude Code が出すコードの「書き味」が安定するかどうかが決まります。

ブロック3：禁止事項（Don’t）

ここが、多くのチームで抜けがちで、かつ最も効くブロックです。

AI は「やっていいこと」より「やってはいけないこと」を伝える方が制御しやすくなります。受託開発で実際に起きやすい事故を、禁止リストとして明文化してください。

書くべき例

  • 本番 DB を直接触るスクリプトを書かない
  • 環境変数を含むファイルを git に追加しない
  • 既存の API レスポンス形を勝手に変更しない（破壊的変更は別 Issue で議論）
  • ライブラリを勝手に追加しない（追加候補は提案だけして PM に確認）
## 禁止事項

- `package.json` への新規依存追加は提案にとどめ、勝手に `npm install` しない
- マイグレーションファイルを後から書き換えない（追加マイグレーションで修正する）
- `console.log` を本番コードに残さない（必要なら logger を使う）
- 既存のテストを「赤いから」という理由だけで削除しない

ここを書くだけで、レビューでの差し戻しが目に見えて減ります。逆に言えば、過去にレビューで差し戻したパターンこそが、このブロックに書くべきネタの宝庫です。

ブロック4：呼び出し方・参照ルール（When）

最後に、「どんな作業のときに、どのファイルを追加で読ませるか」を書きます。

CLAUDE.md 1枚にすべてを詰め込もうとすると、肥大化して逆に読まれなくなります。詳細仕様は別ファイルに切り出し、起動条件付きで参照させるのが現実的です。

## 参照ルール

- API 仕様の変更を伴う作業の前に `docs/api-spec.md` を読む
- DB スキーマに触る作業の前に `docs/schema.md` と `prisma/schema.prisma` を読む
- リリース作業の前に `docs/release-checklist.md` を読む
- レガシーモジュール（`legacy/` 配下）を触るときは `docs/legacy-context.md` を読む

これで CLAUDE.md はカタログの役割になり、本体の文脈は必要なときだけ展開されます。トークンも節約できます。

運用するための3つの実務ルール

構造を決めたら、次は運用です。CLAUDE.md を腐らせない最低限のルールを3つ挙げます。

1. 「変えたら CLAUDE.md も見る」をレビュー観点に入れる

技術スタックを変えたとき、規約を変えたとき、禁止事項に追加すべき事故が起きたときは、コードと一緒に CLAUDE.md も更新します。レビュー観点に「CLAUDE.md の更新有無」を入れておくと、忘れにくくなります。

2. PR テンプレートで「禁止事項に該当しないか」を自己申告する

禁止事項は、書いてあっても守られなければ意味がありません。PR テンプレートに「CLAUDE.md の禁止事項に抵触していないか確認した」のチェックを入れると、開発者本人もレビュアーも、確認しやすくなります。

3. 月1で「効いていない記述」を棚卸しする

書いたまま放置された記述は、ノイズとして AI の判断を鈍らせます。「このルールは過去3ヶ月で1度も指摘していない」「形骸化している」と感じたら、削るか、別ドキュメントに退避させてください。CLAUDE.md は積み上げではなく、現役の前提だけが残っている状態を保つほうが効きます。

チーム展開で詰まる前に：個人運用→チーム標準の橋渡し

ここまで「設計」と「運用」を書きましたが、実は最大の壁はチーム展開です。

「自分の CLAUDE.md はうまく動くが、チームに配ると形骸化する」というのは、Claude Code 導入で最もよくある失敗です。導入を3段階に分けて、無理なく定着させる考え方は別記事にまとめています。

→ 関連記事：Claude Code が社内で使われない3つの原因｜定着させる3段階フレーム

また、PM がチームの Claude Code 運用に関わるときは、エンジニアとの線引きも重要です。CLAUDE.md の設計責任を誰が持つか、最終判断はどう渡すかは、こちらを参照してください。

→ 関連記事：PMがClaude Codeを使うときの3ルール｜エンジニアと衝突しない線引きと最終判断の渡し方

まとめ

CLAUDE.md は、Claude Code を「個人技」から「チームの標準」に引き上げるための要（かなめ）です。

  • プロンプトを磨く前に、プロジェクト前提を固定化する方が投資効率は高い
  • 構造は「概要 → 規約 → 禁止事項 → 参照ルール」の4ブロックで整理する
  • 禁止事項とレビュー観点・PR テンプレートを連携させると、運用が形骸化しにくい
  • 詳細仕様は別ファイルに切り出し、CLAUDE.md はカタログとして軽く保つ

毎回同じ前提を貼り直す手戻りが消えると、Claude Code への依頼は本来やりたい「個別の意思決定」に集中できます。設計の初動として、まず4ブロックの空テンプレートを切り、過去のレビューコメントから禁止事項を埋めることから始めてみてください。

文脈設計と運用設計をもう一段引き上げたい方は、テックエイドのオンライン実践キャリア講座が体系的な学習導線になります。本記事の CLAUDE.md 設計は、講座 AIX-101とAIX-102で扱う「文脈設計」「チーム運用設計」の実装イメージそのものです。受託開発の現場で AI を使い倒すためのカリキュラムを、ぜひチェックしてみてください。

→ テックエイドの講座一覧を見る