「結局どれを書けばいいんですか」
先週、日本のクライアントとのキックオフでそう聞かれた。「.cursorrules と CLAUDE.md と AGENTS.md、それにこの前 DESIGN.md ってのも出ましたよね」。筆者も最初は迷った。2025年に AGENTS.md が広まり、Claude Skills の流れで SKILL.md が出てきて、2026年4月には Google Labs から DESIGN.md まで出た。3つとも触ってみると、それぞれの役割が驚くほど明確に分かれていることに気づく。本稿は実プロジェクトで 3種を使い分けてハマったポイント・効いたポイントの実装メモだ。
前提・環境
本稿で扱う構成はこれ。中堅 EC サイトのリニューアル現場で実際に走っているもの。
Next.js 14 (App Router) + TypeScript / pnpm monorepo (apps/web, apps/admin, packages/ui)
AI エージェント: Claude Code と Cursor を併用
フロントエンド 8名 + AI エージェントが PR を出すハイブリッド体制
3種の役割分担
まず全体像。実際に分離してみてわかったのは、3種は「何を書くか」より「いつ・誰のために」で分かれているという点だ。
ファイルスコープ主な読者検証手段AGENTS.mdプロジェクト全体のルール全 AI エージェント (常時)暗黙 (規約)SKILL.md再利用可能な単機能trigger 一致時のみfrontmatter スキーマDESIGN.mdデザインシステム仕様UI 生成タスクnpx @google/design.md lint
AGENTS.md は OpenAI・Google・Sourcegraph・Cursor・Factory らが共同で策定し、2025年12月に Linux Foundation へ寄贈された。SKILL.md は Anthropic Claude Skills 文化が起点。DESIGN.md は 2026年4月に Google Labs が公開した一番新しい仕様で、CLI の lint 検証ツールが付属する。
AGENTS.md - 全体ルールの一枚岩
筆者のプロジェクトの AGENTS.md (抜粋) はこんな感じ。
# AGENTS.md
ビルド
パッケージマネージャは pnpm。npm/yarn は使わない
pnpm dev で全 workspace の開発サーバが起動する
テスト
単体テスト: pnpm test --filter @repo/ui
変更したパッケージのみ実行。全部走らせない
コーディング規約
TypeScript strict mode
Server Component ファースト。'use client' は最小限
状態管理は Zustand のみ。Redux/Recoil/Jotai は採用しない
禁止事項
any 型 (やむを得ない場合は eslint-disable + 理由コメント必須)
直接 DB 接続。必ず packages/db 経由
ここで 30分ハマった。最初は「親切に書こう」と思って命名規則や UI ガイドラインまで詰め込んだら、AGENTS.md が 1500行を超えた時点でエージェントの精度が体感で落ちた。長すぎて関連情報を取り出せなくなったように見える。命名規則は SKILL.md に、UI ルールは DESIGN.md に分離してから、AGENTS.md は 250行に圧縮された。短くした方が効いたのだ。
SKILL.md - 発火条件付きの再利用ユニット
SKILL.md の特徴は frontmatter で trigger と参照ファイルを宣言する点にある。
---
name: api-route-generator
description: Next.js App Router の API route を生成。Zod バリデーション + try/catch + ログ込み
trigger: "API ルート|app/api/.*\.ts"
files:
templates/api-route.template.ts
docs/error-codes.md
API Route 生成スキル
このスキルは新規 API route を作る時のみ発火する。
既存 route のリファクタには使わない (それは別スキル refactor-api を呼ぶ)。
テンプレート構造
Zod スキーマ定義
handler 関数 (try/catch + 構造化ログ)
単体テスト雛形 (Vitest)
...
これも罠だった。trigger を当初 "API" 1単語にしたら、ドキュメント本文中の「API 設計について」という見出しでも発火した。「ファイルパスとキーワードの AND 条件」に書き直してから誤発火が止まった。trigger は狭めから始めて、必要に応じて広げる方が安全だ。
DESIGN.md - lint で検証できるデザイン仕様
DESIGN.md の本質は「人が読むデザインドキュメント」と「AI エージェントが参照する制約」を 1ファイルで兼ねる狙いにある。Figma → Storybook → 実装という従来の流れと別経路で、AI への直接の入力として機能する。
# DESIGN.md
Color
color.primary: #2D5BFF
color.semantic.error: #E5484D
color.semantic.success: #30A46C
Typography
font.body: Inter, sans-serif
size.body: 14px / line-height 1.5
Component: Button
variants: primary | secondary | ghost
size: sm (32px) | md (40px) | lg (48px)
必須 props: children, onClick
禁止: inline style での color 上書き
付属 CLI の動作はこんな感じ。
$ npx @google/design.md lint
✓ Color tokens valid (3 defined, 3 used)
✓ Typography tokens valid
✗ packages/ui/src/Button.tsx:42 - hardcoded color #3366FF
→ use color.primary (#2D5BFF) instead
1 error, 0 warnings
ハードコードされた色をエージェントが PR で出してきても CI で落ちる。これが思ったより効く。レビューで毎回「DESIGN_TOKENS.ts のトークン使って」と書いていた手間が消えた。
動作確認
3か月走らせた肌感覚として、PR の差し戻し率が体感で半減した。「またこの規約破られてる」を繰り返すレビューが減った、という方が正確かもしれない。30%減と聞くと小さく聞こえるが、1回 10分かかるレビューが 100件単位で消えると意外と効く。具体的な計測値は社内で集計中だが、感覚は現場のメンバー間で揃っている。
応用・発展
3種の使い分けの発想は Web 以外にも持っていけそうだ。実際に試したわけではないが、考えられる横展開は次のあたり。
データ分析パイプライン: AGENTS.md (依存と実行手順) + SKILL.md (DataFrame 操作テンプレ) + 「DATASET.md」 (スキーマと制約)
モバイルアプリ: AGENTS.md + SKILL.md + DESIGN.md (iOS/Android のトークン分離)
業務システム: AGENTS.md + SKILL.md + 「DOMAIN.md」 (業務ドメイン用語と整合性ルール)
マイグレーション現場: 「MIGRATION.md」 (旧 → 新の対応表 + 禁止パターン)
DESIGN.md を「lint 可能な制約ファイル」と一般化して捉え直すと、自分のドメインで最も誤りが起きやすい領域に同じ発想を適用できる気がする。
まとめ
正直なところ、最初は「ファイルが 3つに増えるなんて面倒」と思っていた。実際に分離すると、それぞれが「いつ・誰のために」を持つので、結果的に各ファイルが短く保たれる。1500行の AGENTS.md より、3つに分かれた合計 1500行の方が AI エージェントの精度も人間のメンテ性も上だった。次はテスト戦略を切り出した「TEST.md」を試してみる予定だ。
筆者は 5years+ で AI/LLM の業務応用を担当している。同じく現場でハマった方の知見、コメントで歓迎。