Lecture 18AGENTS.mdとCLAUDE.mdの役割
AIにプロジェクトの前提やルールを伝えるAGENTS.mdとCLAUDE.mdの重要性を理解します。
AGENTS.mdとCLAUDE.mdは、AIに渡すプロジェクトの利用ルールです。 料理店でいえば「この店のレシピ」「接客の決まり」「使ってよい道具」をまとめた紙に近いものです。
CodexやClaude CodeのようなAIコーディングツールは、何も言わなくてもコードを書けます。 しかし、プロジェクトごとの約束を知らないまま動くと、古い書き方を使ったり、触ってほしくない場所を変更したりします。 そこで、最初に読ませるルールとしてAGENTS.mdとCLAUDE.mdを置きます。
1AGENTS.mdはAI向けの共通ルールブック
AGENTS.mdには、AIが作業前に読むべき前提を書きます。 人間向けのREADMEが「このプロジェクトの説明書」だとすると、AGENTS.mdはAI作業者向けの作業ルールです。
- 使っている技術やバージョンを伝える。
- コードを書く前に読むべき公式Docsや設計資料を伝える。
- 触ってよい場所、避けるべき作業、確認方法を伝える。
- 文章のトーンやUIの方針など、プロジェクト固有の約束を伝える。
この講座アプリなら、「講義本文はTSXに直接書く」「本文は非エンジニア向けに書き直す」 「Tailwindのユーティリティクラスでスタイルを書く」といったルールがそれに当たります。
2CLAUDE.mdはClaude Code向けの入口
CLAUDE.mdは、Claude Codeが読みやすい入口として使われます。 よくある構成では、CLAUDE.mdの中に@AGENTS.mdと書き、AGENTS.mdの内容を読み込ませるようにします。
同じルールを二重管理しない
AGENTS.mdとCLAUDE.mdに同じ文章を別々に書くと、片方だけ古くなることがあります。 まずはAGENTS.mdを本体にして、CLAUDE.mdから参照する形にすると管理しやすくなります。
つまり、AGENTS.mdは「共通のルールブック」、 CLAUDE.mdは「Claude Codeにも同じルールを読ませるための案内板」と考えればOKです。
3なぜNext.jsでは特に重要なのか
Next.jsのような開発ツールは、バージョンによって書き方が変わります。 AIが古い知識だけで作業すると、今のプロジェクトでは使えないAPIや古いファイル構成を提案することがあります。
Next.js 16では、インストールされたパッケージ内にそのバージョンに合ったDocsが入っています。 AGENTS.mdで「コードを書く前にnode_modules/next/dist/docs/を読む」と指定しておけば、 AIはネット検索や古い記憶だけに頼らず、今入っているNext.jsに合う情報を確認できます。
4何を書けばよいか
最初から完璧なルールを書く必要はありません。 AIが迷いやすいこと、毎回説明していること、間違えると困ることから書けば十分です。
- このプロジェクトで使う技術と、必ず読む資料を書く。
- ディレクトリ構成と、本文や画像を置く場所を書く。
- スタイル、文章トーン、命名などの約束を書く。
- やってほしくないことを書く。
- 作業後に実行してほしい確認を書く。
AIに作らせてもよい
既存プロジェクトなら、Codexに「このリポジトリを読んで、AGENTS.mdに書くべきルール案を作ってください」と頼めます。 その後、人間が読んで、過剰なルールや間違いを削れば始められます。
5参考リンク
- Next.js Docs: AI Coding AgentsNext.js公式のAI coding agents向けガイド。AGENTS.mdとCLAUDE.mdの基本構成を確認できます。
- Claude Code DocsClaude Codeの公式Docs。CLAUDE.mdを使う文脈を確認するときに見ます。
自分のプロジェクト用ルールを3つ書く
Codexに「このプロジェクトのAGENTS.mdを読み、重要なルールを3つに要約してください」と依頼してみましょう。 次に、自分が今後AIに守ってほしいルールを1つ追加するなら何かを考えてみましょう。
6理解確認チェックリスト
- AGENTS.mdはAI向けの共通ルールブックだと説明できる。
- CLAUDE.mdはClaude Codeに同じルールを読ませる入口だと理解している。
- Next.jsでは、バージョンに合ったDocsをAIに読ませることが重要だと説明できる。
- 毎回説明している前提をAGENTS.mdに移す判断ができる。