個人開発のCLAUDE.md設計パターン — AIに「指示書」を書く技術

はじめに

Claude Code を使い始めた頃、私は「CLAUDE.md は技術スタックを並べておく場所」くらいに思っていました。

でも、複数プロジェクトを並行開発する規模になると、それでは足りません。毎回同じことを説明し直し、毎回同じミスを踏み、毎回同じレビュー指示を出す。AI を「使う」のではなく「介護している」感覚になります。

CLAUDE.md は 「Claude Code に毎セッション最初から読ませる、プロジェクトの憲法」 です。ここに何を書き、何を書かないかで、開発体験は劇的に変わります。

私は現在、3つの Web サービスを個人で開発・運用しており、それぞれに CLAUDE.md があります。さらに事業全体を束ねるルートディレクトリにも CLAUDE.md を置いています。合計4つの「指示書」を運用してきた中で見えてきた、実際に効いた設計パターン7つ をまとめます。

想定読者:

• Claude Code を使っているが、CLAUDE.md は最低限しか書いていない方

• AI に同じミスを繰り返されてイライラしている方

• 複数プロジェクトを並行運用していて指示の一貫性に悩んでいる方

前提：私の CLAUDE.md 運用構成

話を具体的にするため、まず構成を出します。

C:/Project/
├── CLAUDE.md           # 事業ルート（マネージャー指示書）
├── App1/CLAUDE.md      # FolioInk（サブスクブログPF）
├── App2/CLAUDE.md      # jir0.com（自分のHP/ポートフォリオ）
└── App3/CLAUDE.md      # エペナビ（APEXツールサイト）

ルートの CLAUDE.md では「私（Claude）はマネージャーで、依頼を受けたら適切な事業エージェントに委任する」と宣言し、各プロジェクトの CLAUDE.md では「プロジェクト固有のエージェントチーム」「技術スタック」「開発フロー規約」を定義しています。

このネストした構成自体が、最初に共有しておきたい設計パターンの1つです。

CLAUDE.md の進化、3段階

私の CLAUDE.md は、3段階の進化を経て今の形に落ち着きました。

第1段階から第3段階への進化は、ほぼ全てが「同じ失敗を踏んだあとに、その教訓を CLAUDE.md に成文化する」という積み上げで起きました。

CLAUDE.md は最初から完成形を書くものではなく、痛みを書き留めるノート として運用しています。

パターン1：「あなたの役割」を最初に宣言する

CLAUDE.md の冒頭で、Claude が今このプロジェクトでどういう立場かを明示します。

私のルート CLAUDE.md の冒頭はこうです。

## あなたの役割: マネージャー

あなた（Claude）はマネージャーとして、ユーザーの依頼を受けて以下を行う：

1. 依頼内容を分析し、どのエージェントが適任かを判断する
2. 複数の視点が有効な場合は並行で依頼する（Agent ツールを複数同時実行）
3. 各エージェントの回答を統合し、矛盾があれば整理してユーザーに提示する
4. 単純な質問や作業指示の場合は、エージェントを介さず直接対応する

これを書く前は、「市場調査して」とだけ言うと Claude が自分で WebSearch を始めていました。書いてからは、Market Researcher エージェント（サブエージェント）に委任するようになり、マネージャーが自分で動くなります。

役割宣言の効果は「振る舞いの統一」というより「責務の境界線を引く」こと です。何をするか以上に、何をしないか を Claude が理解します。

パターン2：技術スタックとディレクトリ構成は「目次」として書く

「コードを読めば分かることは書かない」という主張を見かけますが、私は逆の立場です。

技術スタックとディレクトリ構成は、Claude が最初の探索をスキップするための目次 として CLAUDE.md に書くべきです。（と言ってくれています。）

## 技術スタック

| カテゴリ | 技術 |
|---------|------|
| Framework | Next.js 15 (App Router) |
| ORM | Prisma 7 |
| 認証 | Auth.js v5 (Split Config) |
| 決済 | Stripe (Connect, Subscriptions, Payment Intents) |

これがないと、Claude は毎セッション package.json を Read し、prisma/schema.prisma を Glob し、src/app/api/ を Grep して構成を把握しようとします。1セッションで数十回のツール呼び出しが節約できます。

ポイントは、バージョン番号を入れる こと。Next.js 15 と書くだけで、Claude が「App Router 前提」「Server Components がデフォルト」と理解できる粒度になります。

パターン3：エージェント選定ガイドをテーブルで書く

複数のサブエージェントを定義しているなら、「依頼の種類 → 担当エージェント」のテーブル を必ず置きます。

| 依頼の種類 | 担当エージェント | 並行推奨 |
|-----------|----------------|---------|
| 「このアイディアどう思う？」 | Market Researcher + Growth Strategist + Business Advisor | 3名並行 |
| 「市場や競合を調べて」 | Market Researcher | 単独 |
| 「AとBどちらを優先すべき？」 | Business Advisor | 単独 |
| 「価格設定を相談したい」 | Market Researcher + Growth Strategist | 2名並行 |

このテーブルが効くのは「並行推奨」列です。

私はかつて Claude に「アイディア評価して」と頼むたびに、Market Researcher だけが返事して終わっていました。「3名並行で」と毎回追加で言うのが面倒で、テーブルに「並行推奨：3名並行」と書いた途端、Claude が単一メッセージで3つのエージェントを同時起動するようになりました。

「依頼の自然言語例」を書くのも重要 です。「アイディア評価」ではなく「このアイディアどう思う？」と書くことで、ユーザーの実際の言い方とマッチして発火しやすくなります。

パターン4：完了報告の順序を明文化する

これは個人開発で最も効いたパターンです。

### 完了報告の順序（重要）

実装・修正後は以下の順序で確認し、全て完了してからユーザーに報告する。
ユーザーの指摘を待たないこと。

1. 型チェック — `npx tsc --noEmit` でエラーがないことを確認
2. 単体テスト — `npx vitest run` で全テストがパスすることを確認
3. Lint — `npm run lint` でエラーがないことを確認
4. 脆弱性チェック — `npm audit --audit-level=high`
5. Reviewer レビュー — Reviewer エージェントによるコードレビューを実施
6. 修正 — Critical/Warning があればその場で修正してから報告する

書いていなかった頃は、「実装できました！」とだけ報告されて、私が tsc を回して型エラーが10個出てくる、という光景が日常でした。

順序を明示すると、Claude は「型 → テスト → Lint → audit → レビュー → 修正」を1ターンで全て回してから報告するようになります。CI が回っていない個人開発では、これが事実上の品質ゲートです。

「ユーザーの指摘を待たないこと」という一文を入れるかどうかで、Claude の自律性が大きく変わります。これがないと「テストも回しますか？」と聞き返されます。あると勝手に回します。

パターン5：禁止事項は理由付きで書く

「〜してはならない」だけ書くと Claude は守りますが、エッジケースの判断ができません。

私の CLAUDE.md はこういう書き方をしています。

## 禁止事項

- マネージャーが各プロジェクトのコードを直接変更してはならない
  — コード変更が必要な場合は、必ず該当プロジェクトのエージェントに
  Agent ツールで委任すること。委任時には該当スキル
  （`vercel-react-best-practices`等）の使用指示と
  Reviewer レビュー指示を含めること。
  マネージャーは事業戦略レベルの分析・判断・提案に集中する。

理由（「マネージャーは事業戦略レベルに集中するから」）まで書くことで、Claude は「じゃあ .logs/ への記録は事業戦略の周辺だから直接書いていい」「コードに見えるが設定ファイルは委任すべきか？」のような判断を文脈に沿って下せるようになります。

禁止事項のすぐ下に「代替手段」を書く のがコツです。「Aをするな」だけだと Claude は固まります。「Aではなく、Bという手順で行え」と書くと迷わず動けます。

パターン6：3strikes rule — 対処療法を検知する仕組み

これは私が最も気に入っているパターンです。

### 3strikes rule（対処療法の検知）

以下のいずれかに該当したら対処療法を中止し、設計自体を再検討する：

- 同一機能で修正が2回失敗した
- タイミング依存の修正（delay/retry/reload）を入れようとしている
- レイヤー越境の回避策（サーバーで完結すべき処理を
  クライアントに移す等）を検討している

これを書く前、Claude はテストが赤になると「setTimeout で 100ms 待ってから assert すれば通ります」みたいな提案を平気でしてきました。動けば良し、で進めると後から不安定なテストの山ができます。

3strikes rule を入れてからは、2回失敗した時点で Claude 自身が「対処療法に陥っている可能性があるので、Architect と設計を再検討しましょう」と切り替えるようになりました。

ヒューリスティクスを Claude に持たせる という考え方の例です。Claude は個別の判断は強いですが、「自分が対処療法ループに入っていることに気づく」のは苦手なので、外から検知ルールを与えます。

パターン7：セッション開始・終了時のチェックリスト

最後は地味ですが、作業もれをなくすのに効いたパターンです。

## セッション開始・終了時の Git 状態確認（必須）

- セッション開始時（最初の依頼に着手する前）:
  `git fetch` → `git status` → `git log @{u}..HEAD --oneline`
  で未コミット変更・未プッシュコミット・upstream との差分を確認

- セッション終了時:
  同様に確認し、取り残しがあればユーザーに報告する

- 取り残しを検知した場合:
  内容を確認したうえでユーザーに報告し、コミット・プッシュの要否を判断する
  （勝手にコミット・プッシュしない）

- 記録: 未プッシュコミットや未コミット変更が残ったまま
  セッション終了する場合、`.logs/activity.md` に「持ち越し」として記録する

これを書く前、私は「あれ、昨日コミットしたつもりだった変更が git status に残ってる」を何回かやらかしていました。Claude Code Cloud scheduled task が origin/main に直接コミットする機能を使い始めてからは、ローカルとリモートの差分も日常的に発生するようになり、より深刻になりました。

セッション冒頭に強制的に git fetch させることで、こうした取り残しがほぼゼロになりました。

「勝手にコミット・プッシュしない」という制約も大事です。これがないと Claude は親切心で勝手に push し始めます。Git 操作は破壊的なので、確認を挟む方針を明示します。

CLAUDE.md と memory の使い分け

Claude Code には auto memory という、セッションをまたいで記憶する仕組みがあります。これと CLAUDE.md の使い分けは混乱しがちなので、私のルールを書いておきます。

memory はチームメンバーには見えませんが、CLAUDE.md は将来チームに加わる人（または未来の自分）にも読まれることを前提にすると、自然と振り分けが決まります。

アンチパターン3つ

逆に、書かない方が良かったものも記録しておきます。

1. 「丁寧に答えてください」のような口調指示

効きません。Claude は元々丁寧です。文字数の無駄なので削除しました。

2. コードの「あるべき姿」を抽象的に書く

「保守性の高いコードを書くこと」「DRY を守ること」のような抽象指示は、実装者ごとに解釈が割れます。書くなら「src/lib/api/ の関数は必ず Zod でバリデーションすること」のように具体的に。

3. 全てを CLAUDE.md に詰め込む

CLAUDE.md は毎セッション読まれます。長すぎるとコンテキストを圧迫します。詳細仕様は docs/specification.md に切り出し、CLAUDE.md には**「docs/specification.md を参照」とポインタだけ書く** 構成が現実的です。

まとめ

CLAUDE.md は「Claude Code への指示書」というより、「過去の自分が踏んだ地雷の供養塔」 です。

7つのパターンを再掲します。

1. 役割を最初に宣言する — 何をしないかが明確になる

2. 技術スタックとディレクトリ構成を目次として書く — 探索コストの削減

3. エージェント選定ガイドをテーブルで書く — 並行推奨列を忘れない

4. 完了報告の順序を明文化する — 個人開発の事実上の CI

5. 禁止事項は理由と代替手段付きで書く — エッジケースで Claude が迷わない

6. 3strikes rule を入れる — 対処療法ループの自己検知

7. セッション開始・終了時のチェックリスト — Git 取り残し防止

最初から全部書く必要はありません。ミスを踏むたびに、その教訓を1行追加する という運用でやれば、自分の開発スタイルに合った CLAUDE.md が育ちます。

CLAUDE.md は「書かなくても動く」ファイルですが、書けば書くほど Claude が自走する範囲が広がります。ソロ開発で AI と組むなら、ここに投資する時間は最も回収率の高いリファクタリングのひとつだと思います。

関連リンク

• Claude Code 公式ドキュメント — CLAUDE.md

• Claude Code 公式ドキュメント — Sub agents

• Claude Code 公式ドキュメント — Skills