CLAUDE.mdの役割

概要

CLAUDE.mdは、Claude Codeがプロジェクト作業を開始するときに参照するメモリファイルである。リポジトリの目的、主要コマンド、コーディング規則、テスト手順、修正してはいけない領域など、毎回プロンプトに繰り返し書きにくい情報を文書として残す。

Claude Codeはコードベースを読んで現在の状態を把握できるが、チームの暗黙の規則や運用上の制約までは自動的には分からない。CLAUDE.mdはその背景知識を明示的に提供し、回答と作業方式の一貫性を高める。

CLAUDE.mdが必要な場合

ビルド、lint、テスト、ローカル実行コマンドが決まっている場合、特定ディレクトリを承認なしに修正してはいけない場合、新規パッケージ追加、DBマイグレーション、APIスキーマ変更に別手順がある場合、または機密情報や.envの扱いに規則がある場合はCLAUDE.mdを置くとよい。

複数人が同じリポジトリでClaude Codeを使うなら、チーム共通規則は個人プロンプトではなくリポジトリのCLAUDE.mdに残すほうが安全である。

メモリファイルの種類

実務では、チーム規則は./CLAUDE.mdに置き、個人の好みは~/.claude/CLAUDE.mdや個人用importファイルに分けるのが適切である。

ロード方式と優先順位

Claude Codeは開始時にメモリファイルをコンテキストとして読み込む。現在の作業ディレクトリから上位ディレクトリへたどり、見つかったCLAUDE.mdも参照できる。大規模モノレポではルートに共通規則を置き、サービス配下により具体的な規則を置ける。

repo/
  CLAUDE.md
  services/
    api/
      CLAUDE.md
    web/
      CLAUDE.md

ただし規則を過度に分割すると、どの指示が適用されているか追跡しにくい。共通規則と例外規則を明確に分ける必要がある。

作成方法

Claude Codeでは/initコマンドでプロジェクト用CLAUDE.mdの草案を作成できる。

/init

草案を作った後は、実際のプロジェクトに合わせて必ず修正する。README、パッケージ設定、ビルド設定、テスト設定を確認せずに作ったコマンドは誤った自動化につながる。

基本テンプレート

# Project Instructions

## Project Overview

- This repository is a [service/library/site] for [target users].
- Main stack: [language/framework/runtime].
- Application code lives in `[path]`.
- Tests live in `[path]`.

## Common Commands

- Install dependencies: `[command]`
- Run locally: `[command]`
- Lint: `[command]`
- Type check: `[command]`
- Unit test: `[command]`
- Build: `[command]`

## Working Rules

- Keep changes scoped to the requested task.
- Do not modify `[path]` without explicit approval.
- Do not add dependencies unless the task requires it.
- After code changes, run the smallest relevant verification command first.

良い規則と悪い規則

CLAUDE.mdの品質は文章量ではなく具体性で決まる。「きれいに書く」「テストをしっかりする」「セキュリティに注意する」だけでは実行基準がない。命令、パス、条件を一緒に書く必要がある。

- React共通コンポーネントは`src/components`に置く。
- APIルーターを変更した後は`npm run test:api`を実行する。
- `.env`、`.env.*`、`secrets/`、`credentials/`配下のファイルは読んだり出力したりしない。

importの活用

CLAUDE.mdは@path/to/file形式で他のファイルを取り込める。長い説明をすべてメモリファイルに貼り付けるより、必要な文書を参照するよう分けるとコンテキスト管理がしやすい。

チーム運用

チームでCLAUDE.mdを使うときは文書をコードのように管理する。ビルド、テスト、デプロイコマンドが変わったら同じpull requestでCLAUDE.mdも修正する。個人の好みはプロジェクトメモリに入れず、禁止規則には理由と範囲を添える。

点検チェックリスト

• プロジェクト目的と主要フォルダ構造が書かれている。
• インストール、実行、テスト、ビルドコマンドが実在する。
• 修正禁止ファイルと承認が必要な作業が具体的である。
• 機密ファイルを読んだり出力したりしない規則がある。
• チーム共通規則と個人の好みが分離されている。
• 抽象表現より命令、パス、条件が多い。

まとめ

CLAUDE.mdはClaude Codeにプロジェクトの作業規則を知らせる運用文書である。良いCLAUDE.mdは長い説明書ではなく、Claude Codeがすぐ適用できる具体的な命令と制約の集合に近い。