AGENTS.md / CLAUDE.md 設計レシピ集

コース構成

このコースで学ぶこと

1. 01

   AGENTS.md と CLAUDE.md の違いを 1 枚で

   Claude Code が自動で読み込むのは CLAUDE.md。AGENTS.md は『どんな AI でも従ってほしい共通ルール』を置く中立的な慣習で、CLAUDE.md から `@AGENTS.md` で取り込むのが定石。内容のレイヤリングを設計すると“迷子の Claude”がいなくなる。

   AGENTS.md は中立的なエージェント向け規約として OSS 界隈で広まった慣習。Claude Code 自体は AGENTS.md を直接ロードしないが、CLAUDE.md に `@AGENTS.md` と 1 行書けば再帰的に取り込まれる。これにより同じプロジェクトを Cursor や他の AI ツールで開いても、共通ルールは一元管理できる。

   • CLAUDE.md: Claude Code が起動時に自動ロード（プロジェクト直下）
   • AGENTS.md: 中立的ルールを置く慣習。`@AGENTS.md` 経由でロード
   • 用途分担: AGENTS.md = 言語仕様・規約、CLAUDE.md = Claude 固有の挙動
   • @filename で他ファイルを取り込み可能（再帰展開される）

   理解度チェック

   1. Q1.Claude Code が起動時に“自動でロードする”のはどちらのファイル？

      AAGENTS.md（Claude Code 専用）BCLAUDE.md（プロジェクト直下のもの）CREADME.md（全プロジェクト共通）Dpackage.json（Node 系プロジェクトのみ）
   “やってほしくないこと”を 1 行で書く
2. 02

   “やってほしくないこと”を 1 行で書く

   Claude は読みやすい禁止条項に強い。〜しない、〜は使わない、と明示的に書くことで誤動作が激減する。

   • 「黙ってファイルを作らない」
   • 「console.log は残さない」
   • 「未使用 import は削除する」
   • 「コミットは作らない（ユーザー指示時のみ）」

   markdown

   ## NEVER
   - Do not run `git push --force` without explicit confirmation
   - Do not create new files unless asked
   - Do not change package.json scripts without confirmation

   理解度チェック

   1. Q1.禁止事項を CLAUDE.md / AGENTS.md に書くときの効きやすい書き方は？

      A「気をつけて」のような曖昧な表現B“NEVER” セクションに `Do not 〜` 形式で 1 行ずつ列挙Cストーリー仕立てでなぜダメかを長く書くDコードコメントだけに書く
   AGENTS.md と CLAUDE.md の違いを 1 枚でプロジェクト固有のディレクトリ地図を渡す
3. 03

   プロジェクト固有のディレクトリ地図を渡す

   ファイル構造を 20 行以内で説明するだけで、grep の精度と速度が大幅に上がる。Claude にとってのオリエンテーション資料になる。

   markdown

   ## Directory Map
   - src/app/        Next.js App Router pages
   - src/lib/        Pure utilities (no React)
   - src/components/ Reusable UI components
   - tests/          Vitest unit tests
   - e2e/            Playwright e2e

   手を動かす

   0 / 3

   • 各ディレクトリの 1 行説明を書いた
   • import の禁止・推奨方向を書いた（例: components → lib OK / lib → components NG）
   • テストファイルの置き場所を明示した

   理解度チェック

   1. Q1.AGENTS.md にディレクトリ地図を書く副次的なメリットとして正しいのは？

      AClaude のレスポンス速度自体が物理的に倍になるBgrep / glob の精度が上がり、Claude が当てずっぽうで全 src/ を漁る無駄が減るCTypeScript の型推論が強化されるD.gitignore が不要になる
   “やってほしくないこと”を 1 行で書く“決定済み事項” と “未決事項” を分ける
4. 04

   “決定済み事項” と “未決事項” を分ける

   決定済みのアーキ判断（ライブラリ採用、命名規約）と、まだ揺れている事項を Claude に区別させると、勝手なリファクタを抑制できる。

   ## Decisions（決定済み）と ## Open Questions（未決事項）の 2 セクションに分けて書く。Claude は未決事項に触る前にユーザーに確認するようになる。

   • 決定: Tailwind v4 / framer-motion / vitest を使用
   • 決定: API レスポンスは snake_case で返す
   • 未決: 国際化（i18n）の導入時期
   • 未決: 認証は NextAuth か自前か

   理解度チェック

   1. Q1.AGENTS.md に「Decisions」と「Open Questions」を分けて書く効果は？

      A未決事項を Claude が勝手にリファクタしてしまうB未決事項に触る前に Claude がユーザーに確認を取りやすくなるC決定事項を Claude が無視するようになるDファイルの行数が必ず短くなる
   プロジェクト固有のディレクトリ地図を渡すSkill 化と社内テンプレ配布
5. 05

   Skill 化と社内テンプレ配布

   良い AGENTS.md ができたら社内テンプレ化して配布する。新規プロジェクト立ち上げの 30 分を 3 分に短縮できる。

   手を動かす

   0 / 4

   • テンプレ AGENTS.md / CLAUDE.md を Skill 化（plugin に同梱）
   • プロジェクト種別ごと（Next.js / FastAPI / Rails）にバリエーション
   • “最初に書き換える 5 項目”を冒頭に TODO コメントで明示
   • Skill 説明に「新規 Next.js プロジェクトの初期化時に使う」と書く

   Lv.3 — 記憶 (memory)

   理解度チェック

   1. Q1.新規プロジェクトの AGENTS.md テンプレを Skill に同梱するとき、冒頭に必ず書くべきは？

      A全ての社内ルールを 1 行で要約した文B“最初に書き換える 5 項目”の TODO コメントCSkill 自体の利用回数カウンタDプロジェクトの最終 commit ハッシュ
   “決定済み事項” と “未決事項” を分ける