プロジェクトの指示書を手に、AIコーディング支援と協働する様子を描いたイラスト
約 7 分

CLAUDE.mdとAGENTS.mdの書き方｜AIコーディング支援をチームに定着させる

プロジェクトの前提や作業ルールをAIへ渡す際に、書くべきこと・書かないこと・更新の仕方を実務目線で整理します。

CLAUDE.mdとは？AIコーディング支援を“チームの戦力”にする指示書の作り方

Claude Codeを使っていて「同じ説明を毎回している」「プロジェクトの作法を忘れられる」と感じたら、まず整えたいのが CLAUDE.md です。これはAIに渡す、プロジェクト専用の短い引き継ぎメモのようなもの。

結論から言うと、CLAUDE.mdには「毎回守ってほしい、具体的で検証可能な前提」だけを書きます。 長大な仕様書や秘密情報の置き場にはしません。

この記事では、CLAUDE.mdの仕組みと書き方、チーム運用の注意点を整理したうえで、Codexを使う場合の対応ファイル AGENTS.md までつなげて解説します。

CLAUDE.mdは何をするファイル？

CLAUDE.md は、Claude Codeが作業を始める際に読むMarkdown形式の指示ファイルです。コードの置き場所、よく使うコマンド、命名規則、変更時に必ず行う確認などを、会話のたびに説明し直さず共有できます。

たとえば「テストは pnpm test を実行する」「APIの変更では docs/ も更新する」「本番用の環境変数は絶対に出力しない」といった約束です。人間の新メンバー向けREADMEよりも、AIが作業中に判断するための実務ルールに寄せると機能します。

ただし、これは強制的なセキュリティ制御ではありません。Claude Codeの公式ドキュメントでも、CLAUDE.mdは“設定”ではなくコンテキストとして扱われると説明されています。削除禁止やデプロイ禁止のように絶対に止めたい操作は、権限設定やフックなど別の仕組みで守りましょう。

まず押さえるべき配置と効く範囲

Claude Codeでは、作業ディレクトリから上へたどった CLAUDE.md と CLAUDE.local.md が読み込まれます。さらに、作業対象の配下にあるファイルは、そのディレクトリに入った時点で読み込まれます。

  • ~/.claude/CLAUDE.md：個人の全プロジェクト共通の好み
  • リポジトリ直下の CLAUDE.md または .claude/CLAUDE.md：チームで共有する標準ルール
  • サブディレクトリの CLAUDE.md：その領域だけのルール
  • CLAUDE.local.md：個人・ローカル環境だけの情報。Git管理から外す

近い階層の指示ほど、より具体的なルールとして効かせるのがコツです。たとえばルートには全体のテスト方針を書き、apps/admin/CLAUDE.md には管理画面だけの確認手順を書く、と分けます。

CLAUDE.mdに書くべきもの／書かないもの

書くべきもの

  • 開発・テスト・型チェックのコマンド
  • ディレクトリ構成と、責務の境界
  • 命名、フォーマット、エラー処理などの規約
  • 変更に伴う確認事項（テスト、ドキュメント、マイグレーション）
  • 既知の落とし穴と、再発を防ぐ具体策

書かないほうがよいもの

  • APIキー、トークン、顧客情報、接続文字列などの秘密情報
  • すぐ古くなる詳細仕様や、長い設計議論の全文
  • 「いい感じに」「適切に」のように検証できない表現
  • 一度しか使わない作業手順

同じ訂正を2回したら、短く具体化してCLAUDE.mdへ足す。 これは良い更新基準です。一方、特定のパスだけで必要な複雑な手順は、Claude Codeのパス指定ルールや専用スキルに逃がすと、通常の作業コンテキストを圧迫しません。

最小構成のCLAUDE.md例

次の程度から始めるのが扱いやすいでしょう。実際のコマンドやパスは、必ず自分のリポジトリに合わせて置き換えてください。

# プロジェクト概要
- Webアプリ本体は `apps/web/`、APIは `apps/api/`。
- パッケージ管理は pnpm を使う。

# 作業ルール
- JavaScript/TypeScriptを変更したら `pnpm test` と `pnpm lint` を実行する。
- APIの公開仕様を変えたら `docs/api.md` を更新する。
- 新しい本番依存を追加する前に、理由と代替案を提示する。

# 禁止・注意
- `.env` の中身を表示・コミットしない。
- DBスキーマ変更にはロールバック手順を添える。

ポイントは、命令を増やすことではなく、AIが迷いやすい判断を減らすことです。「何を」「いつ」「どう確認するか」が一行でわかる記述を目指します。

CLAUDE.md、README、ルール、Auto memoryの使い分け

似た情報をあちこちに書くと、やがて食い違います。役割を分けておくと保守しやすくなります。

  • README.md：人間も読む、プロジェクトの概要・導入手順
  • CLAUDE.md：AIが毎回の作業で守る実行ルール
  • .claude/rules/：対象パスやファイル種類を限定したルール
  • Auto memory：Claude Codeが訂正や学びから自動で残すメモ

Claude CodeにはAuto memoryもありますが、チームで合意したルールを任せきりにするのはおすすめしません。共有したいルールはレビュー可能なCLAUDE.mdに置き、個人の学びはAuto memoryやローカルファイルへ、と分けると透明性が保てます。

Codexの場合はどうなる？対応するのはAGENTS.md

Codexで同じ役割を担うのは、原則として AGENTS.md です。名前は違っても、目的はほぼ同じ。AIにプロジェクトの「前提」「守ること」「確認方法」を伝えるためのMarkdownファイルです。

Codexは起動時に、グローバル設定とプロジェクト内の指示ファイルを連結して読みます。探索順は次のとおりです。

  • グローバル：~/.codex/AGENTS.override.md があればそれを、なければ ~/.codex/AGENTS.md
  • プロジェクト：リポジトリのルートから現在の作業ディレクトリまで、各階層で AGENTS.override.md、次に AGENTS.md を探す
  • 同じ階層に両方ある場合：AGENTS.override.md が優先される
  • より深い階層の内容：後ろに連結されるため、より広い階層の指示より優先される

Codexはデフォルトで、プロジェクト指示の合計を32KiBまで読み込みます。大きな文書を1枚に詰め込むより、ルートには全体ルール、必要なサブディレクトリには局所ルール、と分けたほうが安全です。設定で代替ファイル名や上限を調整することもできます。

Codex用AGENTS.mdの最小例

# リポジトリの約束
- 依存関係の追加には pnpm を使う。
- TypeScriptを変更したら `pnpm test` と `pnpm lint` を実行する。
- 公開APIを変更したら `docs/api.md` を更新する。

# 安全性
- `.env`、トークン、顧客データを出力・コミットしない。
- 破壊的なDB操作やデプロイの前に、対象と影響を確認する。

Claude CodeとCodexを併用するなら、ルールを二重管理しないのが大事です。Claude Codeは AGENTS.md を自動では読まないため、既存のAGENTS.mdを使いたい場合は、リポジトリ直下の CLAUDE.md に @AGENTS.md と書いて読み込ませる方法があります。Claude固有の指示はその下に追加できます。

@AGENTS.md

# Claude Codeだけの補足
- `src/billing/` の変更は、まず計画を示してから実装する。

反対にCodexが CLAUDE.md を標準で探索するわけではありません。共通ルールは AGENTS.md を正本にし、Claude向けに CLAUDE.md から読み込む構成が、両方を使うチームではわかりやすい選択肢です。

導入を失敗させない3つの運用ルール

  1. 最初は20〜40行程度で始める：Claude Codeの公式ガイドは1ファイル200行未満を目安にしています。短いほど、重要なルールを見失いにくくなります。
  2. PRと同じようにレビューする：指示変更はAIの振る舞いを変えます。なぜ必要か、どの場面で効くかをレビュー対象にします。
  3. 定期的に削る：すでに自動化した確認、守られない曖昧な規則、古いコマンドは削除または置換します。矛盾した指示は、AIにも人にも事故のもとです。

今日の一歩：まず“同じ説明”を3つだけ書き出す

いきなり完璧なルール集を作る必要はありません。直近のAIとの作業を振り返り、繰り返し伝えたことを3つだけ選びましょう。たとえば「使うパッケージマネージャ」「必ず回すテスト」「触れてはいけない秘密情報」です。

それをリポジトリ直下の CLAUDE.md（Codex中心なら AGENTS.md）に、具体的な一文で置く。次の作業で役立ったかを見て、少しずつ育てる。この小さな反復が、AIコーディング支援を“毎回説明が必要な便利ツール”から“チームの文脈を知る相棒”へ変えていきます。

参照した一次情報

この記事で追加した実務メモ

この記事は、指示書を長くすることではなく、AIと人が同じ前提で作業できる状態を作る観点から更新しました。秘密情報や一時的な指示を混ぜないことも大切です。

まずは「プロジェクトの目的」「確認が必要な操作」「テスト方法」の3項目だけを書き、実作業で困った点を足していきましょう。

あわせて読みたい