CLAUDE.mdを「とりあえず書いてる」状態から卒業しませんか?――3つのプロジェクト規模で実際に運用して見えた、再現性のある7つの設計パターンをテンプレートごと公開します。
結論: CLAUDE.mdの「構造設計」でAIの出力品質は劇的に変わる
Claude Codeの出力品質を決めるのは、プロンプトの巧みさではなく指示書(CLAUDE.md / SKILL.md)の構造です。本記事では、個人開発・少人数チーム・大規模プロジェクトの3フェーズで実際に試行錯誤した結果を、再現可能な7つの設計パターンとして体系化しました。
この記事を読むと、以下がわかります。
- プロジェクト規模ごとに最適なCLAUDE.md / SKILL.mdの設計パターン
- やりがちなアンチパターンとその改善方法
- そのままコピーして使えるテンプレート全文
環境・前提条件
| 項目 | 内容 |
|---|---|
| ツール | Claude Code(CLI版) |
| 対象ファイル |
CLAUDE.md(プロジェクト指示書)、.claude/skills/ 配下の SKILL.md 群 |
| 前提知識 | Claude Codeの基本操作、Markdownの記法 |
| 検証環境 | macOS / Linux、Git管理下のプロジェクト |
CLAUDE.mdとSKILL.mdの役割の違い
CLAUDE.md: プロジェクトルートに置く「全体方針書」。コーディング規約、アーキテクチャ方針、禁止事項などを記述SKILL.md(.claude/skills/*.md): 特定のタスクやドメイン知識を切り出した「専門スキル定義」。Claude Codeが必要に応じて参照する
なぜCLAUDE.md / SKILL.mdの設計が重要なのか
Claude Codeは、コードを書く前に必ずCLAUDE.mdを読みます。ここに書かれた指示が曖昧であれば、出力も曖昧になります。逆に、構造化された明確な指示書があれば、人間がレビューで指摘するような観点をAI自身が事前に適用してくれます。
特に重要なのは以下の3点です。
- 一貫性: チームメンバー全員が同じ品質のAI出力を得られる
- 再現性: 指示書がバージョン管理されていれば、なぜその出力になったかを追跡できる
- 拡張性: SKILL.mdに知識を分離することで、指示書の肥大化を防げる
パターン①〜③: 個人開発向け
パターン①: ミニマル型
適用場面: 個人の小規模プロジェクト、プロトタイピング
最小構成のCLAUDE.mdだけで運用するパターンです。SKILL.mdは使わず、1ファイルに必要最低限の情報だけを書きます。
# CLAUDE.md
## プロジェクト概要
個人ブログのNext.jsアプリケーション
## 技術スタック
- Next.js 15 (App Router)
- TypeScript (strict mode)
- Tailwind CSS v4
## コーディング規約
- 関数コンポーネントのみ使用(クラスコンポーネント禁止)
- 型定義は `types/` ディレクトリに集約
- `any` 型の使用禁止
## コマンド
- dev: `npm run dev`
- build: `npm run build`
- test: `npm run test`
- lint: `npm run lint`
ポイント: 30行以内に収めること。迷ったら書かない。情報が足りなければ後から足す。
パターン②: コンテキスト集約型
適用場面: 個人開発だが、ドメインが複雑(金融計算、医療データ処理など)
CLAUDE.mdにドメイン知識のコンテキストを厚めに書くパターンです。AIが業務知識を理解した上でコードを書けるようになります。
# CLAUDE.md
## プロジェクト概要
確定申告の自動計算ツール
## ドメイン知識(重要)
- 所得税の計算は累進課税方式。税率テーブルは `src/constants/taxRates.ts` に定義済み
- 「所得控除」と「税額控除」は別概念。混同しないこと
- 金額計算は全て整数(円単位)で行う。浮動小数点は使用禁止
- 端数処理: 国税は切り捨て、地方税は切り上げ(法令準拠)
## アーキテクチャ
- ドメインロジックは `src/domain/` に集約
- 外部API呼び出しは `src/infrastructure/` に分離
- ドメイン層は外部ライブラリに依存しないこと
## テスト方針
- ドメインロジックは必ずユニットテストを書く
- テストデータは国税庁の計算例を使用(`tests/fixtures/` に配置済み)
ポイント: ドメイン知識セクションを設けて、AIが「判断に迷いそうなポイント」を先回りして明記します。
パターン③: タスクルーティン型
適用場面: 個人開発で、定型タスクを繰り返し実行する場合
CLAUDE.mdに加えて、SKILL.mdを1〜2ファイル用意し、繰り返しタスクの手順を定義するパターンです。
# CLAUDE.md
## プロジェクト概要
SaaSのバックエンドAPI(NestJS)
## 基本規約
- RESTful API設計に従う
- レスポンスは全て `{ data, error, meta }` 形式
- エラーハンドリングは例外フィルターに集約
## スキル参照
定型タスクは `.claude/skills/` 配下のスキル定義を参照すること
# .claude/skills/create-crud-endpoint.md
## スキル: CRUDエンドポイント作成
### 手順
1. `src/modules/{resource}/` ディレクトリを作成
2. 以下のファイルを生成:
- `{resource}.controller.ts` - ルーティング定義
- `{resource}.service.ts` - ビジネスロジック
- `{resource}.repository.ts` - DB操作
- `{resource}.dto.ts` - バリデーション定義
- `{resource}.entity.ts` - エンティティ定義
3. `src/app.module.ts` にモジュールを登録
4. テストファイルを `tests/modules/{resource}/` に作成
### 命名規則
- ファイル名: kebab-case
- クラス名: PascalCase
- エンドポイント: `/api/v1/{resource}` (複数形)
### バリデーション
- DTOには必ず `class-validator` のデコレータを付与
- ページネーションは `page` と `limit` パラメータ(デフォルト: page=1, limit=20)
ポイント: 「新しいAPIエンドポイントを作って」と指示するだけで、毎回同じ構造・同じ品質のコードが生成されます。
パターン④〜⑤: 少人数チーム向け(2〜5人)
パターン④: ロール分離型
適用場面: フロントエンド担当とバックエンド担当がいるチーム
CLAUDE.mdをルートに1つ置きつつ、サブディレクトリごとにもCLAUDE.mdを配置するパターンです。Claude Codeはカレントディレクトリから上位に向かってCLAUDE.mdを探索し、見つかったものをすべてマージして読み込みます。
project-root/
├── CLAUDE.md # 全体方針
├── frontend/
│ ├── CLAUDE.md # フロントエンド固有の規約
│ └── src/
├── backend/
│ ├── CLAUDE.md # バックエンド固有の規約
│ └── src/
└── .claude/
└── skills/
├── frontend-component.md
└── backend-api.md
# project-root/CLAUDE.md(全体方針)
## プロジェクト概要
ECサイトのフルスタックアプリケーション
## チーム共通規約
- コミットメッセージ: Conventional Commits 形式
- ブランチ: `feature/`, `fix/`, `chore/` プレフィクス
- PRは必ずテストが通ってからマージ
## 共通の型定義
- API のリクエスト/レスポンス型は `shared/types/` に定義
- フロントエンド・バックエンド双方から参照すること
# frontend/CLAUDE.md(フロントエンド固有)
## 技術スタック
- React 19 + TypeScript
- TanStack Query v5 でデータフェッチ
- Zustand で状態管理
## コンポーネント設計
- Presentational / Container パターンを採用
- `components/ui/` は汎用UIコンポーネント(ロジック禁止)
- `components/features/` は機能単位のコンポーネント
## テスト
- コンポーネントテスト: Vitest + Testing Library
- E2E: Playwright(`e2e/` ディレクトリ)
# backend/CLAUDE.md(バックエンド固有)
## 技術スタック
- Go 1.23 + Echo v4
- PostgreSQL 16 + sqlc
## API設計
- OpenAPI 3.1 スキーマ駆動開発
- スキーマは `api/openapi.yaml` に定義
- コード生成: `make generate`
## エラーハンドリング
- ドメインエラーは `domain/errors.go` に定義
- HTTPステータスコードへの変換は `handler` 層で行う
ポイント: 各担当者が自分の領域のCLAUDE.mdだけをメンテナンスすれば良いので、管理負荷が分散されます。
パターン⑤: レビュールール埋め込み型
適用場面: コードレビューの品質をチーム内で統一したい場合
SKILL.mdにレビュー観点を明記し、Claude Codeにセルフレビューさせるパターンです。
# .claude/skills/code-review-checklist.md
## スキル: コードレビューチェック
コードを生成・修正した後、以下のチェックリストで自己レビューを実施すること。
### セキュリティ
- [ ] SQLインジェクション対策(パラメタライズドクエリ使用)
- [ ] XSS対策(ユーザー入力のエスケープ)
- [ ] 認証・認可チェックの漏れがないか
- [ ] 機密情報がログに出力されていないか
### パフォーマンス
- [ ] N+1クエリが発生していないか
- [ ] 不要なデータの全件取得をしていないか
- [ ] インデックスが必要なクエリはないか
### 可読性
- [ ] 関数は単一責任になっているか
- [ ] マジックナンバーは定数化されているか
- [ ] 公開APIにはコメント(JSDoc/GoDoc)が付いているか
### テスト
- [ ] 正常系・異常系の両方をテストしているか
- [ ] 境界値のテストがあるか
- [ ] モックの使いすぎで実装と乖離していないか
問題が見つかった場合は、修正を適用してからコードを提示すること。
ポイント: チームのレビュー観点を暗黙知からSKILL.mdに移すことで、「レビューで毎回同じ指摘をする問題」が解消されます。
パターン⑥〜⑦: 大規模プロジェクト向け(6人以上)
パターン⑥: モノレポ対応型
適用場面: モノレポで複数パッケージを管理するプロジェクト
ルートのCLAUDE.mdには組織全体のルールだけを書き、各パッケージに個別のCLAUDE.mdを配置します。SKILL.mdもドメインごとにディレクトリを分けます。
monorepo-root/
├── CLAUDE.md # 組織全体ルール
├── packages/
│ ├── web-app/
│ │ ├── CLAUDE.md # Webアプリ固有
│ │ └── src/
│ ├── mobile-app/
│ │ ├── CLAUDE.md # モバイルアプリ固有
│ │ └── src/
│ ├── api-server/
│ │ ├── CLAUDE.md # APIサーバー固有
│ │ └── src/
│ └── shared-libs/
│ ├── CLAUDE.md # 共有ライブラリ固有
│ └── src/
└── .claude/
└── skills/
├── domain/
│ ├── payment.md # 決済ドメイン知識
│ ├── inventory.md # 在庫管理ドメイン知識
│ └── user-management.md # ユーザー管理ドメイン知識
├── operations/
│ ├── database-migration.md # DB マイグレーション手順
│ └── deployment.md # デプロイ手順
└── guidelines/
├── api-design.md # API 設計ガイドライン
└── error-handling.md # エラーハンドリング方針
# monorepo-root/CLAUDE.md
## 組織ルール(全パッケージ共通)
### 絶対に守ること
- 本番DBへの直接操作コマンドを生成しない
- APIキー・シークレットをコード内にハードコードしない
- `shared-libs` の公開APIを変更する場合は破壊的変更に注意し、全パッケージへの影響を確認する
### モノレポ構成
- パッケージマネージャ: pnpm workspace
- ビルド: Turborepo
- パッケージ間の依存は `workspace:*` で指定
### コミット規約
- Conventional Commits + スコープにパッケージ名を記載
- 例: `feat(api-server): ユーザー検索APIを追加`
ポイント: ルートのCLAUDE.mdは「絶対ルール」だけに絞り、詳細は各パッケージに委譲します。情報の階層構造がClaude Codeの参照精度を高めます。
パターン⑦: SKILL.mdバージョニング+PRレビュー運用型
適用場面: SKILL.mdの変更がチーム全体の出力品質に影響する大規模チーム
SKILL.mdの変更をPRレビュー必須とし、変更履歴と影響範囲を明記する運用パターンです。
# .claude/skills/domain/payment.md
---
version: 2.1.0
last_updated: 2025-01-15
reviewers: ["@payment-team-lead", "@senior-backend-eng"]
breaking_change: false
---
## スキル: 決済処理
### 変更履歴
- v2.1.0 (2025-01-15): サブスクリプション決済の冪等性キー対応を追加
- v2.0.0 (2024-12-01): 決済プロバイダを Stripe から複数対応に変更【破壊的変更】
- v1.0.0 (2024-10-01): 初版
### 決済フローの実装ルール
1. 全ての決済操作には冪等性キーを必ず付与する
2. 決済プロバイダの呼び出しは `PaymentGateway` インターフェース経由で行う
3. 決済失敗時はリトライ(最大3回、指数バックオフ)してから例外を投げる
4. 決済ステータスの遷移は `PaymentStateMachine` で管理する
### 禁止事項
- 決済金額の計算にfloat型を使わない(Decimal型を使用)
- 決済プロバイダのSDKをドメイン層で直接呼び出さない
- テスト環境でも本番のAPIキーを使わない
運用のコツ:
-
.github/CODEOWNERSに.claude/skills/のオーナーを設定し、PRレビューを自動アサインする - CIでSKILL.mdのフォーマットチェック(フロントマターの必須項目の有無など)を実行する
- 破壊的変更がある場合はSlack等でチームに通知する仕組みを入れる
アンチパターン3選 ― やりがちな失敗と改善例
❌ アンチパターン1: 全部入りCLAUDE.md
# ❌ 悪い例: 1ファイルに500行以上詰め込む
## コーディング規約
(100行)
## API設計
(80行)
## DB設計
(60行)
## デプロイ手順
(50行)
## トラブルシューティング
(100行)
## 会議メモ
(???行)
...
問題: Claude Codeのコンテキストウィンドウを圧迫し、重要な指示が埋もれる
改善: SKILL.mdにドメイン知識を分離し、CLAUDE.mdは100行以内に収める。会議メモなどの非技術情報は別管理にする。
❌ アンチパターン2: 曖昧な指示
# ❌ 悪い例
## コーディング規約
- きれいなコードを書く
- 適切にエラーハンドリングする
- パフォーマンスに気をつける
問題: 「きれい」「適切」「気をつける」は人間にも曖昧なので、AIにはさらに解釈が分かれる
改善: 具体的な基準を数値や実例で示す
# ✅ 良い例
## コーディング規約
- 1関数30行以内、1ファイル300行以内
- エラーは `AppError` クラスで型付けし、error codeを付与する(例: `USER_NOT_FOUND`)
- DBクエリは実行計画を考慮し、WHERE句のカラムにインデックスがあることを確認する
❌ アンチパターン3: 更新されないSKILL.md
問題: プロジェクト開始時に書いたきり放置され、現在のコードベースと乖離する
改善:
- SKILL.mdにバージョンと最終更新日を必ず記載する
- 月次でSKILL.mdの棚卸しをスプリントレビューに組み込む
-
last_updatedが3ヶ月以上前のSKILL.mdにCIで警告を出す
テンプレートファイル全文公開とディレクトリ構成例
以下は、少人数チーム(パターン④+⑤)向けのテンプレートです。コピーして自分のプロジェクトに合わせて編集してください。
ディレクトリ構成
your-project/
├── CLAUDE.md
├── frontend/
│ └── CLAUDE.md
├── backend/
│ └── CLAUDE.md
└── .claude/
└── skills/
├── create-component.md
├── create-api-endpoint.md
└── code-review-checklist.md
テンプレート: ルートCLAUDE.md
# CLAUDE.md
## プロジェクト概要
<!-- 1〜2行でプロジェクトの目的を書く -->
## 技術スタック
- フロントエンド:
- バックエンド:
- データベース:
- インフラ:
## 絶対ルール(これに違反するコードは生成しないこと)
-
-
-
## コマンド一覧
- dev: ``
- build: ``
- test: ``
- lint: ``
- format: ``
- test単体: ``
## Git規約
- ブランチ命名: `feature/`, `fix/`, `chore/`
- コミットメッセージ: Conventional Commits
- マージ戦略: Squash Merge
## ディレクトリ構成
<!-- 主要ディレクトリの役割を書く -->
テンプレート: SKILL.md
# .claude/skills/{skill-name}.md
---
version: 1.0.0
last_updated: YYYY-MM-DD
---
## スキル: {スキル名}
### 概要
<!-- このスキルが何をするのか1〜2行で -->
### 手順
1.
2.
3.
### 規約・制約
-
-
### 良い例
### 悪い例
まとめ: CLAUDE.mdは「生きたドキュメント」として育てる
- 規模に合ったパターンを選ぶ: 個人開発でパターン⑦を使う必要はないし、大規模チームでパターン①では回らない。現在のチームサイズと複雑度に合った型から始めるのが大切です
- CLAUDE.mdは100行以内、詳細はSKILL.mdに分離: 「全部入り」は最大のアンチパターン。CLAUDE.mdは全体方針だけ、ドメイン知識やタスク手順はSKILL.mdに切り出すことで、AIの参照精度が上がります
- 書いて終わりではなく、使いながら育てる: CLAUDE.md / SKILL.mdは仕様書ではなく「チームの暗黙知を形式知化したもの」。コードと同じようにバージョン管理し、定期的に見直す運用が重要です