AGENTS.md、CLAUDE.md、.cursorrules に関するガイドのほとんどは、フォーマットの問題として扱う。どれかひとつ選んで、記入して、コミットする。それで終わり。
その前提が間違っている。しかも、実際の生産性を損なう形で。
ファイル形式は最も重要な決断ではない。重要な決断は「自分のツールチェーンにどれが合うか」「その中に何を書くか」「6ヶ月後にスタックが変わっても正確なままでいられるよう、ルールをどうスコープするか」だ。
このガイドでは入門的な比較は省略する（それは AGENTS.md vs CLAUDE.md: When to Use Which を参照）。ここではユースケース別のテンプレートカタログを掲載する。各テンプレートにはファイル選択の根拠とコピペで使える設定例を付けた。最後にあるセクションでは、よくある落とし穴・複数ファイルの合成・FAQを扱う。
ファイル選択の問題
テンプレートの前に、どのファイルに手を伸ばすかのメンタルモデルを整理しておく。
AGENTS.md を使うべき場面:
- チームが複数のAIツールを併用している（Claude Code + Cursor + Codex CLI + GitHub Copilot など）
- すべてのツールで読まれる単一の情報源を持ちたい
- ルールがプロジェクト全体に適用されるもので、ツール固有のものではない
CLAUDE.md を使うべき場面:
- Claude Code がプライマリツール（あるいは唯一のAIツール）
- ディレクトリ単位のルール階層が必要
@import、パススコープの.claude/rules/、ユーザーレベルのオーバーライドなど Claude 固有機能を使いたい- AGENTS.md に加えて、共有コンテキストの上に Claude 固有の深みを乗せたい
.cursorrules を使うべき場面:
- Cursor がプライマリ IDE で他の AI ツールを使っていない
- 既存の .cursorrules ファイルから移行途中で、まだフォーマット変更の準備ができていない
- 注意: .cursorrules はフラットなファイルで階層がない。プロジェクトが大きくなっていたら
.cursor/rules/*.mdcへの移行を検討する
2026年の多くのチームにとっての実践的な答え:
- リポジトリルートに AGENTS.md（ユニバーサルなコンテキスト、全ツールが読む）
- その上に CLAUDE.md を重ねる（Claude 固有の深みとディレクトリスコープ）
- .cursorrules は Cursor 専用環境でかつ移行していない場合のみ
この前提でテンプレートに進む。
テンプレート 1: ソロ開発者、TypeScript SaaS
プロフィール: 1人開発。フルスタック TypeScript。Next.js フロントエンド、Node/Express か Hono バックエンド、PostgreSQL。Vercel にデプロイ。Claude Code をメインに使い、たまに同じリポジトリを Cursor で開く。
ファイル選択: ルートに AGENTS.md（両ツールが読む）、Claude 固有の追加設定として CLAUDE.md。
なぜ両方？ Claude Code はオペレーション上の詳細（DB コマンド、env セットアップ、テストパターン）を必要とする。Cursor も同じアーキテクチャのルールを知るべき。AGENTS.md が共通部分をカバーし、CLAUDE.md が Claude 固有の挙動（「依存関係をインストールする前に確認する」等）を追加する。
AGENTS.md
# Project: [SaaS 名]
TypeScript SaaS。フロントエンドは Next.js 15（App Router）、バックエンドは Hono、データベースは Drizzle ORM 経由で PostgreSQL。認証は Clerk。デプロイ先はフロントが Vercel、バックエンドが Railway。
## Tech Stack
- Frontend: Next.js 15, TypeScript strict, Tailwind CSS, shadcn/ui
- Backend: Hono on Node.js, Zod でバリデーション, Drizzle ORM
- Database: PostgreSQL (Railway)。ローカル開発は Docker を使用
- Auth: Clerk（JWT ベース、ユーザー同期に Webhooks を使用）
- パッケージマネージャー: pnpm workspaces
## アーキテクチャのルール
- デフォルトは Server Components。インタラクティビティ、ブラウザ API、React フックが必要な場合のみ `'use client'` を追加する。
- ミューテーションは `src/app/actions/` の Server Actions を通じて行う。フロントエンドからのミューテーションに REST エンドポイントを作らない。
- API ボディ・フォームデータ・URL パラメータなど、外部からの入力はすべて Zod スキーマでバリデーションしてからデータベースを操作する。
- 生 SQL は使わない。データベースアクセスはすべて Drizzle クエリビルダーを通じて行う。
- フィーチャーフラグは `src/lib/flags.ts` にある。新しい挙動を追加する前に確認する。
## ファイル規約
- `apps/web/` — Next.js フロントエンド
- `apps/api/` — Hono バックエンド
- `packages/db/` — Drizzle スキーマ・マイグレーション・クライアント
- `packages/types/` — 共有 TypeScript 型
- ファイル名: kebab-case。コンポーネント名: PascalCase。ページとレイアウト以外のデフォルトエクスポート禁止。
- テストはコロケーション: `feature.ts` の隣に `feature.test.ts` を置く。
## コマンド
- `pnpm dev` — 全アプリを開発モードで起動
- `pnpm build` — プロダクションビルド（リポジトリルートから実行）
- `pnpm test` — 全テストを実行（Vitest）
- `pnpm db:generate` — Drizzle マイグレーションを生成
- `pnpm db:migrate` — ローカル DB にマイグレーションを適用
- `pnpm lint` — 全パッケージで ESLint を実行
- `docker compose up -d` — ローカル PostgreSQL を起動
## 環境
- 初回起動前に各アプリで `.env.example` を `.env.local` にコピーする。
- `.env` ファイルはコミットしない。DB の接続 URL は Railway のダッシュボードにある。
- `DATABASE_URL` が設定されていないとバックエンドが起動しない。
## TypeScript のルール
- `any` は禁止。`unknown` を使って型ガードや Zod で絞り込む。
- オブジェクト形状には `type` より `interface` を優先する。
- すべての async 関数はエラーを明示的に処理する（未処理の Promise rejection 禁止）。
- `strictNullChecks` は有効。null/undefined は深いところではなく境界で処理する。CLAUDE.md（Claude 固有の挙動を追加）
# Claude Code 設定
@import AGENTS.md
## 挙動
- 新しい npm パッケージをインストールする前に確認を求める。必要な理由と検討した代替案を明示すること。
- Drizzle スキーマを変更する前に確認を求める。スキーマ変更はマイグレーションが必要で本番を壊す可能性がある。
- 自動コミットしない。変更をステージして、何をしようとしているかを説明する。
- 3ファイル以上の変更が必要なタスクは、開始前に計画を概説する。
## 推奨パターン
- 条件付きクラスには `@/lib/utils` の `cn()` ユーティリティを使う。
- 楽観的 UI 更新には `useOptimistic` を使う（手動ステート管理は不要）。
- エラーバウンダリは `src/app/error.tsx` と `src/app/global-error.tsx` に置く。
- 新しい API エンドポイントには、まず `packages/types/` に Zod スキーマを追加してから実装する。
## テスト
- 新しいユーティリティ関数にはユニットテストが必須。
- Hono エンドポイントの統合テストは `apps/api/test/` に置く。
- 統合テストではデータベースをモックしない。テストコンテナを使う（`docker-compose.test.yml` 参照）。テンプレート 2: OSS ライブラリメンテナー
プロフィール: OSS ライブラリ。複数のコントリビューター。AI ツールは人によってバラバラ。Claude Code 使いもいれば Cursor 使いも Codex CLI 使いもいる。全員に同じツール設定を要求せずに、コントリビューション基準を統一したい。
ファイル選択: AGENTS.md のみ。1ファイル、最大の互換性。
なぜ CLAUDE.md ではないか？ コントリビューターは異なるツールを使う。CLAUDE.md は Claude Code ユーザーにしか機能しない。AGENTS.md は現代の AI エージェントが全員読む唯一のファイルだ。
AGENTS.md
# [ライブラリ名]
[概要説明] のための TypeScript ユーティリティライブラリ。npm で公開。Node 18+、Deno、ESM 経由のブラウザ環境をサポート。
## コントリビューションのルール
- 公開 API は `src/index.ts` にある。Discussions でのプロポーザルなしにこのファイルに追加しない。
- すべての公開関数に JSDoc コメントが必須: 概要、各パラメータの `@param`、`@returns`、1つ以上の `@example`。
- 破壊的変更はコミットボディに BREAKING CHANGE ノートが必要（release-please がメジャーバージョンバンプをトリガー）。
## コード基準
- TypeScript strict モード。`any` も `// @ts-ignore` も禁止。
- 可能な限り純粋関数。副作用はドキュメントに記載する。
- ランタイム依存関係はゼロ。dev dependencies のみ。何かを追加する前に `package.json` を確認する。
- バンドルサイズが重要。新しいエクスポートはバンドルを増やす。ツリーシェイク可能な名前付きエクスポートを優先する。
## テスト
- テストランナー: Vitest
- `pnpm test` — テストを実行
- `pnpm test:coverage` — カバレッジレポート（90%以上を維持すること）
- テストファイルの命名: `feature.ts` の隣に `feature.test.ts`
- 実装ではなく公開された挙動をテストする。テストでプライベート関数をインポートしない。
- 各テストファイルにはモジュール名に対応する `describe` ブロックが必要。
## ビルドとリリース
- `pnpm build` — TypeScript を `dist/` にコンパイル（ESM + CJS デュアル出力）
- `pnpm typecheck` — ファイルを生成せずに TypeScript の型チェック
- `CHANGELOG.md` やバージョン番号を手動で編集しない。release-please が管理する。
- PR タイトルは Conventional Commits に従う: `feat:`、`fix:`、`docs:`、`refactor:`、`test:`、`chore:`。
## やってはいけないこと
- Discussion なしに依存関係（ランタイムまたはピア）を追加しない。
- ビルド設定（`tsup.config.ts`、`tsconfig.json`）を相談なしに変更しない。
- ブラウザ専用 API（`window`、`document`、`localStorage`）を使わない。このライブラリは Node と Deno でも動く。
- 実行順序に依存するテストを書かない。テンプレート 3: エンタープライズ モノレポ
プロフィール: 30以上のパッケージを持つモノレポ。複数チーム。Claude Code に標準化。フロントエンドチームのルールがバックエンドに漏れないよう、またその逆も起きないよう、ディレクトリ別のルールが必要。
ファイル選択: ディレクトリスコープルールを持つ CLAUDE.md。共有コンテキストとしてルートに AGENTS.md。
なぜ CLAUDE.md がディレクトリスコープに必要か？ AGENTS.md はディレクトリレベルのスコープをサポートしない。CLAUDE.md はどのディレクトリにも置くことができ、Claude Code は最も近いものを読む。これがエンタープライズモノレポを管理可能にする鍵となる機能だ。
ルートの AGENTS.md（全ツールが読む）
# モノレポ
Turborepo で管理。30以上のパッケージ。フロントエンド・バックエンド・共有ユーティリティにまたがる。チーム: Platform、Growth、Data、Mobile。
## リポジトリ構造
- `apps/` — デプロイ可能なアプリケーション
- `packages/shared/` — クロスチームの共有ライブラリ
- `packages/ui/` — デザインシステムコンポーネント
- `services/` — バックエンドマイクロサービス
- `infra/` — Terraform と Kubernetes 設定
- `tools/` — ビルドツールとコードジェネレーター
## 全チーム共通ルール
- すべてのパッケージに `README.md` が必要: 目的、オーナーチーム、使用例。
- クロスパッケージの依存関係は適切なパッケージ境界を通じて行う。パッケージディレクトリをまたぐ相対インポート禁止。
- パッケージ管理には `pnpm` のみ使う。`npm install` は使わない。
- 公開パッケージの API を変更する PR を開く前に `pnpm changeset` を実行する。
- CI が通らないとマージできない。テストや型エラーがある状態でマージしない。
## コミット規約
- Conventional Commits 必須: `feat(scope):`、`fix(scope):`、`chore(scope):` 等。
- スコープ = パッケージまたはアプリ名（例: `feat(ui):`、`fix(auth-service):`）ルートの CLAUDE.md
# Claude Code — ルート設定
@import AGENTS.md
## このリポジトリでの挙動
- 変更を提案する前に、自分がどのパッケージにいるかを必ず確認する。パッケージ境界は厳格。
- オーナーチームに確認なしにパッケージ間でコードを移動することを提案しない。
- 新しいファイルを作る前に、ジェネレーターが存在するか確認: `pnpm turbo gen [type]`
- `turbo.json`、`pnpm-workspace.yaml`、その他ルートレベルの設定を変更する前に確認を求める。
## Turbo コマンド
- `pnpm turbo build` — 影響を受けた全パッケージをビルド
- `pnpm turbo test` — 影響を受けた全パッケージをテスト
- `pnpm turbo lint` — 全パッケージをリント
- `pnpm turbo dev --filter=[app-name]` — 単一アプリを開発モードで起動packages/ui/CLAUDE.md（UI パッケージスコープのルール）
# デザインシステムパッケージ
共有 UI コンポーネントライブラリ。全フロントエンドアプリが使用。
## コントリビューションルール
- 新しいコンポーネントには必須: TypeScript props インターフェース、Storybook ストーリー、ユニットテスト、`docs/` のドキュメント。
- アクセシビリティが重要なコンポーネント（ダイアログ、ドロップダウン、ツールチップ）には Radix UI プリミティブを使う。
- コンポーネントはライトモードとダークモードの両方で動作しなければならない。提出前に両方テストする。
- コンポーネントにビジネスロジックを入れない。データフェッチ・API コール・ルーティングはアプリに属し、ここではない。
## コマンド
- `pnpm storybook` — Storybook 開発サーバーを起動
- `pnpm test` — コンポーネントテストを実行
- `pnpm build` — コンポーネントライブラリをビルドテンプレート 4: モバイルチーム（Flutter）
プロフィール: Flutter アプリ。iOS と Android ターゲット。4人チーム。Claude Code と GitHub Copilot を使用。状態管理は Riverpod。バックエンドは Supabase。
ファイル選択: AGENTS.md（Copilot 互換性が必要）+ Flutter 固有の Claude 挙動のために CLAUDE.md。
AGENTS.md
# [アプリ名] — Flutter アプリ
iOS と Android 対応の Flutter アプリ。バックエンド: Supabase（認証・DB・ストレージ）。状態管理: Riverpod 2.x。
## アーキテクチャ
このプロジェクトはフィーチャーファースト型アーキテクチャに従う:
lib/ core/ — アプリ全体のユーティリティ・定数・テーマ features/ auth/ data/ — リポジトリ・API クライアント domain/ — エンティティ・ユースケース presentation/ — 画面・ウィジェット・プロバイダー shared/ — 複数のフィーチャーが使うウィジェットとユーティリティ
- 各フィーチャーは自己完結している。フィーチャー間の通信はドメイン層を通じて行う。
- ウィジェットにビジネスロジックを入れない。ウィジェットはプロバイダーから読み取り、イベントをディスパッチする。
- プロバイダーは `presentation/providers/` に定義する。画面または主要ウィジェットごとに1ファイル。
## コード基準
- `flutter_lints` を強制。コミット前に `flutter analyze` を実行する。
- Null safety 有効。`!` による強制アンラップには、なぜ null が不可能かを説明するコメントが必要。
- 可能な限り `const` コンストラクターを使う。
- ウィジェットファイル: 1ファイルに1ウィジェット。ファイル名はウィジェット名の snake_case。
- ビジネスロジックに `BuildContext` を渡さない。データはパラメーターとして渡す。
## 状態管理（Riverpod）
- 非同期状態には `AsyncNotifierProvider` を優先する。
- 認証状態に依存するプロバイダーは `ref.watch(authProvider)` を使い、未認証状態を処理する。
- ウィジェットの `build` メソッドで `.read()` を呼ばない。`.watch()` を使う。
- ネットワーク呼び出しをするプロバイダーは、ローディング・データ・エラー状態を明示的に処理しなければならない。
## コマンド
- `flutter run` — 接続済みデバイスで実行
- `flutter test` — 全テストを実行
- `flutter analyze` — 静的解析
- `flutter build apk --release` — Android リリースビルド
- `flutter build ipa` — iOS リリースビルド（Mac + Xcode が必要）
- `dart run build_runner build` — コード生成（Freezed、Riverpod アノテーション）
## テスト
- ユースケースとリポジトリのユニットテストは `test/features/[feature]/` に。
- 複雑な UI のウィジェットテストは `test/widget/` に。
- モックには `mocktail` を使う。`mockito` は使わない。
- 視覚的に退行してはいけない UI コンポーネントにはゴールデンテストを使う。テンプレート 5: データ / ML パイプライン
プロフィール: Python ML プロジェクト。データ取り込み・特徴量エンジニアリング・モデル訓練・バッチ推論。データのバージョニングに DVC。全員が Claude Code を使うデータサイエンティスト3人チーム。
ファイル選択: CLAUDE.md のみ。全メンバーが Claude Code を使う。DVC と MLflow は Claude 固有のワークフロー需要がある。
CLAUDE.md
# ML パイプライン — Claude Code 設定
Python ML プロジェクト。DVC でデータバージョニング。実験追跡は MLflow。AWS SageMaker で学習、Lambda で推論。
## 環境セットアップ
- Python 3.11。常にプロジェクトの venv を使う: `source .venv/bin/activate`
- `pip install -e ".[dev]"` で dev 依存関係込みのパッケージを編集可能モードでインストール
- DVC リモートは `.dvc/config` に設定済み。作業前に `dvc pull` でデータファイルを同期する。
- MLflow トラッキングサーバー: `mlflow ui --backend-store-uri sqlite:///mlflow.db`
## テスト
- `make test` — ユニットテストとカバレッジ
- `make lint` — black + ruff
- `make train` — DVC 経由でトレーニングステージを実行
- `make evaluate` — 評価ステージを実行
- `dvc push` — データとモデルアーティファクトをリモートにプッシュ
## データのルール
- 生データは読み取り専用。`data/raw/` 内のファイルは絶対に変更しない。
- すべてのデータ変換は再現可能でなければならない。固定シードなしのランダム操作禁止。
- パイプラインを出るデータは `src/data/schemas.py` の Pandera スキーマでバリデーションしなければならない。
- データファイルは DVC で追跡し、Git ではない。.csv、.parquet、.pkl ファイルを `git add` しない。
## 実験追跡
- すべてのトレーニング実行は MLflow に記録する。必須パラメーター: `model_name`、`dataset_version`、`feature_set`、`random_seed`。
- 該当する場合はチケット番号でタグ付け: `mlflow.set_tag("ticket", "ML-42")`。
- モデルアーティファクトは `mlflow.log_model()` で記録する。手動でモデルを保存しない。
## やってはいけないこと
- `notebooks/` からインポートしない。ノートブックはスクラッチスペース。
- AWS リージョンやバケット名をハードコードしない。環境変数で管理する。
- モデルの重みをコミットしない。DVC アーティファクトとして管理する。
- ログに `print()` を使わない。`src/utils/logging.py` に設定された `logging` モジュールを使う。テンプレート 6: ゲーム開発（Unity）
プロフィール: Unity ゲームプロジェクト。C# スクリプト。モバイルターゲット（iOS/Android）。Claude Code を使う小規模スタジオ。独自の ECS ライクアーキテクチャを使用。
ファイル選択: CLAUDE.md。Unity プロジェクトは実質的に小規模スタジオでは Claude Code 専用セットアップが多い。
CLAUDE.md
# ゲームプロジェクト — Unity
Unity 6（6000.0 LTS）。C# スクリプト。モバイルターゲット: iOS および Android。レンダーパイプライン: URP。
## アーキテクチャ
- **Systems**: `Assets/Scripts/Systems/` の `MonoBehaviour` クラス。毎フレームエンティティを処理する。1クラス1責任。
- **Components**: データのみを持つ純粋な C# クラス（`[System.Serializable]`）。コンポーネントにロジックを入れない。
- **Events**: `Assets/Scripts/Events/` の `ScriptableObject` ベースのイベントチャンネル。システム間の通信は直接参照ではなくイベントを通じて行う。
- **Services**: クロスカッティングな関心事（オーディオ・アナリティクス・セーブデータ）のためのシングルトン。
## C# 規約
- 名前空間: `[Studio].[Module]`（例: `Studio.Combat`、`Studio.UI`）。
- プライベートフィールド: `_camelCase`。パブリックプロパティ: `PascalCase`。
- 明示的に継承が必要でない限り `sealed` クラスをデフォルトとする。
- 初期化後に変更しないフィールドには `readonly` を使う。
- `Update()` の中で `Find()` や `GetComponent()` を呼ばない。`Awake()` か `Start()` でキャッシュする。
## パフォーマンスルール
- ターゲット: iPhone 12 / ミッドレンジ Android で 60fps。最適化の前にプロファイリングする。
- ホットパス（`Update`、物理コールバック）でのアロケーションを避ける。GameObjects は `Assets/Scripts/Pools/` でプールする。
- パブリックフィールドの代わりに `[SerializeField]` プライベートフィールドを使う。Inspector をクリーンに保つ。
## やってはいけないこと
- `Assets/Scripts/Services/` 以外で `DontDestroyOnLoad` を使わない。乱用するとメモリリークになる。
- スクリプトにゲームデータを入れない。データは `Assets/Data/` の `ScriptableObject` アセットに入れる。
- `ScriptableObject` アセットからシーンオブジェクトを参照しない。
- `Invoke()` や `InvokeRepeating()` を使わない。コルーチンか `UpdateService` を使う。テンプレート 7: 静的サイト / マーケティング
プロフィール: Astro 製マーケティングサイト。コンテンツチームが MDX ファイルを編集する。開発者は1人。コンポーネント作業とコンテンツ自動化に Claude Code を使用。
ファイル選択: CLAUDE.md。サイトは Claude Code 専用で、コンテンツチームは AI ツールをリポジトリ上で直接使用しない。
CLAUDE.md
# マーケティングサイト — Astro
Astro 5 サイト。コンテンツは MDX。GitHub Actions 経由で Cloudflare Pages にデプロイ。
## コンテンツ構造
- `src/content/blog/` — ブログ記事（MDX）。フロントマタースキーマ: `src/content.config.ts`。
- `src/content/pages/` — ランディングページ（MDX）。
- `src/components/` — Astro コンポーネントと React アイランド。
- `public/` — 静的アセット。画像は直接配信（最適化パイプラインなし）。
## コンテンツルール
- ブログ記事の必須フロントマター: `title`、`description`、`pubDate`、`draft`、`tags`。
- `draft: true` はプロダクションビルドから記事を除外する。公開準備ができたら `false` に設定する。
- MDX で参照する画像は `public/images/` に存在しなければならない。参照前に確認する。
- MDX に外部画像を含めない（ソースが落ちると壊れる）。ダウンロードして `public/` に追加する。
## コンポーネントパターン
- 静的コンテンツには Astro コンポーネント（`.astro`）。クライアントサイドのインタラクティビティが必要な場合のみ React コンポーネント（`.tsx`）。
- クライアントサイド React: すぐに必要なインタラクティビティには `client:load`、重要でないものには `client:idle`、フォールドより下には `client:visible`。
- スタイリングはすべて Tailwind CSS。コンポーネントに `<style>` ブロックを書かない。
## コマンド
- `pnpm dev` — 開発サーバーを起動（localhost:4321）
- `pnpm build` — `dist/` にプロダクションビルド
- `pnpm preview` — プロダクションビルドをローカルでプレビュー
- `pnpm check` — Astro の型チェック
## デプロイ
- `main` へのプッシュが Cloudflare Pages のデプロイを自動的にトリガーする。
- PR ごとにプレビューデプロイが作成される。
- `dist/` は編集しない。ビルド出力で git ignored。テンプレート 8: バックエンド API（Go）
プロフィール: Go の REST API。PostgreSQL データベース。Docker ベースのローカル開発。チームは Claude Code と Cursor の両方を使用。
ファイル選択: AGENTS.md + CLAUDE.md。ミックス環境には Cursor 互換のために AGENTS.md が必要。Claude Code は CLAUDE.md の追加 Go 固有ルールから恩恵を受ける。
AGENTS.md（抜粋）
# バックエンド API — Go
Go の REST API。pgx ドライバー経由で PostgreSQL。ローカル開発は Docker。GCP Cloud Run にデプロイ。
## アーキテクチャ
レイヤードアーキテクチャ:
- ハンドラーがサービスを呼ぶ。サービスがリポジトリを呼ぶ。レイヤーをスキップしない。
- `service/` に `net/http` のインポートを持ち込まない。サービスは実行中の HTTP サーバーなしでテスト可能でなければならない。
- `handler/` にデータベースのインポートを持ち込まない。データベースは依存性注入の問題。
## コード基準
- `gofmt` と `golangci-lint` 必須。コミット前に `make lint` を実行する。
- エラー処理: 常にエラーをチェックする。明示的なドキュメントなしに `_` でエラーを無視しない。
- コンテキスト伝播: ブロックする可能性のある関数はすべて第1引数として `context.Context` を受け取る。
- グローバルステートを避ける。依存関係は関数引数または構造体フィールドで渡す。
- エクスポートされた型と関数には godoc コメントが必要。
## データベース
- マイグレーションは `db/migrations/` に。`goose` フォーマットで番号付け: `001_create_users.sql`。
- ORM なし。`pgx` で生 SQL。クエリはリポジトリファイルに。
- パラメーター化クエリのみ。ユーザー入力の文字列フォーマット禁止。
## コマンド
- `make dev` — Air でホットリロードしながら API を起動
- `make build` — バイナリをビルド
- `make test` — ユニットテスト
- `make test-integration` — 統合テスト（Docker が必要）
- `make lint` — golangci-lint を実行
- `docker compose up -d` — ローカルで PostgreSQL を起動テンプレート 9: DevOps / インフラストラクチャ
プロフィール: Terraform 設定、Kubernetes マニフェスト、CI/CD パイプラインを管理するインフラチーム。IaC 支援に Claude Code を使用。
ファイル選択: CLAUDE.md。インフラ変更はリスクが高い。CLAUDE.md は一般的な AI には自明でない安全制約を encode する必要がある。
CLAUDE.md
# インフラリポジトリ
本番インフラの Terraform と Kubernetes 設定。AWS + GCP マルチクラウド。環境: dev、staging、production。
## 重要: 安全ルール
変更を提案する前に、それがどの環境に影響するかを特定すること。本番変更には以下が必要:
1. Terraform plan のレビュー（直接 apply は絶対にしない）
2. 別のチームメンバーによるピアレビュー
3. オフピーク時のデプロイウィンドウ（本番は月-金 09:00-17:00 UTC を避ける）
以下を引き起こす変更は絶対に提案しない:
- ビジネス上の理由なしに IAM ロールやポリシーを変更する
- リソースを削除する（代わりに `lifecycle { prevent_destroy = true }` を使う）
- インターネット向けサービスに影響する可能性のあるネットワーキングルールを変更する
- `terraform/environments/production/variables.tf` の最小値以下にクラスターノード数を減らす
## Terraform 規約
- すべてのリソースに `Name` タグと `Environment` タグが必要。
- `variables.tf` でデフォルトのない変数は必須入力。なぜデフォルトがないかをドキュメントに記載する。
- リモートステートは S3（AWS）か GCS（GCP）に。チーム環境でローカルステートの `terraform init` を実行しない。
- コミット前に `terraform fmt` を使う。CI はフォーマットが一貫していないと失敗する。
## Kubernetes 規約
- すべての Deployment にリソースの `requests` と `limits` を設定しなければならない。
- Pod には `readinessProbe` と `livenessProbe` を定義しなければならない。
- シークレットは Kubernetes Secrets か external-secrets-operator（AWS Secrets Manager / GCP Secret Manager から読む）から取得する。ConfigMap やマニフェストにシークレットを入れない。
## コマンド
- `terraform plan -var-file=environments/dev/terraform.tfvars` — dev の plan
- `kubectl kustomize kubernetes/overlays/dev | kubectl apply -f -` — dev オーバーレイを適用
- `make validate` — 全 Terraform モジュールと Kubernetes マニフェストを検証テンプレート 10: クイック PoC / スパイク
プロフィール: 新しいライブラリの探索、統合のプロトタイピング、または実現可能性の調査。タイムボックス制（1〜5日）。捨てるか書き直す予定。
ファイル選択: どちらでもない。または何かが必要なら AGENTS.md のみ。
根拠: PoC コードは本番コードとは異なる制約を持つ。本番グレードのパターンを強制する CLAUDE.md はスピードを落とし、AI と口論することになる。設定ファイルをスキップするか、制約を課さずコンテキストを設定するだけの最小限の AGENTS.md を使う。
AGENTS.md（PoC 用最小版）
# PoC: [探索内容の名前]
タイムボックス制の探索。ゴール: [答えたい具体的な問い]。期限: [日付]。
これは使い捨てコード。優先すること:
1. コード品質より反復速度
2. 本番準備より動作するデモンストレーション
3. アーキテクチャの正確性より学習成果
## 探索内容
[テストしている具体的な統合または機能を説明]
## 既知の制約
- [PoC でも重要な実際の制約 — 例: 「API はレートリミット 10 req/s」]
- [PoC でもスキップできないセキュリティ制約]
## セットアップ
[実行方法]
## 成功基準
[「この PoC は成功した」とはどういう状態か？具体的でテスト可能な成果]テンプレート 11: バックエンド API（Python / FastAPI）
プロフィール: Python FastAPI サービス。非同期。SQLAlchemy async で PostgreSQL。Claude Code と Copilot に分かれたチーム。
ファイル選択: AGENTS.md + CLAUDE.md（Go API と同じ理由）。
AGENTS.md（抜粋）
# API サービス — Python / FastAPI
FastAPI アプリケーション。全体を通じて非同期。SQLAlchemy（async）で PostgreSQL。Pydantic v2 でデータバリデーション。AWS ECS にデプロイ。
## Python 基準
- Python 3.12。すべての関数シグネチャに型ヒント。
- `ruff` でリンティングとフォーマット（black + flake8 の代替）。設定は `pyproject.toml`。
- `mypy` で型チェック。strict モード有効。
- 全体を通じて async 関数。同期的なデータベース呼び出し禁止。リクエストハンドラーに `asyncio.run()` 禁止。
## FastAPI パターン
- ルート関数は薄く: 入力バリデーション、サービス呼び出し、スキーマ返却。
- 依存性注入は `Depends()` で: 認証・データベースセッション・設定。
- すべてのデータベースセッションは `Depends(get_db)` から来る。ルートでセッションを手動作成しない。
- HTTP 例外: `raise HTTPException(status_code=..., detail=...)` を使う。エラーの dict を返さない。
- レスポンスモデルは `models/schemas/` に定義する。ルートから SQLAlchemy モデルを直接返さない。
## コマンド
- `uvicorn src.main:app --reload` — 開発サーバー
- `make test` — テスト
- `make lint` — ruff + mypy
- `alembic upgrade head` — マイグレーションを適用
- `docker compose up -d` — ローカルで PostgreSQL を起動よくある落とし穴
落とし穴1: 検証できないルール
プログラム的に確認できないルールは、AI はプレッシャー下で忘れる。
# 悪い例 — 検証不能
パフォーマンスに注意すること。
# 良い例 — 具体的で確認可能
新しい npm 依存関係を追加する前に `bundlephobia` でパッケージを確認し、バンドルサイズへの影響が 10KB 未満であることを確認する。落とし穴2: コンテキスト・制約・プロセスの混在
AI ツールはファイルを上から下へ読む。コンテキスト（プロジェクトとは何か）は制約（やってはいけないこと）の前に来るべきで、さらにプロセス（どうやるか）の前に来るべきだ。これらを混在させると、AI は間違った情報タイプに間違ったフレームを当てはめる。
# 良い構造
## このプロジェクトについて
[コンテキスト]
## アーキテクチャのルール
[制約]
## 開発ワークフロー
[プロセス]
## コマンド
[リファレンス]落とし穴3: 更新されないファイル
6ヶ月前に書かれた CLAUDE.md がプロジェクトが bun に移行しているのに pnpm と書いていたり、v3 になっているライブラリの v1 に言及していたりすると、積極的に害を与える。AI は古い指示に従って壊れたコードを生成する。
対策: ## Last Updated 行と日付を追加して、月1回のチェックをスケジュールする。設定ファイルをドキュメントと同様に扱う。
落とし穴4: モノレポに対する1ファイル
20以上のパッケージを持つモノレポに1つのルートレベル CLAUDE.md を置くと、大きくなりすぎて使えなくなり、異なるチームの関心事が混在する。テンプレート3のアプローチを使う: ルートに共有コンテキスト、パッケージレベルにチーム固有のルール。
落とし穴5: カスタマイズなしのコピペ
これらのテンプレートは出発点だ。実際のプロジェクトのコマンド・ファイルパス・規約は異なる。プロジェクトで make test を使っているのに pnpm test と書かれたテンプレートに従う AI は混乱したエラーメッセージを出す。ファイルをコミットする前にカスタマイズを行う。
落とし穴6: 理由なしのルール
自明でないルールには AI が理由を理解していると役立つ:
# 悪い例
Prisma は使わない。
# 良い例
Prisma は使わない。このプロジェクトはパフォーマンス上の理由から `pg` で生 SQL を使っている
（Prisma のクエリ生成が特定のアクセスパターンで N+1 問題を引き起こしていた）。
`src/lib/db.ts` のクエリビルダーとパラメーター化クエリを使うこと。理由のあるルールはコンテキストウィンドウの圧縮に対して、単純な命令より生き残りやすい。
複数ファイルの合成
複雑なセットアップ（エンタープライズモノレポ・マルチチーム・混在ツール）には、スケールする合成パターンがある。
レイヤー1: ルートの AGENTS.md
ユニバーサルなコンテキスト。このリポジトリを触るすべての AI ツールが読む。アーキテクチャ・コマンド・ハードな制約に絞った事実のみ。ツール固有の指示はここに入れない。
レイヤー2: ルートの CLAUDE.md
その上に重なる Claude 固有の挙動。重複を避けるために AGENTS.md をインポートする:
@import AGENTS.md
## Claude 固有の設定
[Cursor や Codex では意味をなさない Claude 固有のルール]レイヤー3: ディレクトリレベルの CLAUDE.md
モノレポや、サブディレクトリごとに異なる規約を持つプロジェクト用。Claude Code は最も近い CLAUDE.md を読んでディレクトリツリーを上っていく。各サブ CLAUDE.md は追加的（そのディレクトリ用のルールを追加するだけ）にも、特定の親ルールをオーバーライドする形にもできる。
レイヤー4: .claude/rules/
大きな CLAUDE.md ファイルには、関心事別に分割する:
.claude/
rules/
testing.md
security.md
database.mdCLAUDE.md から参照する:
@import .claude/rules/testing.md
@import .claude/rules/security.md
@import .claude/rules/database.mdFAQ
Q: 3つすべてのファイルが必要ですか？
いいえ。ほとんどのプロジェクトは1〜2つで足りる。チーム全員が Claude Code を使うなら CLAUDE.md だけで十分。ツールが混在しているなら AGENTS.md だけでユースケースの80%をカバーする。3ファイル構成は、ユニバーサルな互換性と Claude 固有の深みの両方が必要な複雑な環境のためだ。
Q: AGENTS.md と CLAUDE.md が矛盾したらどうなりますか？
Claude Code は両方を読み、調整しようとする。実際には、より具体的なルールが優先される。CLAUDE.md に「パッケージをインストールする前に確認する」とあり、AGENTS.md にパッケージインストールについて何も書いていなければ、CLAUDE.md のルールに従う。本当に矛盾している（一方が「X をしろ」、もう一方が「X をするな」）場合、CLAUDE.md の方がツール固有であるため、Claude Code はおそらく CLAUDE.md に従う。AGENTS.md をベースとして扱い、CLAUDE.md を追加的なものとして扱うことで矛盾を避ける。
Q: ファイルはどのくらいの長さにすべきですか？
短い方が良い。すべてをカバーしようとする300行の CLAUDE.md は、重要なルールが埋もれてコンテキストから切り捨てられるために無視される。ほとんどのプロジェクトでは200行以下を目標にする。より大きなセットアップには .claude/rules/ に分割し、現在のタスクに必要なものをインポートする。
Q: CLAUDE.md にシークレットや認証情報を入れていいですか？
いいえ。CLAUDE.md はリポジトリにコミットされる。公開（少なくともリポジトリへのアクセス権を持つ全員がアクセス可能）だ。環境変数の名前と場所を参照し、値は入れない。
Q: CLAUDE.md が大きくなってきた。何を削ればいいかどうやって分かりますか？
「このルールがなかったら AI は間違ったことをするか？」と問う。答えがノーなら（ルールがなくてもその挙動が起きるなら）削除する。ファイルはプロジェクト固有の制約を encode すべきであって、一般的なソフトウェアエンジニアリングの助言ではない。
Q: AI が生成したコードに CLAUDE.md 自体を変更させていいですか？
CLAUDE.md はエンジニアリングドキュメントとして扱い、AI が変更する生きたファイルとしては扱わない。AI に変更を提案させたいなら、差分を出力させて自分で適用する。AI に設定ファイルを自己変更させるパターンは、本番セットアップで微妙なドリフトを引き起こした事例がある。
ここに掲載したテンプレートは、理論的なベストプラクティスではなくスケールで機能するパターンだ。自分のプロジェクトに最も近いものから始め、適用されないものを削除し、チームが実際に使っている規約を追加し、スタックが進化するにつれて数ヶ月ごとに見直す。現在のプロジェクトを正確に反映した設定ファイルは、6ヶ月前にドリフトした包括的なものの10倍の価値がある。