CLAUDE.mdは、新しく参加したメンバーが必要とするようなコンテキストをClaudeに提供します。規約、コマンド、アーキテクチャ、そしてチームが最も頻繁に目にする間違いなどが含まれます。かつては人々の頭の中やwikiにあった知識が、エージェントがセッション開始時に読み込むファイルとなり、チーム全体で維持され、間違いが発生するたびに改善されていきます。
はじめに
- 前提条件: なし。
- インフラストラクチャ: リポジトリ、インストールされたClaude Code、そしてコードベースをよく理解しているエンジニア1名。
実行方法
- リポジトリで
/initを実行します。Claudeは見つけた情報から初期のCLAUDE.mdを生成します。 - 生成されたファイルを、新しく参加したメンバーが初日に必要とする内容まで絞り込みます。ビルド、テスト、lintのコマンド、重要な規約、そしてClaudeが繰り返し間違える事項を残します。
CLAUDE.mdをリポジトリのルートでGitにチェックインし、チーム全体が1つのバージョンを共有し、変更がコードと同様にレビューされるようにします。- ここでは運用ルールが役立ちます。Claudeが同じ間違いを2回した場合、その修正内容を
CLAUDE.mdに反映します。 - 1ページ以内に収めてください。Claudeはセッション開始時にすべてを読み込むため、古くなった内容は何の利益もなくコンテキストを消費してしまいます。
実例
このCLAUDE.mdは、ある保険会社の顧客ポータルのリポジトリに属しています。請求情報を保持する古い社内システムはclaims-coreであり、intent/には各変更の計画ファイルが保管されています。
CLAUDE.md:
markdown
# Claims portal
## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)
- Run: make run (portal on :3000, claims-api on :8000)
## Conventions
- claims-api is Python 3.12 and FastAPI. portal is TypeScript and React.
- Every endpoint needs a test in claims-api/tests.
- Dates cross the API as ISO 8601, never as formatted text.
## Architecture
- portal/ is the customer site, claims-api/ is its backend, and
intent/ holds the intent.md, spec.md and plan.md for each change.
- Only claims-api talks to claims-core. The portal never calls it.
- claims-core allows 50 requests a second. Cache reads; never poll it.
## Things Claude gets wrong
- Do not log request or response bodies in claims-api; they can hold PII.
- Do not bump dependency versions; the platform team owns them.ガバナンス上の考慮事項
CLAUDE.mdはバージョン管理されているため、エージェントが従う指示はレビュー可能かつ監査可能です。チームの規約はこのファイルを通じて適用され、変更はGitの履歴に記録され、コードオーナーがPRレビューでそれらの変更を承認します。
測定方法
- 先行指標:
CLAUDE.mdが防げたはずの間違いをClaudeが繰り返す頻度。CLAUDE.mdへの修正や変更はGitの履歴内で追跡されるべきです。 - 遅行指標: PR履歴から見た、チームの新メンバーが最初のPRをマージするまでの時間。