CLAUDE.md と AGENTS.md 実践設計術 — AIに伝わるプロジェクト定義の書き方

Claude Code の出力品質は、コードを書く腕前ではなく、CLAUDE.md の品質で決まる。

「AIに任せたら見当違いのコードが出てきた」「何度修正指示を出しても同じミスを繰り返す」——この手の問題の原因は、ほぼ100%がプロジェクト定義の不足にある。Claude Code は優秀だが、超能力者ではない。プロジェクトの文脈を知らなければ「推測」で動くしかなく、推測は外れる。

この記事では、筆者が実際に開発中の recipe-ai（YouTube料理動画からレシピを自動抽出するアプリ）の CLAUDE.md と AGENTS.md の実物を全文公開し、各セクションの設計意図を解説する。

この記事でわかること:

• CLAUDE.md と AGENTS.md の役割の違い
• recipe-ai で実際に使っている CLAUDE.md / AGENTS.md の全文と設計意図
• AIが「迷う」ポイントを事前に潰す具体的テクニック
• モノレポでの階層構造パターン
• やってはいけないアンチパターン

---

CLAUDE.md と AGENTS.md の役割

CLAUDE.md = プロジェクトの「何」を定義する

CLAUDE.md は Claude Code がプロジェクトを理解するための最上位ドキュメントだ。人間でいえば「プロジェクト概要書」に相当する。

含めるべき情報:

• 何を作っているのか（プロジェクトの目的）
• 何を使っているのか（技術スタック）
• どこに何があるのか（ディレクトリ構成）
• 何をしてはいけないのか（制約・ルール）
• 今何をすべきか（フェーズ・スコープ）

AGENTS.md = 「どう実装するか」のガイド

AGENTS.md はより技術的な実装ガイドだ。「この関数を使え」「このパターンで書け」「この落とし穴に気をつけろ」といった、コードを書く際の具体的な指示を記述する。

この2つがないとAIは「推測」で動く

CLAUDE.md も AGENTS.md もないプロジェクトで Claude Code を使うと、こうなる:

• 技術スタックを推測する（Next.js 15 のAPIで書いてしまう）
• ディレクトリ構成を推測する（存在しない場所にファイルを作る）
• 既存ユーティリティを知らない（同じ機能を重複作成する）
• スコープを知らない（Phase 2 の機能を勝手に実装する）

結果、修正指示のやり取りでトークンを浪費する。良い CLAUDE.md を書く時間は、その何倍もの修正時間を節約する。

---

recipe-ai の CLAUDE.md 全文解説

以下が recipe-ai で実際に使っている CLAUDE.md だ。

@AGENTS.md

# recipe-ai (LaunchKit 実証兼用)

YouTube 料理動画の URL からレシピ（材料・手順・コツ）を AI 自動抽出する MVP。
LaunchKit（KOBO）スターターを使った実証案件、Build in Public 素材も兼ねる。

## 技術スタック
- Next.js 16 (App Router) + TypeScript
- Supabase (Auth, DB) — KOBO と同じ Supabase プロジェクト共用 (`amtwwscvhwkfdrqimgqm`)
- Anthropic Claude Haiku 4.5 (`claude-haiku-4-5-20251001`) — レシピ JSON 抽出
- youtubei.js — YouTube 字幕取得（yt-dlp/Python 不要）
- Tailwind v4 + shadcn/ui

## コマンド
- `npm run dev` — 開発サーバー（port 3001、KOBO の 3000 と被らない）
- `npm run build` — 本番ビルド

## ディレクトリ構成
- `app/[locale]/` — i18n（ja のみ）
- `app/api/extract/` — メイン抽出 API
- `lib/youtube.ts` — youtubei.js で字幕取得
- `lib/recipe.ts` — Claude Haiku でレシピ JSON 化
- `lib/anthropic.ts` — Anthropic クライアント
- `types/recipe.ts` — Recipe 型
- `supabase/migrations/` — recipes テーブル定義

## 重要ルール
- **Phase 1 スコープ**: 字幕付き動画限定、認証あり、保存あり、課金なし
- **Phase 2（将来）**: Whisper 音声処理、Stripe 課金プラン
- **角丸禁止・Editorial 系デザイン**（`feedback_no_rounded.md` 準拠）
- 60 分超の動画はエラー
- Next.js 16 の破壊的変更あり、`node_modules/next/dist/docs/` を確認
- Supabase クライアント生成は `lib/supabase/` の既存ユーティリティを使う
- LaunchKit ショーケースとして KOBO の構成を可能な限り流用

## 環境変数
`.env.example` 参照

各セクションの設計意図

1行目: @AGENTS.md

これが最も重要な1行かもしれない。@AGENTS.md と書くことで、Claude Code は AGENTS.md も自動的に読み込む。CLAUDE.md は概要、AGENTS.md は詳細という分離ができる。

プロジェクト説明（冒頭2行）

「何を作っているか」を1-2文で書く。AIは文脈がないと「汎用的な」コードを書きがちなので、「YouTube料理動画のURL」「レシピを自動抽出」という具体的な目的を明示する。

技術スタック

ここでの要点はバージョンとモデル名の明示だ。

• Next.js 16 — 15ではなく16であることを明示。これがないとAIは学習データ上で最も一般的なバージョンのAPIを使う
• claude-haiku-4-5-20251001 — モデルIDを文字列レベルで指定。「Haiku」とだけ書くと古いバージョンを使われる可能性がある
• youtubei.js — yt-dlp/Python不要と補足。これがないとPython依存のソリューションを提案されることがある

コマンド

port 3001、KOBO の 3000 と被らない という補足が地味に重要。モノレポでは複数プロジェクトを同時に開発サーバーで動かすことがあり、ポート衝突はよくあるトラブルだ。

ディレクトリ構成

全ファイルを列挙する必要はない。AIが「どこに書けばいいか」迷いそうなファイルだけ書けばいい。recipe-ai の場合、抽出APIのエントリポイント、YouTubeライブラリ、Anthropicクライアントの場所がわかれば、ほとんどのタスクに対応できる。

重要ルール

ここが CLAUDE.md の核心だ。特に注目すべきポイント:

• Phase 1 / Phase 2 のスコープ定義: これがないと「ついでにStripe課金も実装しておきました」という余計な作業が発生する。Phase 2 は「将来」と明記することで、AIに「今は触るな」と伝える
• 角丸禁止: デザイン上の制約。これを書かないと shadcn/ui のデフォルト（角丸あり）で実装される
• 60分超の動画はエラー: ビジネスロジック上の制約。AIはこうした境界条件を自分では判断できない
• 既存ユーティリティを使え: AIの最も多い失敗は「既存のユーティリティを知らずに同じものを作ること」。明示的に lib/supabase/ を指定する

---

recipe-ai の AGENTS.md 全文解説

AGENTS.md はより技術的で、コードレベルの指示を含む。

<!-- BEGIN:nextjs-agent-rules -->
# This is NOT the Next.js you know

This version (Next.js 16) has breaking changes — APIs, conventions,
and file structure may all differ from your training data. Read the
relevant guide in `node_modules/next/dist/docs/` before writing any
code. Heed deprecation notices.
<!-- END:nextjs-agent-rules -->

# recipe-ai アーキテクチャガイド

LaunchKit（KOBO）スターターをベースにした Dogfooding 兼実証アプリ。
YouTube 料理動画の URL からレシピを抽出。

## Next.js 16 注意点
- **`middleware.ts` は廃止 → `proxy.ts` に名前変更必須**。
  エクスポート関数も `proxy` または `default`
- 詳細: `node_modules/next/dist/docs/01-app/03-api-reference/
  03-file-conventions/proxy.md`

## Supabase クライアント（重要）
新規にクライアントを作成しないこと。以下の既存ユーティリティを使う：

| ファイル | 用途 |
|---------|------|
| `lib/supabase/client.ts` | ブラウザ用 `createClient()` |
| `lib/supabase/server.ts` | サーバー用 `createClient()` |
| `lib/supabase/middleware.ts` | proxy.ts 用（`updateSession`） |

KOBO と同じ Supabase プロジェクト（`amtwwscvhwkfdrqimgqm`）を共用。
`recipes` テーブルだけ追加、RLS で分離。

## Anthropic Claude
- `lib/anthropic.ts` で `getAnthropic()` シングルトン取得
- `RECIPE_MODEL = "claude-haiku-4-5-20251001"` を使う
- prompt caching を有効化（システムプロンプト部分）

## 主要ファイル

| パス | 役割 |
|---|---|
| `app/[locale]/page.tsx` | トップ（Server Component、認証チェック） |
| `app/[locale]/HomeClient.tsx` | フォーム + 結果カードのクライアント側状態 |
| `app/api/extract/route.ts` | メイン抽出 API |
| `lib/youtube.ts` | youtubei.js で字幕取得 + videoId 抽出 |
| `lib/recipe.ts` | Claude Haiku でレシピ JSON 抽出 |
| `lib/anthropic.ts` | Anthropic クライアント |
| `types/recipe.ts` | Recipe 型、API レスポンス型、エラーコード |
| `proxy.ts` | i18n + 認証保護（`/recipes` 以下） |
| `supabase/migrations/001_recipes.sql` | recipes テーブル DDL + RLS |

## デザイン規約
- **角丸禁止**（`memory/feedback_no_rounded.md` 準拠）
- Editorial 系（masatoman.net 方針）
- stone カラーパレット中心
- アクションボタンは黒地白文字（`bg-stone-900`）

## エラーハンドリング
`app/api/extract/route.ts` で全エラーを `ExtractErrorCode` で分類:
- `INVALID_URL` / `VIDEO_NOT_FOUND` / `NO_TRANSCRIPT`
  / `TOO_LONG` / `NOT_RECIPE` / `API_ERROR`

## スコープ
- **Phase 1（現状）**: 字幕付き動画限定、認証あり、保存あり、課金なし
- **Phase 2（将来）**: Whisper 音声処理、Stripe 課金プラン

## 環境変数
`.env.example` 参照。本番は Vercel ダッシュボードで設定。

特に重要なセクション

冒頭の警告ブロック

<!-- BEGIN:nextjs-agent-rules -->
# This is NOT the Next.js you know
<!-- END:nextjs-agent-rules -->

HTMLコメントで囲まれたこのブロックは、AIが最初に目にする「警告」だ。Next.js 16 は学習データにない破壊的変更を含むため、「お前の知識は古い、ドキュメントを読め」と強く伝える必要がある。これがないと middleware.ts を作ろうとする（Next.js 16 では廃止済み）。

Supabase クライアントの表

「新規にクライアントを作成しないこと」という禁止命令と、使うべきファイルの一覧表。AIに「作るな、これを使え」と指示する場合、禁止と代替を同時に示すのが鉄則だ。「作るな」だけだとAIは困る。「作るな、代わりにこれを使え」なら迷わない。

主要ファイルのマップ

CLAUDE.md のディレクトリ構成よりも詳細で、各ファイルの「役割」まで書いてある。これが CLAUDE.md（概要）と AGENTS.md（詳細）の使い分けだ。AIが新しいファイルを作る前に「既存ファイルで対応できないか」を判断するための材料になる。

エラーコードの列挙

ExtractErrorCode のバリエーションを列挙することで、AIが新しいエラーケースを追加する際に既存の命名規則に従える。「API_ERROR」というパターンがあるとわかれば、勝手に「ApiError」や「api-error」といった別命名を使わない。

---

設計のコツ: AIが「迷う」ポイントを先に潰す

1. 破壊的変更は最上位で警告する

AIの学習データは過去のもの。フレームワークの破壊的変更は、AIが最も間違えやすいポイントだ。

recipe-ai の例:

# This is NOT the Next.js you know

**`middleware.ts` は廃止 → `proxy.ts` に名前変更必須**

「何が変わったか」だけでなく、「代わりに何を使うか」まで書く。

2. 「これを使え」「これを作るな」を明示する

AIの失敗パターンで最も多いのが「既存ユーティリティの再発明」だ。

悪い例:

Supabase を使う

良い例:

## Supabase クライアント（重要）
新規にクライアントを作成しないこと。以下の既存ユーティリティを使う：

| ファイル | 用途 |
|---------|------|
| `lib/supabase/client.ts` | ブラウザ用 |
| `lib/supabase/server.ts` | サーバー用 |

3. スコープを Phase で区切る

「今やること」と「将来やること」を明確に分ける。

- **Phase 1 スコープ**: 字幕付き動画限定、認証あり、保存あり、課金なし
- **Phase 2（将来）**: Whisper 音声処理、Stripe 課金プラン

これがないと、AIは「良かれと思って」Phase 2 の機能を先取り実装する。特に課金機能のような複雑な実装を勝手に始められると、スコープが爆発する。

4. デザイン制約は具体値で書く

「シンプルなデザイン」では伝わらない。

- **角丸禁止**
- stone カラーパレット中心
- アクションボタンは黒地白文字（`bg-stone-900`）

CSSクラス名まで指定すれば、AIは迷わない。

---

モノレポでの階層構造

モノレポでは、CLAUDE.md を階層的に配置できる。

monorepo/
  .claude/
    CLAUDE.md          # ルート: 全プロジェクト共通の行動原則
  recipe-ai/
    CLAUDE.md          # プロジェクト固有: スタック、構成、ルール
    AGENTS.md          # 実装詳細: ファイルマップ、パターン
  KOBO/
    CLAUDE.md
    AGENTS.md
  masatoman.net/
    CLAUDE.md
    AGENTS.md

ルート CLAUDE.md の役割

ルートの CLAUDE.md には全プロジェクト共通の行動原則を書く。

recipe-ai のモノレポのルート CLAUDE.md から抜粋:

## 行動原則
- 3ステップ以上のタスクは必ずPlanモードで開始する
- コードを読まずに書かない。探索→絞り込み→実装の順
- 動作を証明できるまでタスクを完了とマークしない
- 最小差分で解決。リファクタ・横展開禁止
- 各サブプロジェクトの `CLAUDE.md` / `AGENTS.md` を必ず参照

「コードを読まずに書かない」「最小差分で解決」といったルールは、どのプロジェクトでも共通だ。これをルートに書いておけば、各プロジェクトの CLAUDE.md で繰り返す必要がない。

@AGENTS.md による参照

各プロジェクトの CLAUDE.md 冒頭に @AGENTS.md と書くことで、AGENTS.md を自動参照させる。CLAUDE.md は「何を」、AGENTS.md は「どうやって」と分離することで、それぞれの文書が短く読みやすくなる。

---

アンチパターン

1. 曖昧な指示

# 悪い例
きれいなUIで作って

# 良い例
- 角丸禁止
- stone カラーパレット中心
- アクションボタンは `bg-stone-900 text-white`

「きれい」の定義はAIと人間で異なる。具体的なCSSクラスまで落とし込む。

2. 制約の欠如

# 悪い例
Supabaseでデータを保存

# 良い例
Supabase クライアントは `lib/supabase/server.ts` の既存
createClient() を使う。新規にクライアントを作成しない。
KOBO と同じプロジェクトを共用、`recipes` テーブルのみ追加。

制約がないと、AIは「一般的に正しい」コードを書く。それはプロジェクト固有の設計とは異なることが多い。

3. スコープ未定義

# 悪い例
YouTube動画からレシピを抽出するアプリ

# 良い例
- Phase 1 スコープ: 字幕付き動画限定、認証あり、保存あり、課金なし
- Phase 2（将来）: Whisper 音声処理、Stripe 課金プラン
- 60分超の動画はエラー

スコープがないと、AIは「完全な」ソリューションを目指す。字幕なし動画への対応、課金システム、管理画面——聞いてもいない機能を「親切心」で実装し始める。

4. バージョン情報の省略

# 悪い例
Next.js + TypeScript

# 良い例
Next.js 16 (App Router) + TypeScript

バージョン番号の省略は、AIに「学習データで最も一般的なバージョン」を使わせることになる。特に破壊的変更があるフレームワークでは致命的だ。

---

まとめ

CLAUDE.md はプロジェクトの「何を・何で・何をしない」を定義し、AGENTS.md は「どう実装するか」の具体的ガイドを提供する。この2つを正しく設計すれば、AIは推測ではなく指示に基づいて動き、修正のやり取りによるトークン浪費を大幅に削減できる。

---

関連記事

Claude Code で 0→MVP を1日で作る全記録

CLAUDE.md設計から始まるMVP構築の全工程

→

【第6回】Claude Code で作る「売れるSaaS」開発フロー

Skills x MCP の統合設計

→

Next.js 16 破壊的変更まとめ

AGENTS.mdで事前に潰した破壊的変更の詳細

→