Claude.mdのコピペをやめよう：CLAUDE.md進化の4つの段階

先週の火曜日、私は同じ15行のプロジェクト背景情報をClaudeに貼り付けました――これで47回目です。スタック、慣習、データベースのスキーマ、「JWTのためにlocalStorageを使わない」というルール。毎回毎回。

そこで気づいたんです。私のCLAUDE.mdは時間が止まったままで、6か月前にプロトタイプから本番アプリになったのに、そのまま書かれていたのです。

心当たりありませんか？

たいていのCLAUDE.mdガイドはファイルに何を入れるかを教えてくれます。この記事はそれとは違って、それを「いつ」そこに入れるべきかを扱います。あなたのCLAUDE.mdはプロジェクトと一緒に育つべきです。空のファイルからエンタープライズ級の仕組みまで、4つの段階を紹介します。

Stage 1: The blank canvas (prototype)

mkdirで新しいプロジェクトを作るとき、200行のCLAUDE.mdは不要です。必要なのは10行です。

# CLAUDE.md

## Project
Name: TaskFlow (working title)
Purpose: Team task management system

## Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL

## Rules
- TypeScript strict mode
- Conventional Commits

以上です。この段階では「なぜ」ではなく「何が」あるかを記録すること。まだ、推論を文書化するほどの意思決定が十分にできていないからです。プロトタイプは昼食前に3回も方向転換します。

私が最もよく見かけるミスは、初日から他人の150行ぶんのCLAUDE.mdテンプレートを丸ごとコピペしてしまうことです。Claudeは、別のプロジェクト、別のチーム、別のアーキテクチャ向けに書かれたルールに、きちんと従ってしまいます。小さく始めて、意図的に育てていきましょう。

Stage 2: The MVP harness

あなたのプロトタイプは生き残りました。ユーザーもいます。ここから意思決定がたまっていきます。そして、ドキュメントとして最も価値が高いのは「使わないと決めたもの」です。

## Architecture decisions

### Frontend
- React 18 + TypeScript 5.0
- State: Zustand (Reduxは規模的に過剰でした)
- UI: Material-UI (カスタムデザイン作業を最小化)
- Routing: React Router v6

### Backend
- Node.js 18 + Express 4
- API: REST (GraphQLは延期 -- 複雑さが増えるだけで、まだ利用者の需要がありませんでした)
- Auth: JWT + refresh token
- DB: PostgreSQL 15

### Rejected alternatives (and why)
- Vue.js: チームにはReactの経験がより深いメンバーがいる
- GraphQL: RESTで現在のユースケースはカバーでき、オーバーヘッドが少ない
- MongoDB: リレーショナルなデータモデルのほうが適している

「却下した代替案（および理由）」のセクションは、隠れた宝物です。これがないと、新しいチームメンバー（そして新しいClaudeのセッション）ごとに、あなたがすでに検討して却下したのと同じ代替案を提案され続けます。数か月前に決着している意思決定を、トークンを無駄にしてまた蒸し返すことになります。

私はこのことを苦い経験から学びました。Claudeはコードレビューで、GraphQLへの移行を提案し続けていたのですが、私が1行追加したところで止まりました：GraphQL: postponed -- REST covers current needs。このたった1行で、数十もの会話が節約できました。

この段階では、さらに「起きている最中のアーキテクチャ意思決定を記録し始める」べきです。ライブラリを選ぶたびに、ある方針を却下するたびに、PRレビューで論点が決着するたびに――それをCLAUDE.mdに追記してください。将来のあなた、そして将来のClaudeが、今のあなたに感謝します。コストは意思決定ごとに1行。見返りは、その後のすべてのセッションが、空の状態から始まるのではなく、共有された文脈から始められることです。

Stage 3: The production rulebook

アプリは稼働しています。ユーザーが支払っています。ここからは状況の重要度が上がり、最も多くのチームが飛ばしてしまうセクションが一番重要になります：「これを絶対にやらない」。

## Coding standards

### TypeScript
- Interface名: PascalCase、先頭にIを付けない
- nullよりundefinedを優先（APIの一貫性のため）
- 共通の型はtypes/にまとめる、コンポーネントローカルの型はインライン

### React
- 関数コンポーネントのみ（クラスコンポーネントなし）
- カスタムフック: use- プレフィックスが必須
- props: 3つ以上のプロパティがある場合は分解代入

## Never do this

### Security
- JWTをlocalStorageに保存しない --> httpOnly cookiesを使う
- フロントエンドコードにAPIキーを埋め込まない
- SQLを文字列連結で組み立てない --> パラメータ化クエリのみ

### Performance
- useEffectの依存配列を省略しない（無限ループのリスク）
- 動的なリストでkey={index}を使わない
- 最適化なしで画像をレンダーしない（next/imageを使う）

### Operations
- 本番ブランチに直接pushしない
- バックアップなしでマイグレーションを実行しない
- ログを最初に確認せずにロールバックしない

（はい、一度だけlocalStorageにJWTを保存したことがあります。でもそれについて話すつもりはありません。）

「これを絶対にやらない」セクションが効く理由は、Claudeがそれをハード制約として扱うからです。Claudeに認証を実装してと頼むと、localStorageの提案すらしません――その選択肢は事前に排除されているからです。これが文脈エンジニアリングの本質です：質問が投げられる前に、解決策の空間を形づくる。もう少し実務的に言えば、テキストファイルにルールを書いてしまえば、Claudeはあなたがすでに決めたことについて延々と言い争う必要がなくなります。

ここにセキュリティの制約も入れるべきです。もしCLAUDE.mdに「パラメータ化クエリのみ」と書いてあれば、Claudeはデフォルトでパラメータ化クエリを生成します。リマインドも不要です。コードレビューでの見逃し対策も不要です。文脈が仕事をしてくれます。

Stage 4: The enterprise harness

あなたのチームは12人に増えました。モノリスは6つのサービスに分割されました。CLAUDE.mdは今300行になり、あなたのコンテキストウィンドウを食い潰しています。

分割する時が来ました。

project/
├── CLAUDE.md                  # 中核ルールのみ（約50行）
├── docs/
│   ├── ARCHITECTURE.md        # システム設計の詳細
│   ├── API-DESIGN.md          # API設計ガイド
│   └── SECURITY.md            # セキュリティ要件
└── .claude/
    └── agents/
        ├── frontend.md        # フロントエンドの専門家
        ├── backend.md         # バックエンドの専門家
        └── devops.md          # DevOpsの専門家

親のCLAUDE.mdはスリムに保ちます――プロジェクト概要、共有ルール、専門知識がどこにあるかの地図だけ。各サブエージェントのファイルには、関連する場合にだけ読み込まれる領域固有の文脈が入っています。

本当の力は、作業内容に応じて文脈を自動注入するフックにあります：

#!/bin/bash
# .claude/hooks/user-prompt-submit.sh

PROMPT="$1"

返却形式: {"translated": "翻訳されたHTML"}if echo "$PROMPT" | grep -qi "react\|component\|hook\|frontend"; then
    cat .claude/agents/frontend.md
fi

if echo "$PROMPT" | grep -qi "api\|database\|auth\|backend"; then
    cat .claude/agents/backend.md
fi

# セキュリティの観点は、認証関連の作業では常に読み込まれます
if echo "$PROMPT" | grep -qi "auth\|token\|security"; then
    cat docs/SECURITY.md
fi

これは、CI/CDで大規模コードベースが使っているのと同じパターンです。毎回すべてを実行しないこと。関連するものだけを読み込みます。コンテキストウィンドウは予算です――賢く使いましょう。

実際にどのように見えるか

私のチームでは、この分割によって平均のコンテキスト消費量が約40%減りました。分割前は、Claudeの各セッションがタスクに関係なくルール300行以上を読み込んでいました。分割後はこうです。フロントエンドのバグ修正なら約80行（core + frontend.md）、データベースのマイグレーションなら約90行（core + backend.md）、デプロイのタスクなら約70行（core + devops.md）です。

意外だったのは一貫性でした。フロントエンドの専門家用コンテキストが読み込まれていると、ClaudeはUIの問題に対してバックエンドのパターンを提案しません。DevOpsのコンテキストが有効なときも、インフラの問題に対してアプリケーションレベルの修正を推奨しません。それぞれのサブエージェントは持ち場からはみ出しません――あなたがそう指示したからではなく、読み込まれたコンテキストが自然に解決策の探索空間を制約するからです。

注意点がひとつあります。コアのCLAUDE.mdは50行未満に保ちましょう。100行を超えた瞬間、同じ肥大化の問題に戻ります。私はこれを毎月レビューし、ドメイン固有のものはすべて専門ファイルに押し込みます。

graph TD
    A[CLAUDE.md<br/>コアルール 約50行] --> B[frontend.md<br/>React、UI、hooks]
    A --> C[backend.md<br/>API、DB、auth]
    A --> D[devops.md<br/>インフラ、CI/CD、監視]
    E[Hook: prompt analysis] --> |"react, component"| B
    E --> |"api, database"| C
    E --> |"deploy, docker"| D
    F[SECURITY.md] -.-> |"常にauthのために読み込まれる"| C

CLAUDE.md vs AGENTS.md: 異なる思想

OpenAIのCodexを使ったことがあるなら、AGENTS.mdを見たことがあるはずです。どちらのファイルもAIの振る舞いを設定しますが、デザイン思想が異なります：

AGENTS.mdはAIにどうあるべきかを伝えます。CLAUDE.mdはAIにどこにいるのかを伝えます。実際には、この両方のアプローチを組み合わせられます。

# CLAUDE.md

## AI Configuration
あなたはTaskFlowのシニア・フルスタックエンジニアです。
提案するすべてにおいて、保守性とセキュリティを優先してください。

## Project Context
[詳細なプロジェクト情報――CLAUDE.mdのやり方で]

## Standards
[チームの慣習と制約]

このハイブリッドアプローチでは、Claudeにアイデンティティとコンテキストの両方が与えられます。この組み合わせは、セッションをまたいでもっとも一貫した結果を生むと感じています。

あなたの番

今週やることはこれです：

• [ ] 現在のCLAUDE.mdがどの段階（1〜4）にあるか確認する
• [ ] 足りないセクションを追加する――特に「絶対にやらないこと」
• [ ] ファイルが100行を超えているなら、サブエージェント用ファイルに分割を始める

あなたのCLAUDE.mdは今、どの段階でしょうか？コメントをください――6か月前にテンプレをコピペしてそのまま触っていない人たちが、どれくらいいるのか本当に気になります。

もっと深掘りしたいなら
Practical Claude Code -- Context Engineering for Modern Development は、CLAUDE.mdのパターン、サブエージェント設計、hooks、そしてコンテキストエンジニアリングの全ワークフローを詳細に扱っています。この記事の4段階の進化は、より大きなシステムの一章です。