CLAUDE.mdを『育てる』技術 — 3ヶ月運用して辿り着いたベストプラクティス15選

結論：CLAUDE.mdは「書いて終わり」ではなく「育てるもの」

CLAUDE.mdは『書いて終わり』ではありません。3ヶ月間、毎日Claude Codeを使い続けて気づいた「育てる」という発想と、実際に効果があった15のプラクティスを全公開します。

私が3ヶ月の運用で得た最大の学びはこれです。

• CLAUDE.mdは「設定ファイル」ではなく「生きたドキュメント」である
• 週1回のレビューサイクルを回すだけで、Claude Codeの出力精度が体感で2〜3倍になった
• チームの暗黙知をAIに伝える最短経路は、CLAUDE.mdを丁寧に育てること

この記事では、失敗談から実際のファイル全文、コピペ可能なテンプレートまで、すべてお見せします。

環境・前提条件

項目	内容
ツール	Claude Code（CLI版）
運用期間	2025年3月〜6月（約3ヶ月）
プロジェクト規模	TypeScript / Next.js（約2万行）
チーム構成	エンジニア3名
CLAUDE.mdの配置	プロジェクトルート直下

1. CLAUDE.mdとは何か — プロジェクトの「人格設定書」

CLAUDE.mdは、Claude Codeがプロジェクトで作業する際に自動的に読み込む指示書ファイルです。プロジェクトルートに置くだけで、Claudeの振る舞いをカスタマイズできます。

しかし、単なる「設定ファイル」と捉えると、その真価を見誤ります。

私はこう考えています。**CLAUDE.mdはプロジェクトの「人格設定書」**です。

• 新メンバーに渡すオンボーディング資料
• コードレビューで毎回指摘する「暗黙のルール」
• チームが大事にしている設計思想

これらをすべて凝縮したものがCLAUDE.mdです。人間の新メンバーに伝えたいことを、AIにも伝える。その発想がスタート地点になります。

2. 失敗から学んだCLAUDE.mdアンチパターン5つ

3ヶ月の運用で、私は何度もCLAUDE.mdを書き直しました。最初の1ヶ月は失敗の連続です。同じ轍を踏まないよう、典型的なアンチパターンを共有します。

❌ アンチパターン1：曖昧な精神論を書く

<!-- ダメな例 -->
きれいなコードを書いてください。
ユーザーファーストで考えてください。

「きれい」の基準がないため、Claudeは毎回異なるスタイルで返してきます。

<!-- 改善例 -->
## コードスタイル
- 1関数は30行以内に収める
- 早期リターンを使い、ネストは最大3段まで
- 変数名は「動詞 + 名詞」形式（例: fetchUserData, validateEmail）

❌ アンチパターン2：巨大化させる（500行超え）

1ヶ月目で私のCLAUDE.mdは600行に膨れ上がりました。結果、Claudeが指示の優先順位を見失い、重要なルールを無視するケースが頻発しました。

目安は150〜300行です。それを超えたら分割か削減のサインです。

❌ アンチパターン3：更新を忘れる

技術スタックを変更したのにCLAUDE.mdを更新しなかった結果、Claudeが古いライブラリのAPIを使い続けるという事故が起きました。

❌ アンチパターン4：ネガティブ指示だけ書く

<!-- ダメな例 -->
- anyを使うな
- console.logを残すな
- マジックナンバーを使うな

「やるな」だけでは、Claudeは何をすべきかがわかりません。必ず「代わりにこうする」をセットで書きます。

<!-- 改善例 -->
- any → 具体的な型を定義する。不明な場合はunknown + 型ガードを使う
- console.log → loggerユーティリティ（src/lib/logger.ts）を使う
- マジックナンバー → src/constants/ 配下に定数として定義する

❌ アンチパターン5：他プロジェクトからコピペする

プロジェクトごとにコンテキストは異なります。別プロジェクトのCLAUDE.mdをそのまま持ってきたら、ディレクトリ構造もAPIの慣習も合わず、Claudeが混乱する出力を連発しました。

3. フェーズ別CLAUDE.md設計術

プロジェクトのフェーズによって、CLAUDE.mdに書くべき内容は変わります。これが「育てる」の核心です。

初期設計期（〜2週間）

最小限に始めます。書くのは4つだけ。

• 技術スタック（言語、フレームワーク、主要ライブラリとバージョン）
• ディレクトリ構造（ツリー形式で主要ディレクトリの役割を明記）
• 命名規則（ファイル名、関数名、コンポーネント名）
• 設計思想（クリーンアーキテクチャ？ドメイン駆動？等の大方針）

実装期（2週間〜2ヶ月）

日々の開発で「Claudeに毎回同じ指摘をしている」と感じたら、その都度CLAUDE.mdに追記します。

• エラーハンドリングのパターン
• テストの書き方・粒度
• よく使うコードパターンのスニペット
• APIレスポンスの型定義の方針

保守期（2ヶ月〜）

プロジェクトが安定したら、「守り」の指示を充実させます。

• 触ってはいけないレガシーコードの領域
• パフォーマンスの閾値
• セキュリティ要件
• 非推奨になったパターンと代替手段

4. 実際のCLAUDE.mdを全文公開＆解説

以下は、私が実際に運用しているCLAUDE.mdの全文です（プロジェクト固有の情報は一部変更しています）。

# CLAUDE.md

## プロジェクト概要
ECサイトの管理画面。商品管理・注文管理・顧客管理の3ドメインで構成。

## 技術スタック
- TypeScript 5.5 / Next.js 14 (App Router)
- Prisma (PostgreSQL) / TanStack Query v5
- Tailwind CSS + shadcn/ui
- Vitest + Testing Library
- パッケージマネージャ: pnpm

## ディレクトリ構造
src/
├── app/          # Next.js App Router ページ
├── components/   # UIコンポーネント（Atomic Design）
│   ├── atoms/
│   ├── molecules/
│   └── organisms/
├── features/     # ドメイン別ロジック（products, orders, customers）
│   └── [domain]/
│       ├── api/        # API通信層
│       ├── hooks/      # カスタムフック
│       ├── types/      # 型定義
│       └── utils/      # ドメイン固有ユーティリティ
├── lib/          # 共通ライブラリ（logger, auth, http-client）
└── constants/    # 定数定義

## コードスタイル
- 1関数30行以内。超えたら分割を検討
- 早期リターン必須。ネスト最大3段
- 変数名: camelCase（動詞+名詞）例: fetchProducts, validateOrderInput
- コンポーネント名: PascalCase 例: ProductListTable
- ファイル名: kebab-case 例: product-list-table.tsx

## 型定義ルール
- any禁止 → unknown + 型ガードを使う
- API レスポンス型は features/[domain]/types/ に定義
- Prismaの型をそのままUIに渡さない。必ずDTO変換する

## エラーハンドリング
- API呼び出しは必ず try-catch で囲む
- エラーは src/lib/logger.ts 経由でログ出力
- ユーザー向けエラーは toast で表示（sonnerライブラリ）
- 想定外エラーは Error Boundary でキャッチ

## テスト方針
- ビジネスロジック（features/*/utils/）: 単体テスト必須
- カスタムフック: renderHook でテスト
- UIコンポーネント: スナップショットは使わない。振る舞いテストのみ
- テストファイル名: *.test.ts(x)（同一ディレクトリに配置）

## Git
- コミットメッセージ: Conventional Commits（feat:, fix:, refactor: 等）
- 日本語禁止（コミットメッセージは英語）

## やらないこと
- CSS Modules は使わない → Tailwind で統一
- default export は使わない → named export のみ
- enum は使わない → as const + 型推論で代替

各セクションの意図

セクション	意図
プロジェクト概要	Claudeに「何のプロジェクトか」を一行で理解させる
技術スタック	バージョンまで指定し、古いAPIを使わせない
ディレクトリ構造	ファイルの置き場所を迷わせない
コードスタイル	定量的な基準を設け、レビュー指摘を減らす
型定義ルール	TypeScript特有の「any逃げ」を防止
エラーハンドリング	毎回指摘していたパターンをルール化
テスト方針	「テスト書いて」で適切な粒度のテストが出る
やらないこと	明確な禁止事項で出力のブレを防ぐ

5. CLAUDE.mdの「育て方」 — レビューサイクルとバージョン管理

CLAUDE.mdは書いたら終わりではありません。週1回のレビューサイクルを回すことで、精度が飛躍的に向上します。

具体的な運用フロー

1. 日次：気づいたら即メモ

Claudeの出力に違和感があったら、CLAUDE.mdの末尾に <!-- TODO: ○○のルール追記 --> とコメントを残しておきます。

2. 週次：金曜15分のレビュー

溜まったTODOを正式なルールに昇格させるか判断します。同時に、もう不要になったルールがないか確認します。

3. 月次：構造の見直し

セクションの順序や分量のバランスを再構築します。成長しすぎたセクションは別ファイルに分割することもあります。

バージョン管理のコツ

CLAUDE.mdはGitで管理します。当たり前のようですが、これが重要です。

git log --oneline -- CLAUDE.md

このコマンドで「いつ、なぜルールが変わったか」の履歴が残ります。コミットメッセージには変更理由を明記します。

docs(claude): add error handling rules - Claudeがtry-catchなしでAPI呼び出しを書く問題の対策

6. ベストプラクティス15選

3ヶ月の試行錯誤で効果を実感したプラクティスを、すべてまとめます。

基盤（最初に整える）

#1 プロジェクト概要を1文で書く

## プロジェクト概要
飲食店向けモバイルオーダーアプリのバックエンドAPI。

Claudeは最初の数行でプロジェクトのコンテキストを把握します。長い説明は不要です。1文で十分です。

#2 技術スタックにバージョンを明記する

## 技術スタック
- Node.js 20 / TypeScript 5.5
- Express 4.18（※ Honoへ移行予定、新規エンドポイントはHonoで実装）

バージョンがないと、Claudeが古いAPIを提案するリスクがあります。移行中の情報も書くと、新旧の使い分けを正しく判断してくれます。

#3 ディレクトリ構造をツリーで示す

テキストのツリー形式で書きます。各ディレクトリの責務を一言添えるのがコツです。Claudeがファイルの配置場所を間違えなくなります。

品質（実装期に追加）

#4 定量的なコードスタイル基準を設ける

「短い関数を書いて」ではなく「30行以内」。「ネストを浅く」ではなく「最大3段」。数値で示すと出力のブレが激減します。

#5 Good / Bad の具体例を併記する

## API呼び出しパターン

### ✅ Good
const { data, error } = await fetchProducts();
if (error) {
  logger.error("商品取得失敗", error);
  toast.error("商品の取得に失敗しました");
  return;
}

### ❌ Bad
const data = await fetch("/api/products").then(r => r.json());

具体例は100の説明に勝ります。Claudeは例示パターンを忠実に踏襲してくれます。

#6 禁止事項には代替手段をセットで書く

「〜するな」だけでは不十分です。「代わりに〜する」まで書いて初めてルールとして機能します。

#7 エラーハンドリングをパターン化する

API呼び出し、バリデーション、想定外エラーなど、パターン別にテンプレートを用意しておくと、毎回一貫した処理を書いてくれます。

#8 テスト方針を粒度別に定義する

「テスト書いて」とだけ言うと、Claudeは過剰にテストを書いたり、不十分だったりします。「ビジネスロジックは単体テスト必須」「UIは振る舞いテストのみ」のように粒度を指定します。

運用（継続的に改善）

#9 150〜300行に収める

長すぎるとClaudeが指示を見落とします。300行を超えたら「本当にこのルールは必要か？」と問い直します。

#10 週1回のレビューサイクルを回す

金曜日の15分で十分です。「今週Claudeに何を繰り返し指摘したか」を振り返り、CLAUDE.mdに反映します。

#11 Gitでバージョン管理する

変更理由をコミットメッセージに残すことで、「なぜこのルールが存在するのか」が追跡可能になります。

#12 チーム全員が編集権を持つ

CLAUDE.mdは特定の人が管理するものではありません。チーム全員がPRを出せる状態にしておくと、多角的な知見が集まります。

応用（慣れてから）

#13 フェーズ別に内容を切り替える

セクション3で解説した通り、プロジェクトの成熟度に応じて記載内容を進化させます。

#14 頻出プロンプトをスニペット化する

## よく使うタスクテンプレート
新しいAPIエンドポイントを作るときは以下の手順で：
1. features/[domain]/types/ に リクエスト/レスポンス型を定義
2. features/[domain]/api/ にAPI関数を作成
3. app/api/ にルートハンドラを作成
4. features/[domain]/api/ にテストを作成

#15 CLAUDE.md自体のレビューをClaudeに依頼する

これは意外と効果的です。以下のようにClaudeに聞いてみてください。

このCLAUDE.mdを読んで、矛盾している箇所、曖昧な箇所、不足している情報を指摘してください。

自分では気づかない曖昧さや矛盾を発見してくれます。

7. まとめ：CLAUDE.mdはチームの暗黙知をAIに伝える最短経路

3ヶ月の運用を通じて、確信を持って言えることが3つあります。

• CLAUDE.mdは「設定ファイル」ではなく「育てる生きたドキュメント」。週1回のレビューサイクルで精度が飛躍的に向上する
• 定量的・具体的・例示付きの3原則を守るだけで、Claudeの出力品質は劇的に変わる
• CLAUDE.mdを丁寧に育てることは、チームのコーディング規約を整備することと同義。AIのためだけでなく、人間のためにもなる

CLAUDE.mdは、チームの暗黙知をAIに伝える最短経路です。そして、それを育て続けることが、AI時代の開発チームの新しい基本動作になると考えています。

まずは今日、あなたのプロジェクトのCLAUDE.mdを開いて、1行追記するところから始めてみてください。

参考リンク

• Claude Code 公式ドキュメント - Memory — CLAUDE.mdの仕様と配置方法
• Claude Code 公式ドキュメント - Overview — Claude Code全体の概要
• Anthropic公式 - Claude Code Best Practices — Anthropicが推奨するベストプラクティス