開発方針を相談する

CLAUDE.md / AGENTS.md に何を書くべきか

AI エージェントに "プロジェクトの地図" を渡すための実践テンプレート。

この記事の結論

「CLAUDE.md / AGENTS.md って、何を書けばいいんですか」

AI コーディングツールをチームに導入するときに、最初にぶつかる質問です。テンプレートが公式にあるわけでもなく、組織ごとに最適解が違うので、最初は手探りになります。

この記事では、min's で実際に運用しているテンプレートを公開しつつ、書くべきこと・書きすぎてはいけないこと・運用しながらの更新方法を整理します。

CLAUDE.md / AGENTS.md とは何か

Anthropic の Claude Code には CLAUDE.md という仕組みがあり、リポジトリに置いておくと Claude の system prompt に自動的に含められる 設計です (Using CLAUDE.md files / Anthropic)。OpenAI の Codex にも AGENTS.md という同じ役割のファイルがあり、グローバル (~/.codex)、プロジェクト (Git ルートから現在のディレクトリ)、サブディレクトリの 3 階層で重なる設計です (Custom instructions with AGENTS.md / OpenAI Developers)。

つまり、これらのファイルは AI に「プロジェクトの地図」を渡す ためのものです。

これらを書いておけば、AI は毎回ゼロから学ばずに作業を始められます。

なぜ 1 つのファイルで済むのか

「README に書けばいいのでは?」と思うかもしれません。違いは 「AI が必ず読む」「人間が読むときには重要ではない情報も入る」 ことです。

README は人間向けに「使い方」「インストール」「ライセンス」を書きます。CLAUDE.md / AGENTS.md は AI 向けに「触る前提」「制約」「規約」を書きます。両方を使い分けるのが現実的です。

書くべき 8 項目

実際に運用しているテンプレートを、項目ごとに紹介します。コード例はサンプルなので、自社プロジェクトに合わせて読み替えてください。

1. プロジェクト概要 (Project Overview)

最初の数行で、プロジェクトの目的を AI に伝えます。

## Project Overview

This is a multi-tenant booking SaaS for hair salons.
- Frontend: Next.js 15 App Router, TypeScript, Tailwind
- Backend: Vercel serverless, Supabase (Postgres + RLS)
- Auth: Clerk
- Payments: Stripe Subscriptions
- Currently in private beta with 5 customers.

「何を作っているか」「主要な技術スタック」「現在のフェーズ」を 1 段落で。事業フェーズ (PoC / MVP / 本番運用) を書いておくと、AI が品質ラインを推測しやすくなります。

2. アーキテクチャ (Architecture)

ディレクトリ構成と、各ディレクトリの責務を明示します。

## Architecture

- `app/` — Next.js routes (Server Components + Server Actions)
- `lib/domain/` — domain models, business rules (pure functions)
- `lib/db/` — Supabase repositories (only place that calls SQL)
- `lib/auth/` — Clerk wrapper (only place that reads session)
- `lib/integrations/` — external SaaS clients (Stripe, SendGrid)
- `components/` — UI components (presentational)

Rule: business logic lives in `lib/domain/`. Routes only call use cases.
Rule: no direct SQL outside `lib/db/`.
Rule: no direct `auth()` calls outside `lib/auth/`.

「ディレクトリの責務」「触っていい / 触ってはいけない境界」をルールとして書きます。

3. コマンド (Commands)

開発・テスト・デプロイで使うコマンドを一覧で。

## Commands

- Development: `pnpm dev`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Test (unit): `pnpm test`
- E2E: `pnpm e2e`
- Build: `pnpm build`
- Migration (new): `pnpm db:migration:new <name>`
- Migration (apply): `pnpm db:migrate`

Before opening a PR, run: typecheck, lint, test.

AI が「PR を出す前に何を実行すべきか」を判断できるよう、「必ず実行すべきコマンドの順序」を明示 します。

4. テスト (Testing)

テスト方針と、AI に守ってほしいルールを書きます。

## Testing

- Unit tests with Vitest, located next to source files (`*.test.ts`).
- E2E tests with Playwright in `e2e/`.
- When adding a new function in `lib/domain/`, add a unit test.
- Tests should cover happy path + at least 2 edge cases.
- For mutations (Server Actions), add integration tests in `lib/integrations/__tests__/`.
- Snapshot tests are discouraged. Prefer explicit assertions.

「どこに、どんなテストを書くか」を明示します。AI はこのルールに従ってテストを自動追加するようになります。

5. コーディング規約 (Coding Rules)

スタイル、命名、責務分割のルール。

## Coding Rules

- TypeScript strict mode. No `any` (use `unknown` + type narrowing).
- Domain functions are pure. Side effects only in `lib/db/`, `lib/integrations/`,
  and route handlers.
- Server Actions for mutations, not API routes (App Router).
- Component file names: kebab-case. Component names: PascalCase.
- Use `zod` for input validation at API boundaries.
- Date handling: `date-fns` only. No `moment`, no native `Date` for arithmetic.
- Use `Result` type for fallible operations, not exceptions.

「文字色やスタイルの好み」より、「設計上の判断」 を中心に書きます。

6. セキュリティ (Security)

セキュリティ上の重要なルール。

## Security

- Always filter by `tenant_id` in repositories. Supabase RLS is the safety net,
  not the primary defense.
- Never log user PII, payment tokens, or Stripe signatures.
- Use `process.env.STRIPE_WEBHOOK_SECRET` for verification. Don't hardcode.
- Permission checks happen at the use case level, not in components.
- No raw SQL strings. Always use parameterized queries via Supabase client.
- Input from external sources (Webhooks, file uploads) must be validated with
  zod before reaching domain code.

セキュリティに関する 「絶対やってはいけないこと」 を明示します。AI への警告線になります。

7. 触らない場所 (Do Not Touch)

AI に触らせたくないファイル / ディレクトリ。

## Do Not Touch

- `supabase/migrations/` — do not edit existing migrations. Add new ones only
  via `pnpm db:migration:new`.
- `.env*` — never commit, never reference values directly.
- `lib/billing/stripe-webhook.ts` — discuss before changing. Idempotency is fragile.
- `lib/auth/clerk-server.ts` — discuss before changing. Auth boundary.
- Anything in `infra/` — infrastructure config, human review required.
- `package.json` "dependencies" — propose, but don't add without review.

「触らない場所」を明示しないと、AI が勝手にマイグレーションを書き換えたり、依存ライブラリを追加したりする事故が起きます。

8. PR チェックリスト (PR Checklist)

PR を出す前に AI が自分で確認することを並べます。

## PR Checklist

Before opening a PR, ensure:
- [ ] `pnpm typecheck` passes
- [ ] `pnpm lint` passes
- [ ] `pnpm test` passes
- [ ] New domain functions have unit tests
- [ ] No new direct DB queries outside `lib/db/`
- [ ] No PII in logs
- [ ] PR description includes a 1-line summary and tested scenarios
- [ ] If changing authentication or billing, request explicit review

このチェックリストは PR テンプレートにも貼り付けて、人間レビュアーと AI で同じ観点を共有します。

ここまでで「自社の CLAUDE.md / AGENTS.md を作りたい」と感じたら、現状のコードベースに合わせてテンプレートをカスタマイズします。

CLAUDE.md / AGENTS.md の整備を相談する →

書きすぎてはいけないこと

OpenAI の Codex ベストプラクティスでは、AGENTS.md が 肥大化したらタスク別ドキュメントへ分ける ことが推奨されています (Codex Best Practices / OpenAI Developers)。Anthropic の CLAUDE.md ファイル解説でも、簡潔で読みやすく保つ ことが推奨されています (Using CLAUDE.md files / Anthropic)。

以下は書かないほうがいい項目です。

書かないもの代わりに置く場所
個別機能の実装詳細docs/features/<name>.md
個別 API の仕様OpenAPI / Swagger、または docs/api/
個別バグの修正履歴PR 履歴と issue で十分
設計の歴史的経緯docs/decisions/ の ADR
全機能のリストREADME で十分
開発環境のセットアップ手順README で十分
ライブラリの選定理由ADR (Architecture Decision Records)

CLAUDE.md / AGENTS.md は、毎回読まれる ので、長すぎると AI のコンテキスト消費が増えます。「全プロジェクト共通で効くルール」だけを残します。

適切なサイズの目安

言語・フレームワーク別の書き方

技術スタックによって、強調すべき項目が変わります。

TypeScript / Next.js プロジェクト

Python / FastAPI プロジェクト

Ruby on Rails プロジェクト

Go プロジェクト

それぞれ書くべき項目は違いますが、「設計判断」「絶対やらないこと」「コマンド」「テスト方針」 という骨格は共通です。

モノレポ・サブディレクトリの扱い

モノレポなどでは、ディレクトリ階層に応じて CLAUDE.md / AGENTS.md を置けます。Codex は親ディレクトリから現ディレクトリまでをマージして読む設計です (Custom instructions with AGENTS.md / OpenAI Developers)。

/AGENTS.md                ← 全体ルール (共通の規約、セキュリティ、コマンド)
/apps/web/AGENTS.md       ← Web 固有のルール (Next.js 固有、UI 規約)
/apps/api/AGENTS.md       ← API 固有のルール (FastAPI 固有、Pydantic)
/packages/shared/AGENTS.md ← 共通ライブラリ固有のルール

下位のファイルが上位の指示を上書き / 追加できる構造なので、領域ごとにルールを分けたいときに便利です。

サブディレクトリ AGENTS.md の例

## apps/api Specific Rules

- All endpoints use Pydantic models for input/output.
- Database access only via `app.db.repositories.*`.
- Async by default. Sync allowed only in CLI scripts.
- Tests in `tests/` mirror the structure of `app/`.

ルートに書くのではなく、ディレクトリ固有のルールはサブディレクトリの AGENTS.md に書く方が、AI のコンテキスト消費を抑えられます。

運用しながら更新する

CLAUDE.md / AGENTS.md は、一度作って終わり ではありません。運用しながら更新していきます。

更新タイミング

更新ワークフロー

  1. レビュー時に「これ、ルールに追記したい」と気づく
  2. その場で 1〜2 行のドラフトをコミットメッセージか PR コメントに残す
  3. 週次の振り返り (15 分) で、追記候補をまとめてレビュー
  4. 合意したものを CLAUDE.md / AGENTS.md にコミット
  5. チーム全員に Slack で通知

更新内容は、1〜2 行の簡潔な指示 に絞ります。長くなりすぎたら、別ファイルに分割します。

陳腐化対策

3〜6 ヶ月に 1 回、全文を読み直して陳腐化した項目を整理します。Anthropic の Claude Code 解説でも、設定は古いモデルに合わせたまま放置すると制約として働いてしまう ため、3〜6 ヶ月に 1 回見直すことが推奨されています (Claude Code docs / Anthropic)。

陳腐化のサイン:

min's での運用例

min's の案件で実際に使っているテンプレートのフルバージョンは、相談時に共有しています。一般的に、以下のサイズで運用しています。

規模行数更新頻度
ルート CLAUDE.md / AGENTS.md200〜400 行月 2〜4 回
サブディレクトリ用30〜100 行月 1〜2 回
四半期に 1 回—全文レビュー

多言語・多技術スタックでの運用

複数言語のリポジトリ (TypeScript + Python など) では、共通ルールをルートに置き、各言語固有のルールをサブディレクトリに置きます。これによって AI が、作業対象のファイルに応じて適切なルールを参照できます。

CLAUDE.md / AGENTS.md の整備を依頼したい方へ

min's では、CLAUDE.md / AGENTS.md のテンプレート整備、既存リポジトリの AI フレンドリー化、運用ルールの設計を支援しています。

以下のような状態であれば、ご相談ください。

次に読む記事

参考

動くデモで終わらせず
本番まで持っていく開発を

AI で作りかけたもの、止まりかけている開発、新しいプロダクトの構想。 まずは現状を整理するところから、ご相談ください。

開発方針を相談する概算見積もりを依頼する