CLAUDE.mdでチームのAI作業を標準化する設定ガイド

結論

CLAUDE.mdはClaude Codeに「このプロジェクトでは何に従って作業すべきか」を伝えるファイルです。チームのコーディング規約・テスト基準・デプロイ手順をここに書くことで、新しいメンバーが加わってもAIが同じ基準で作業するようになります。

設定を正しく階層化することが重要です。全員に共有すべき設定はプロジェクトレベルに、個人の好みは個人レベルに置きます。ここを間違えると「自分には効いているのにチームメンバーには効かない」という問題が起きます。

---

CLAUDE.mdの3層階層

CLAUDE.mdの設定は3つのレベルで読み込まれます。

~/.claude/CLAUDE.md          ← ユーザーレベル（個人設定）
      ↓
リポジトリルート/CLAUDE.md    ← プロジェクトレベル（チーム共有）
または
.claude/CLAUDE.md
      ↓
src/components/CLAUDE.md      ← ディレクトリレベル（特定領域のみ）

全てのレベルが読み込まれ、より具体的な設定が優先されます。

よくある間違い：個人設定が共有されていない

「自分のClaude Codeは正しく動くのに、新しいメンバーが使うと規約に沿ったコードが生成されない」という問題の原因の多くは、設定が~/.claude/CLAUDE.md（ユーザーレベル）に書かれていることです。

ユーザーレベルの設定はバージョン管理に入らないため、他のメンバーには共有されません。

チーム全体で使う設定（コーディング規約・命名ルール・テスト基準）は必ずプロジェクトレベルに置きます。

個人レベル（~/.claude/CLAUDE.md）に書くもの:
- 個人的な作業スタイルの好み
- 実験中の設定
- プライベートなAPIキーや認証情報

プロジェクトレベル（.claude/CLAUDE.md）に書くもの:
- コーディング規約・命名規則
- テストの書き方・命名パターン
- デプロイ手順・必要なチェックリスト
- よく使うコマンドや設定値

---

@importでCLAUDE.mdをモジュール化する

プロジェクトが大きくなると、1つのCLAUDE.mdに全ての情報を書くと読みにくくなります。@import構文を使うとファイルを分割できます。

# CLAUDE.md（プロジェクトルート）

@import ./docs/coding-standards.md
@import ./docs/testing-guide.md
@import ./docs/deployment.md

これにより、コーディング標準はコーディング標準のファイルで管理し、テストガイドはテストガイドのファイルで管理できます。それぞれの担当者が自分の領域だけを更新できるため、メンテナンスが楽になります。

モノレポ構成では、各パッケージのCLAUDE.mdからそのパッケージに関連するドキュメントだけをインポートする形が整理されます。

packages/frontend/CLAUDE.md → @import ../../docs/react-conventions.md
packages/api/CLAUDE.md      → @import ../../docs/api-standards.md
packages/infra/CLAUDE.md    → @import ../../docs/terraform-conventions.md

---

.claude/rules/でパス固有のルールを設定する

コーディング規約はファイルの種類によって変わることが多いです。ReactコンポーネントはFunctional Components+Hooksの書き方、APIハンドラはasync/awaitのエラーハンドリング、テストファイルは特定の命名パターン、のように。

ディレクトリ別にCLAUDE.mdを置く方法もありますが、テストファイルのようにコードベース全体に散らばっているものには対応できません。

この問題を解決するのが.claude/rules/ディレクトリのパス固有ルールです。

---
# .claude/rules/testing.md
paths:
  - "**/*.test.tsx"
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

# テストファイルの規約

テストは次の構造で書くこと:
- describe: テスト対象のコンポーネント名
- it: 「〜のとき、〜すること」の形式で記述
- mockは src/test/mocks/ の共通モックを優先使用
- data-testid属性でDOM要素を選択すること

このファイルを置くと、*.test.tsxにマッチするファイルを編集するときだけこのルールが読み込まれます。他のファイルを編集中は読み込まれないため、トークンの無駄遣いを防げます。

---
# .claude/rules/terraform.md
paths:
  - "terraform/**/*"
  - "**/*.tf"
---

# Terraform規約

- リソース名はスネークケース: aws_s3_bucket
- タグには必ずEnvironment・Owner・Projectを含める
- モジュールのバージョンは固定値で指定すること

パス固有ルールが特に効果的なケース:

• テストファイル（プロジェクト全体に散らばっている）
• 特定言語のファイル（**/*.py・**/*.go）
• インフラ定義ファイル（terraform/**/*・*.yaml）

---

カスタムスラッシュコマンドの作り方

繰り返し行う作業をスラッシュコマンドとして登録すると、毎回プロンプトを書く手間がなくなります。

チーム共有コマンド（.claude/commands/）

# .claude/commands/review.md

このファイルの変更点をレビューしてください。確認する項目:
1. セキュリティの問題（SQLインジェクション・XSS・認証情報のハードコード）
2. エラーハンドリングの漏れ
3. このコードベースの規約からの逸脱
4. パフォーマンス上の懸念点

各問題について、ファイル名・行番号・問題の説明・推奨する修正方法を報告してください。

このファイルを.claude/commands/review.mdに置くと、Claude Codeで/reviewコマンドが使えるようになります。リポジトリをクローンした全員が同じコマンドを使えます。

個人用コマンド（~/.claude/commands/）

チームの標準コマンドを自分のスタイルに合わせてカスタマイズしたい場合は、~/.claude/commands/に別名で保存します。チームメンバーに影響を与えません。

チームの標準: .claude/commands/review.md → /review
個人カスタマイズ: ~/.claude/commands/myreview.md → /myreview

---

Skillsによる高度なコマンド設定

スラッシュコマンドより高度な設定が必要な場合は、Skillsを使います。SkillsはSKILL.mdファイルにフロントマターで動作オプションを指定できます。

context: forkで出力を分離する

---
# .claude/skills/analyze-codebase.md
context: fork
allowed-tools: Read, Grep, Glob
argument-hint: "分析したいモジュール名を入力してください"
---

# コードベース分析

指定されたモジュールの依存関係・公開インターフェース・テストカバレッジを分析してください。
...

context: forkを指定すると、このスキルは独立したサブエージェントとして実行されます。コードベース全体を読み込むような詳細な出力がメインの会話に積み上がることを防ぎ、コンテキストウィンドウを節約できます。

context: forkが適しているケース:

• コードベース全体を探索する調査タスク
• ブレインストーミングや複数の選択肢の比較
• 長い出力が予想される分析作業

allowed-toolsでツールを制限する

---
context: fork
allowed-tools: Read, Write
---

# ドキュメント生成

ソースコードを読み取り、APIドキュメントを生成してください。
ファイルの削除や実行コマンドは禁止です。

allowed-toolsを指定することで、このスキル実行中はReadとWriteしか使えなくなります。破壊的な操作を防ぐ安全策になります。

argument-hintでパラメータを促す

---
argument-hint: "対象コンポーネント名（例: OrderForm）"
---

引数なしでスキルを実行しようとすると、Claude Codeがこのヒントを表示してパラメータの入力を促します。

---

CLAUDE.md vs スラッシュコマンド vs Skills の使い分け

3つの仕組みはそれぞれ使いどころが違います。

設定方法	いつ読み込まれるか	適した用途
CLAUDE.md	常に（セッション開始時）	常に守るべきコーディング規約・命名ルール
パス固有ルール（.claude/rules/）	対象ファイル編集時のみ	ファイルタイプに応じた規約
スラッシュコマンド	手動で呼んだとき	繰り返し使う定型的な指示
Skills	手動で呼んだとき	特定の作業フロー・ツール制限が必要な処理

常に守るべきルールはCLAUDE.mdに、繰り返し実行する定型作業はコマンドやSkillsに、という分担が基本です。

CLAUDE.mdに全てを詰め込むと、セッションごとに関係ないルールも全て読み込まれてトークンを消費します。作業内容に応じて読み込む設定を絞ることで、コンテキストウィンドウを効率的に使えます。

---

設定が正しく読み込まれているか確認する方法

設定が意図どおりに効いているか確認するには、Claude Code内で/memoryコマンドを実行します。現在読み込まれているメモリファイルの一覧が表示されます。

「設定したはずなのにClaude Codeが従わない」という問題の多くは、設定ファイルが正しいパスにない・ユーザーレベルの設定になっている・ファイルの文法エラーで読み込まれていないケースです。

/memoryで確認して対象ファイルが一覧に含まれていれば、設定は読み込まれています。

---

実際のCLAUDE.md記述例

参考として、TypeScript + Reactプロジェクトを想定したプロジェクトレベルCLAUDE.mdの例です。

# Project: ECサイトフロントエンド

## コーディング規約
- TypeScriptのstrictモードを使用
- Functional Componentsのみ（Class Componentは禁止）
- カスタムHooksは src/hooks/ に置く
- APIクライアントは src/api/ に置き、コンポーネントからの直接fetchを禁止

## 命名規則
- コンポーネント: PascalCase（例: OrderSummary）
- Hooks: use始まり（例: useOrderStatus）
- 定数: UPPER_SNAKE_CASE
- ファイル名: コンポーネントと同名

## テスト基準
- 新規コンポーネントには必ずテストを作成
- src/test/mocks/ の共通モックを使う
- data-testid属性で要素を選択する

## よく使うコマンド
- 開発サーバー: npm run dev
- テスト: npm test
- 型チェック: npm run typecheck

具体的であるほど、Claude Codeはこの規約に従ったコードを生成しやすくなります。「良いコードを書いてください」より「src/hooks/に置いてください」の方が明確です。

CI/CDとの統合設定についてはClaude CodeをCI/CDパイプラインに組み込む実践ガイドで詳しく解説しています。プランモードとの使い分けについてはClaude Codeのプランモードと直接実行の判断基準も合わせて参照してください。

---

まとめ

CLAUDE.mdの設定で押さえるべきポイントをまとめます。

• チーム共有の設定はプロジェクトレベルに。個人設定との混在に注意
• @importで大きなCLAUDE.mdを分割・管理しやすくする
• パス固有ルール（.claude/rules/）でファイルタイプごとの規約を自動適用
• チーム共有コマンドは.claude/commands/、個人用は~/.claude/commands/
• Skillsのcontext: forkでコードベース探索などの詳細タスクをメイン会話から切り離す
• /memoryコマンドで設定が正しく読み込まれているか確認する

これらを整備することで、チームメンバー全員が同じ基準でClaude Codeを使えるようになり、コードレビューで「規約に合っていない」という指摘が減ります。