1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【設計パターン集】CLAUDE.mdとSKILL.mdをチーム開発で運用する7つの型 ― 個人/少人数/大規模プロジェクト別テンプレート付き

1
Posted at

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点です。

  1. 一貫性: チームメンバー全員が同じ品質のAI出力を得られる
  2. 再現性: 指示書がバージョン管理されていれば、なぜその出力になったかを追跡できる
  3. 拡張性: 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は仕様書ではなく「チームの暗黙知を形式知化したもの」。コードと同じようにバージョン管理し、定期的に見直す運用が重要です

参考リンク

1
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?