チームでClaude Codeを使い始めた瞬間、問題が起きる。同じプロジェクト、同じコードベースなのに、メンバーによってAIの出力の質も一貫性もバラバラになる。原因はシンプルだ——全員が「自分だけのClaudeに語りかけている」からだ。
CLAUDE.mdは新人への引き継ぎ書だ
Claude Codeを起動するたびに、AIはゼロから始まる。前回のセッションで何をしていたか、このプロジェクトがどんな規約で動いているか、何も知らない状態でスタートする。CLAUDE.mdはその問題を解決するための仕組みだ。
公式ドキュメントによれば、CLAUDE.mdはセッション開始時に自動で読み込まれる。プロジェクトルートに置けばそのプロジェクト専用、~/.claude/CLAUDE.mdに置けば全プロジェクト共通の設定として機能する。また、作業ディレクトリより上の階層にあるCLAUDE.mdも起動時に読み込まれるため、モノリポのようなディレクトリ構成でも柔軟に対応できる。
「毎回同じ説明をしなくていい引き継ぎ書を渡す」と考えれば分かりやすい。新人に口頭で「うちはTailwindを使っていて、コミット前にテストを走らせること。あとany型は禁止ね」と説明するより、引き継ぎ書に書いておく方がずっと確実だ。チームが3人になっても、10人になっても、書いた内容が一貫して伝わる。
Anthropicは公式ブログでCLAUDE.mdの役割をこう説明している。「プロジェクトのアーキテクチャ、コーディング標準、よく使う開発コマンド、テスト要件、独自のツール」を書く場所だと。
.claude/ディレクトリ全体の設計思想
CLAUDE.mdだけ設計しても、チームの標準化は不完全だ。.claude/ディレクトリ全体をひとつのアーキテクチャとして設計する必要がある。憲法・法律・施行規則に例えると分かりやすい。
- CLAUDE.md（憲法）: プロジェクト全体を貫く不変の原則。ここには「絶対に守ること」だけを書く
- rules/*.md（法律）: テーマ別の詳細規定。CLAUDE.mdから
@記法でインポートして読み込む - settings.json（施行規則）: Claudeに与える権限と制限。何を実行してよくて、何を実行してはいけないか
- hooks（警察）: ルールを自動で強制するシェルコマンド。違反を検知したら物理的にブロックする
- skills/（専門書）: オンデマンドで呼び出す深い知識。常に読み込む必要はないが、必要なときに使える
チームでの.claude/ディレクトリの全体像はこうなる。
.claude/
├── CLAUDE.md # プロジェクト憲法（簡潔に、要点だけ）
├── settings.json # 権限設定（許可・禁止コマンド、Hooks）
├── rules/ # テーマ別ルール（@importで参照）
│ ├── code-style.md # フォーマット・命名規則の詳細
│ ├── git-workflow.md # ブランチ・コミット・PR規約
│ └── testing.md # テスト方針・カバレッジ基準
└── skills/ # チーム共有カスタムコマンド
├── review/
│ └── SKILL.md # /review — コードレビュー手順
└── fix-issue/
└── SKILL.md # /fix-issue — Issue調査から修正まで
このディレクトリ全体をGitにコミットする。チームメンバーがgit pullすれば、全員が同じ設定でClaude Codeを動かせるようになる。
CLAUDE.mdに書くべきもの、書いてはいけないもの
CLAUDE.mdは何でも書けばいいわけではない。公式のベストプラクティスにはこう書かれている。「行ごとに『これを削除したらClaudeが間違いをするか？』と問え。そうでなければ削除しろ」。
書くべきもの:
- このプロジェクト固有のコマンド（
bun test、bun run check-allなど） - アーキテクチャの制約（FSDの依存ルール、importの書き方など）
- 禁止事項（
any型の使用禁止、特定ディレクトリへの配置禁止など） - よく間違えやすい判断軸（命名規則、ファイルの配置場所など）
- 詳細ドキュメントへの参照（
@.claude/rules/testing.mdのような形で）
書いてはいけないもの:
- AIが一般常識として知っていること（「読みやすいコードを書け」「DRY原則を守れ」など）
- 変更頻度が高い情報（バージョン番号、外部サービスの料金など）
- このプロジェクトに固有でない汎用的なアドバイス
❌と✅で対比してみる。
# ❌ 悪い例（AIが既に知っていることで埋まったCLAUDE.md）
## コーディングスタイル
- コードは読みやすく書くこと
- 変数名は分かりやすいものにすること
- 関数は短くすること
- DRY原則を守ること
- パフォーマンスを意識すること
- セキュリティを考慮すること
... （50行の「当たり前のこと」が続く）
# ✅ 良い例（このプロジェクトにしかない情報だけ）
## 開発コマンド
- テスト: `bun test`
- ビルド前チェック: `bun run check-all`（コミット前に必ず実行）
## アーキテクチャ制約
- FSD（Feature-Sliced Design）を使用
- 依存方向: `app → widgets → features → entities → shared`
- スライス外部からは必ず `index.ts` 経由でアクセスすること
## 禁止事項
- `any` 型の使用禁止
- `content/articles/` への記事配置禁止（ビルド対象外のため）
## 詳細ドキュメント
- Gitワークフロー: @.claude/rules/git-workflow.md
- テスト規約: @.claude/rules/testing.md
肥大化を防ぐ設計原則
チームで使い始めると、CLAUDE.mdに何でも追記したくなる誘惑がある。「またClaudeが間違えた。ルールを追加しよう」というサイクルが続くと、CLAUDE.mdはどんどん膨れあがる。
これが最も危険な罠だ。公式ドキュメントはこう警告している。「肥大化したCLAUDE.mdは、Claudeが実際の指示を無視するようになる」と。ルールを追加したのに守られない——その原因の多くはCLAUDE.mdが長すぎることだ。
100個のルールを同時に意識し続けられる人間はいない。AIも同じだ。重要なルールが50番目に書かれていたら、埋もれる。CLAUDE.mdは「簡潔さを維持すること」が最優先だ。
対策は@記法を使った分割だ。公式ドキュメントによれば、CLAUDE.mdから他のファイルをインポートできる。
# @記法でサブファイルをインポートする例
## 詳細規約
詳細なコーディング規約は @.claude/rules/code-style.md を参照。
Gitワークフローは @.claude/rules/git-workflow.md を参照。
CLAUDE.mdには「目次と重要ポイント」だけを書き、詳細は別ファイルに分ける。こうすることで、CLAUDE.mdは常に簡潔に保ちながら、必要な情報へのアクセスを確保できる。なお、インポートの深さは最大5階層まで対応している。
HooksとCLAUDE.mdの役割分担
CLAUDE.mdで「毎回テストを走らせてください」と書いても、Claudeが忘れることはある。これはCLAUDE.mdの構造的な限界だ。Hooksはその限界を埋める機能だ。
公式ドキュメントによれば、HooksはClaudeのツール呼び出し前後などの特定イベントで自動実行されるシェルコマンドだ。PreToolUseイベントでgit commitを検知し、テストが通らなければコミット自体をブロックできる。
CLAUDE.mdとHooksの役割分担はこうなる。
- CLAUDE.md: 「毎回テストを走らせてください」（お願い。AIがうっかり忘れることはある）
- Hooks: 「テストが通らなければコミットできない」（物理的な強制。例外なし）
settings.jsonでHooksを設定する例を見てみよう。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash(git commit*)",
"hooks": [
{
"type": "command",
"command": "bun run check-all || (echo 'check-all failed. Fix errors before committing.' && exit 1)"
}
]
}
]
}
}
同じsettings.jsonでClaudeの実行権限も制御できる。チームとして許可したいコマンド、絶対に実行させたくないコマンドを明示的に設定する。
{
"permissions": {
"allow": [
"Bash(bun run *)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git add *)",
"Bash(git commit *)"
],
"deny": [
"Bash(git push --force *)",
"Bash(rm -rf *)"
]
}
}
ルールを「お願い」で済ませるか、「強制」にするかは、チームのリスク許容度で判断する。重要なルールほどHooksで強制する方が確実だ。
Skillsでチームの定型操作を共有する
チームがよく使う操作を定型化しておくと、全員の作業が統一される。公式ドキュメントによれば、.claude/skills/<name>/SKILL.mdに置いたファイルが/skill-nameコマンドとして使えるようになる。
Issueを調査・修正・PR作成まで一貫して対応するSkillsの例を見てみよう。
<!-- .claude/skills/fix-issue/SKILL.md -->
---
name: fix-issue
description: GitHubのIssueを調査・修正・PR作成まで一貫して対応する
---
GitHub Issueの番号: $ARGUMENTS
1. `gh issue view $ARGUMENTS` でIssue内容を確認する
2. 関連ファイルを調査して根本原因を特定する
3. 修正を実装し、テストを追加する
4. `bun run check-all` が通ることを確認する
5. 説明的なコミットメッセージでコミットし、PRを作成する
使い方は/fix-issue 1234と入力するだけだ。このファイルをGitにコミットすれば、チーム全員が同じ手順でIssue対応できる。
なお、以前の.claude/commands/ディレクトリへのMarkdown配置という方式も引き続き動作するが、現在の推奨はSkillsへの移行だ。個人用のSkillsを~/.claude/skills/に置くことで、特定プロジェクトに縛られない全プロジェクト共通のコマンドも持てる。
SkillsとHooksはどちらも.claude/settings.jsonと組み合わせて使う。Skillsは「人間が任意のタイミングで呼び出す定型手順」、Hooksは「Claudeが何かを実行するときの自動チェック」だ。役割が異なるので、両方設計することでチームの標準化が完成する。
チームへの導入手順
最初から完璧なCLAUDE.mdを書こうとしない方がいい。公式ドキュメントが推奨する出発点は/initコマンドだ。コードベースを解析し、ビルドシステム・テストフレームワーク・コーディングパターンを検出して、スターターとなるCLAUDE.mdを自動生成してくれる。これを叩き台にして、チームで議論しながら育てていく。
CLAUDE.mdはコードと同じく育てるものだ
CLAUDE.mdは書いたら終わりのドキュメントではない。コードと同じく、プロジェクトと一緒に育てるものだ。
Claudeが間違えるたびに「なぜ間違えたのか」を分析する。CLAUDE.mdに情報が足りなかったのか、情報が多すぎて埋もれていたのか、それともHooksで強制すべきルールをお願いベースにしていたのか。その判断を繰り返すことで、チームのCLAUDE.mdはどんどん精度が上がる。
コードで問題が起きたとき、次回同じ問題が起きないようにテストを書く。Claudeで問題が起きたとき、次回同じ問題が起きないようにCLAUDE.mdを更新する。それだけのことだ。
チームのCLAUDE.mdが成熟してくると、新しいメンバーがプロジェクトに加わったときも、数分でClaude Codeが適切に動き始める。「このプロジェクトではこういう規約で動く」という知識が、CLAUDE.mdというかたちでチームに蓄積されていく。
