Claude CodeのCLAUDE.mdをチームで育てる書き方とレビュー観点
はじめに
Claude Codeをチームで使い始めると、最初に整えたくなるのが CLAUDE.md です。
ビルド手順、テストコマンド、ブランチ運用、レビュー前チェック、禁止したい変更などを一箇所に書けるため、AIエージェントの立ち上がりをかなり安定させられます。
ただし、CLAUDE.md は「何でも書ける共有メモ」ではありません。
書きすぎると読まれにくくなり、曖昧に書くと守られず、個人の好みを混ぜるとチーム内で衝突します。
この記事では、プロジェクトチームで共有する CLAUDE.md を、レビュー可能な運用文書として設計する観点を整理します。
CLAUDE.mdは設定ファイルではなく、共有された作業文脈
まず押さえるべきなのは、CLAUDE.md は厳密な設定ファイルではないという点です。
Claude Code公式ドキュメントでも、CLAUDE.md はセッション開始時に読み込まれる文脈であり、強制的な設定ではなく「Claudeのふるまいを導くための指示」として説明されています。
そのため、レビュー時には次の前提で見る必要があります。
- 守らせたいルールほど、短く具体的に書く
- 曖昧な行動規範より、実行可能なコマンドや判断基準を書く
- 矛盾したルールがあると、どれが優先されるか不安定になる
- 長大な説明は、必要な場面で読ませる別ファイルに分ける
CLAUDE.md は「プロジェクトに入ったAIエージェント向けのオンボーディング資料」と考えると設計しやすくなります。
チーム共有CLAUDE.mdに書くべき内容
チーム共有の CLAUDE.md では、個人の好みではなく、全員に適用されるプロジェクトルールを優先します。
1. 最初に確認すべきコマンド
AIに「たぶんこれで動くはず」と推測させると、不要なコマンド探索や壊れた検証が増えます。
まず、プロジェクトで正式に使うコマンドを書きます。
## Verify Commands
- Install: `pnpm install`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Unit test: `pnpm test`
- Build: `pnpm build`
Before reporting completion, run the smallest verification command that covers the changed area.
If a command fails because of unrelated existing errors, report the failure and do not hide it.レビュー観点は、コマンドが「実行できるか」だけではありません。
いつ、どの範囲で、失敗時にどう報告するかまで書かれているかを確認します。
2. 変更してよい範囲と、触ってはいけない範囲
Claude Codeは広い範囲を読めるため、指示が曖昧だと関係ないファイルまで修正することがあります。
## Change Scope
- Prefer minimal changes that solve the requested issue.
- Do not reformat unrelated files.
- Do not change public API names without explaining migration impact.
- Do not update lockfiles unless dependency changes are part of the task.ここで大事なのは、「禁止」だけで終わらせないことです。
必要な場合にどう説明すべきかまで書くと、レビュー時に判断しやすくなります。
3. レビュー前に見るべき観点
チームでClaude Codeを使うなら、実装完了後の自己レビュー観点も共有しておくべきです。
## Self Review Checklist
Before final response, check:
- Does the change match the requested scope?
- Are there unrelated rewrites?
- Is error handling consistent with nearby code?
- Are tests added or updated when behavior changes?
- Are verification results reported honestly?これは人間のコードレビューを置き換えるためではありません。
AIが出す最終報告を、レビューアーが読みやすい形に揃えるためのルールです。
書きすぎると危険な内容
CLAUDE.md は便利ですが、何でも入れると品質が落ちます。
個人の作業メモ
「自分はこのテストだけ見たい」「ローカルではこのポートを使う」といった個人設定は、チーム共有ファイルに入れるべきではありません。
個人用の指示は CLAUDE.local.md やユーザー側の設定に分けます。
長すぎる設計資料
巨大な設計資料を丸ごと貼ると、重要なルールが埋もれます。
必要なら @docs/architecture.md のように別ファイルへ分け、CLAUDE.md 本体には「いつ読むべきか」を書きます。
## Architecture References
- Read `@docs/auth-architecture.md` before changing authentication or authorization code.
- Read `@docs/billing-rules.md` before changing invoice calculation.抽象的な精神論
「きれいなコードを書く」「品質を高める」だけでは、AIにも人間にもレビューできません。
<!-- 弱い例 -->
- Write clean code.
<!-- 強い例 -->
- Prefer extracting duplicated validation logic into a named function when the same condition appears in three or more request handlers.レビュー可能なルールは、具体的な判断条件を持っています。
レビュー時に見るべき5つの観点
CLAUDE.md をチームで更新するPRでは、本文の正しさだけでなく、運用文書としての品質を見ます。
| 観点 | 確認すること |
|---|---|
| 再現性 | コマンドや手順が誰の環境でも実行できるか |
| 具体性 | 「よしなに」ではなく、判断条件が書かれているか |
| 範囲 | チーム共有すべき内容と個人設定が混ざっていないか |
| 衝突 | 既存ルールや下位ディレクトリの指示と矛盾しないか |
| 鮮度 | 廃止されたコマンドや古い設計方針が残っていないか |
とくに重要なのは、CLAUDE.md の変更もコードと同じようにレビュー対象にすることです。
AIエージェントの行動を変える文書なので、軽いREADME更新として扱うと、後から予期しない作業ミスにつながります。
チーム用テンプレート
最初の1枚としては、次の程度に絞るのが扱いやすいです。
# Project Instructions
## Project Overview
This repository is a web application for ...
## Verify Commands
- Install: `pnpm install`
- Lint: `pnpm lint`
- Test: `pnpm test`
- Build: `pnpm build`
## Change Scope
- Keep changes focused on the requested task.
- Do not reformat unrelated files.
- Do not change public APIs without explaining the impact.
## Coding Rules
- Follow existing patterns in nearby files.
- Prefer explicit error handling over silent fallback.
- Add or update tests when behavior changes.
## Review Before Final Response
- Summarize changed files.
- Report verification commands and results.
- Mention known risks or unverified areas.最初から完璧な文書を目指す必要はありません。
むしろ、Claude Codeが同じミスを繰り返したタイミングで、チーム合意のうえで1行ずつ足すほうが長持ちします。
まとめ
チーム共有の CLAUDE.md は、AIに命令するための裏技ではなく、プロジェクトの作業文脈を明文化するための運用資産です。
- 実行コマンドは、成功条件と失敗時の扱いまで書く
- 禁止事項は、なぜ禁止なのか、例外時にどう報告するかまで書く
- 個人設定や長大な設計資料は分離する
CLAUDE.mdの変更もレビュー対象として扱う
Claude Codeをチームに入れるなら、最初に整えるべきなのはプロンプトの技巧ではありません。
チームの判断基準を、短く、具体的に、レビュー可能な形で CLAUDE.md に落とすことです。