2026年4月、Google Labsが DESIGN.md という仕様を公開しました。AIエージェントが読めるデザインシステムの仕様で、npx @google/design.md lint というCLI検証ツールがセットになっています。
DESIGN.md の登場で、AIエージェントに渡す指示書ファイルが3種類目に揃いました。2025年から業界標準として広がってきた AGENTS.md（OpenAI・Google・Sourcegraph・Cursor・Factoryらが共同で策定、2025年12月にLinux Foundationへ寄贈）、Anthropic Claude Skillsの中核となる SKILL.md、そしてこの DESIGN.md です。それぞれが扱う対象は重なっていません。
本記事の対象読者は、Claude Code・Cursor・Codexのようなコーディングエージェントを業務に組み込んでいる開発者と、CLAUDE.md やスタイルガイドのような自然言語の指示書を運用しているチームリードを想定しています。仕様駆動開発（Spec-Driven Development、以下SDD）の文脈で開発しているチームにも届くはずです。
これから整理するのは、AIに渡す指示書が動き方・個別タスク・見た目の3層に分かれ始めている構造と、それがSDDという別の流れとどう接続するか、という二点です。
これまでの型: 自然言語ドキュメント
ChatGPTが出てから数年、エンジニアの多くは何らかの形で「AIに守らせたいルール」をMarkdownファイルに書いてきました。CLAUDE.md、styleguide.md、CONTRIBUTING.md、社内のコーディング規約。書く場所は違っても、形式はおおむね同じく、構造化されていない自然言語です。
私がここ数ヶ月で書きためてきた writing-style-guide.md もこの典型と言えます。Zenn記事の執筆をClaudeと進めるにあたり、AI生成テキストに残りがちなクセを禁止表現として書きためてきたファイルです。Claude Desktopに毎セッションで読ませることで、出てくる文章のトーンが揃うようになりました。前回の記事「Markdownだけで作るハーネスエンジニアリング」で書いた、業務エージェントのハーネスとして使っている個人リポジトリの一部にあたります。
このファイルには、emダッシュ「——」を使わない、「〜してみましょう！」のような呼びかけを避ける、「興味深かったのは」のような前振りを削る、といったルールが150行ほど書かれています。同じリポジトリの agents/ 配下には、組織別・ロール別に15本ほどの指示書ファイルが並んでいます。executive-assistant.md、sre-support.md、qa-support.md、accounting.md。それぞれが「このロールで動くときの前提」を自然言語で書いています。
このやり方には、はっきりした効果があります。文体・スタンス・暗黙のルールを明文化できる。チームに共有して新しいメンバーが入ったときも、ファイルを読んでもらえれば期待値が伝わる。CLAUDE.md ならClaude Codeが毎セッションで読み込むので、人格的な指示が一貫して届きます。
ただし、限界もあります。一つ目は検証が人間任せになる点です。書いてあるルールが守られたかどうかを、レビュー時に人間が読んで判断するしかない。二つ目は属人性が残る点です。「丁寧に書く」と書いても、丁寧さの基準がレビュアーによってブレてしまいます。
三つ目の限界が、本記事で本題になる部分です。形式的に検証可能なルール（禁止表現の混入、emダッシュの使用、特定パターンの一致）と、判断系のルール（文体のトーン、構造の妥当性、共感ベースの入り方）が同じファイルに混在しているため、検証可能なものまで人間レビューに頼ってしまう。これがこのあと整理する三つの新しいファイル形式が解決しようとしている問題です。
新しい型 1: DESIGN.md（Google Labs）が示す、見た目の仕様化
2026年4月、Google Labsが google-labs-code/design.md というリポジトリで DESIGN.md の仕様を公開しました。スター数は5月初旬時点で11,000超。Google Stitch（stitch.withgoogle.com）というAIによるUI生成プロダクトのリファレンス実装にあたるものです。
仕様ドキュメントはStitch側にあります。
DESIGN.md が扱うのは、デザインシステムの仕様です。ファイル先頭のYAMLに機械可読なデザイントークン（色、タイポグラフィ、スペーシング、コンポーネント）を書き、その下のMarkdown本文に人間可読な設計意図を書く。両者が同じファイルに同居します。
---
name: Heritage
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
---
## Overview
Architectural Minimalism meets Journalistic Gravitas.
## Colors
- Primary (#1A1C1E): Deep ink for headlines and core text.
- Tertiary (#B8422E): "Boston Clay", the sole driver for interaction.
このフォーマットの目玉は、CLIでの検証ツールがセットになっていることです。
npx @google/design.md lint DESIGN.md
トークン参照の整合性、WCAGコントラスト比、構造規約の遵守を検証して、JSON形式で結果を返します。CIに組み込めばPRごとにデザインシステムの整合性をチェックできる形です。diff コマンドもあり、二つの DESIGN.md を比較してtoken-levelの変更を構造化して返します。デザインシステムのバージョン管理という、これまで属人的だった領域に検証可能性が入ります。
日本語UIに関しては、Google Labs本家のサンプルだけでは不足します。日本語特有のタイポグラフィ要件（CJKフォントフォールバック、行高、letter-spacing、禁則処理、混植）が定義されていないためです。これを補うのが kzhrknt/awesome-design-md-jp で、Apple Japan・SmartHR・freee・note・MUJI・メルカリ・LINE・Toyotaなど10以上の日本サービスを対象に、日本語UIに対応した DESIGN.md が公開されています。日本語のプロダクトに適用するなら、本家と日本版を併用するのが現実的かもしれません。
DESIGN.md が担うのは、これまでFigmaファイルやスタイルガイドPDFに散らばっていたデザインシステムを、機械可読かつ人間可読のハイブリッド形式で一つのファイルに集約することです。AIエージェントがUIを生成するときの「毎回ぶれない見た目」を支える仕様基盤、と位置付けるとよさそうです。
新しい型 2: SKILL.md（Anthropic）とAGENTS.mdが担う、動き方の仕様化
DESIGN.md が「見た目」を担うのに対して、SKILL.md と AGENTS.md 系列が担うのは「動き方」です。エージェントが何をしようとし、どんな手順で動き、何をしてはいけないかを定義する領域になります。
SKILL.md はagentskills.ioが標準化したAgent Skillsオープン標準のファイル形式です。AnthropicのClaude Skillsはこの標準の実装の一つで、同じ SKILL.md をClaude Code・Claude.ai・Agent SDKのいずれからも参照できます。標準準拠なので、OpenClawやHermesといった他社のエージェントからも同じファイルが読めます。ファイル先頭のYAMLでメタデータ（スキル名・用途・許可ツール）を宣言し、その下のMarkdown本文にタスクの手順や専門知識を書く構造です。
SKILL.md の具体例としてわかりやすいのが conorbronsdon/avoid-ai-writing です。英語のAI生成テキストに残るパターン（「Moreover」のような接続表現、「watershed moment」のような誇張、「serves as」のような持って回った動詞表現）を検出して書き直す、英語専用スキルです。100語超の置換テーブルが3層（Tier 1は常に置き換え、Tier 2は同じ段落内で2語以上が出現したときflag、Tier 3は高密度のときのみflag）で組まれ、36のパターンカテゴリで監査します。detect モードと rewrite モードがあり、目的に応じて使い分けられます。
ワンショットのプロンプトと違うのは、構造化された監査結果が返ってくるところです。rewrite モードでは、識別された問題、書き直し版、変更サマリ、二回目の監査結果が四つの独立したセクションで返ってくる。「何が変わったか」「なぜ変えたか」が透明になります。
AGENTS.md は、エージェント全体の動き方を扱います。プロジェクトの前提、ロール、禁止事項、エスカレーションのルール。冒頭で触れたとおりSourcegraphのAmpチームが起点で、現在はOpenAI・Google・Cursor・Factoryらが共同で推進し、2025年12月にLinux Foundationへ寄贈されています。CLAUDE.md はClaude固有の AGENTS.md と考えるとわかりやすいでしょう。Claude Codeは仕様上 AGENTS.md ではなく CLAUDE.md を読み込みますが、AGENTS.md を実体ファイルにして CLAUDE.md をsymlinkとして張るのが、agents.md 公式が推奨するパターンです。冒頭で紹介した私の運用するリポジトリで言えば、agents/ 配下のファイル群がこの層に当たります。
SKILL.md と AGENTS.md はカバー範囲が違います。AGENTS.md は「全体の前提と境界」、SKILL.md は「特定タスクの実行ユニット」を担います。
たとえば、上で挙げた英文の文体監査スキル（avoid-ai-writing）は特定タスクなので SKILL.md の形で配布されます。一方、QAロールの前提や関わり方を書いた agents/genda/qa-support.md のようなファイルは、エージェントの境界を定義するものなので AGENTS.md 系の置き場になります。
これらの形式が共通して扱うのは、見た目ではなく「振る舞い・手順」の領域です。エージェントが何を知っていて、何を任され、何をしてはいけないか。それを検証可能な形で固定する取り組みと読めます。
3層分業の整理
ここまで見てきた三つのファイル形式を整理すると、それぞれが扱う層がはっきり分かれます。
| 層 | 形式 | 何を担うか | 例 |
|---|---|---|---|
| 動き方 |
AGENTS.md / CLAUDE.md（自然言語 + ルール） |
エージェント全体の前提、ロール、禁止事項 |
CLAUDE.md、agents/genda/qa-support.md のようなロール別ファイル |
| 個別タスク |
SKILL.md（先頭のYAML + Markdown本文） |
再利用可能なタスク単位、手順、専門知識 | avoid-ai-writing、社内独自の手順スキル |
| 見た目 |
DESIGN.md（先頭のYAML + Markdown本文） |
デザインシステムの仕様、検証可能な見た目 | Google Labs 本家の仕様、kzhrknt/awesome-design-md-jp の各サービスファイル |
三つは競合関係ではなく分業関係にあります。bergside/typeui のような CLI は、SKILL.md と DESIGN.md のどちらの形式でも生成・更新できるツールとして登場しており、これは分業を前提にしたツールチェーンの現れと言えます。
3層の分け方の本質は、「機械可読と人間可読のバランスをどこに置くか」が層ごとに違うという点にあります。AGENTS.md 系列は、ほぼ人間可読寄り。文脈判断やニュアンスを伝えるため、構造化されすぎない方が機能します。SKILL.md は先頭のYAMLで一部構造化されていますが、本文は人間可読寄り。タスクの粒度は人間が読めないと指示できないからです。DESIGN.md は、先頭のYAMLでデザイントークンを機械可読の形で書き、本文で設計意図を人間可読の形で書く。両者が明確に分離されています。
「機械可読寄り」「人間可読寄り」の重心が、層ごとに違う場所に置かれているわけです。これは「層が違うものは別ファイルで管理する」という、当たり前の構造化原則がAIエージェント向けにも適用された結果と読めます。ファイル名そのものもこの分業を素直に表しており、AGENTS.md は「エージェントへの指示」、SKILL.md は「スキル（再利用可能なタスク）」、DESIGN.md は「デザインシステム」と、扱う対象がそのまま命名になっています。
これまで「AIに渡すルール」を一つの CLAUDE.md に全部詰め込んでいたチームは、ここで分割の判断を迫られます。手元の CLAUDE.md を開いて、次のような問いを当てると、分割の候補が見えてきます。
- デザインシステムの規約を書いている部分はあるか → あれば
DESIGN.mdに切り出せる - 特定のタスク手順（月次集計、テストレビュー、契約レビュー等）を書いていないか → あれば
SKILL.mdに切り出せる - 残るのは、エージェント全体の前提と境界（ロール、禁止事項、エスカレーションの判断軸）だけ → これが
AGENTS.md相当として残る
つまり、3層分業はファイル分割の判断軸として機能します。
SDDとの接続
ここで視野を一段広げて、AIに渡す仕様という大きな流れの中で、3層分業がどこに位置するのかを確認しておきます。
SDDは、要件 → 設計 → タスク → 実装の順にspec（仕様）を書いてからコードを生成していく開発スタイルです。「specを書き捨てるのではなく、コードを生み出す実行可能な存在として扱う」という思想がベースにあります。AWSのKiroは .kiro/specs/{feature}/ に requirements.md、design.md、tasks.md を順に生成するワークフローを提供し、GitHubのSpec Kit（スター数も9万超）も /specify /plan /tasks /implement といったスラッシュコマンドで同じ流れを支援しています。Kiroが採用する EARS notation（Easy Approach to Requirements Syntax）は、要件を五つの定型テンプレートに整形することで曖昧さを減らす書き方の規約です。SDDは2025年から2026年にかけて急速に広がってきた領域で、Zennでも「仕様駆動開発」関連の記事は100本を超えています。
3層分業（AGENTS.md / SKILL.md / DESIGN.md）とSDDは、表面的には別々の流れに見えます。SDDコミュニティの議論はKiroやspec-kitの使い方に集中していて、DESIGN.md 側の議論は形式仕様や検証ツールに集中しています。両者を横断する記事はあまり見かけません。
ただ、両者の哲学を並べると、共通点が多くあります。
| # | 共通する哲学 | 仕様駆動開発 |
DESIGN.md / SKILL.md / AGENTS.md
|
|---|---|---|---|
| 1 | 実装前に明文化 | 要件 → 設計 → タスク → 実装 | 振る舞い → 実装、見た目 → 実装 |
| 2 | 機械可読 + 人間可読の併存 |
requirements.md（EARS notation）+ 自然言語 |
先頭のYAML + Markdown本文 |
| 3 | AIへの永続的コンテキスト |
.kiro/specs/{feature}/ を毎回参照 |
DESIGN.md / AGENTS.md を毎回参照 |
| 4 | 構文の規範化で曖昧さを減らす | EARS notationで要件を構造化（五つのテンプレート） |
lint でWCAGコントラスト比や構造規約を検証可能に |
| 5 | 「決めたこと」を場所として固定 | specファイルが意思決定の住処 | specファイルが意思決定の住処 |
両者は「AIに渡す仕様」というより大きな流れの中で、同じ哲学を共有していると言えます。
一方で、両者は同じものではありません。違いを一言で言うと、時間軸が違います。
| # | 軸 | 仕様駆動開発 |
DESIGN.md / SKILL.md / AGENTS.md
|
|---|---|---|---|
| 1 | 時間軸 | 「これから作るもの」を書く | 「すでにある規範」を書く |
| 2 | スコープ | 単一機能・プロジェクトの開発ライフサイクル | 永続的な規範・スタイル |
| 3 | 更新リズム | 機能ごとに新規作成 → 消費 → アーカイブ | 長期メンテナンス、徐々に成長 |
| 4 | 対象 | 要件・設計・タスク（動かし方の手続き） | 動き方・個別タスク・見た目の規範 |
SDDのspecは「これから何を作るか」を書きます。requirements.md は「この機能が満たすべき要件」、design.md は「この機能をどう実装するか」、tasks.md は「この機能を作るためのタスク分解」。完成すれば役割を終えて、アーカイブされていきます。
3層分業のspecは「何が常に守られるべきか」を書きます。DESIGN.md は何度UIを作ろうと色とタイポグラフィの規範を提供し、AGENTS.md は何度セッションを跨ごうとエージェントの前提を提供する。長期的にメンテされ、徐々に成長します。
この時間軸の違いから、両者が競合しないことがわかります。一過性のspecと永続的なspecは、両方が同じプロジェクトに併存できる。むしろ、相互参照される将来が見えます。.kiro/specs/checkout-feature/design.md の中で「ボタンは {colors.tertiary} を使う」と書けば、永続的な DESIGN.md が提供する色トークンを、一過性の機能specが参照する形になります。まだ事例として広く確立されたものではありませんが、十分に組み合わせられる構造です。
ここで気になるのは、SDDが活発な領域（Kiroコミュニティ等）とDESIGN.md / SKILL.md / AGENTS.md が活発な領域は、2026年5月時点ではまだ十分に交差していないという事実です。SDD側は「機能をいかに作るか」に集中し、3層分業側は「規範をいかに渡すか」に集中しているのが現状です。
SDDを導入していなくても、3層分業から始めれば「AIに渡す仕様」の入り口に立てます。逆に、SDDを運用しているチームは、機能specの中から DESIGN.md のトークンを参照し始めれば、規範の二重管理を避けられます。両者は次の段階で接続されていく流れにあると言えるでしょう。
過去にKiroの設計思想について整理した記事がありますので、SDD側に関心のある方は参照してみてください。
すべてが仕様化されるわけではない
3層分業の話を進めると、「全部仕様化したほうがいいのでは」という方向に流れがちですが、そうはなりません。
形式的に検証できないルールは、自然言語ドキュメントのまま残ります。文体のトーン、構造的な判断、文化的なニュアンス。たとえば、記事冒頭の共感ベースの入り方や、結論の余韻の付け方のような感覚的なもの。こうしたものは仕様化のコストに見合わないというよりも、仕様化しようとすると本質が抜け落ちます。
仕様化の判断軸はシンプルで、「形式的に検証可能か」です。
- 色のコントラスト比（検証可能） →
DESIGN.md - 用語の言い換え「leverage → use」（検証可能） →
SKILL.md - 文体のトーン（柔らかい断定、教科書的にしない）、全体のスタンス（教えるトーン厳禁、整理する立場）など（検証不可） →
AGENTS.md/CLAUDE.mdに残す
小規模チームでは、「自然言語の1ファイル」で十分なケースもあります。CLAUDE.md 一つで運用が回っているなら、無理に分割する必要はありません。仕様化のコストと運用負荷のバランスは、チームサイズと運用継続性で判断すべきでしょう。
3層分業は、SDDと同じく段階的に導入するもので、すべてを一気に仕様化する必要はありません。複雑な領域、検証可能性の効きそうな領域から始めればよいでしょう。
つまり、3層分業はゴールではなく、必要に応じて導入するオプションです。
どこから手をつけるか
ここまでの整理を踏まえると、いくつかの選択肢が見えてきます。
最初の一手として考えられるのは、自身の CLAUDE.md やスタイルガイドを開いて、形式的に検証可能な部分と判断系の部分を分類してみることです。色やタイポグラフィの規約、用語の言い換えリスト、構造ルール。こうした検証可能な部分が一定量ある場合、DESIGN.md（見た目）か SKILL.md（タスク）のどちらかに切り出す候補を一つ選ぶ。一気に分けず、最も独立性が高いものから始めるほうが安全です。
外部のスキルを取り込む方法もあります。avoid-ai-writing のような既製の SKILL.md を ~/.claude/skills/ に置くと、書き手としての自分のスタンスは変わらず、検証だけ機械に任せられます。
すでにKiroやspec-kitを運用しているチームは、.kiro/specs/{feature}/design.md の中から DESIGN.md のトークンを参照できないか試す段階に入っているかもしれません。機能specと永続specの相互参照は、まだ事例が少ない領域です。
共通するのは「すべてを一気に仕様化しない」という姿勢です。ドキュメント分割 → 運用試行 → 仕様化、という段階移行が現実的でしょう。3層分業は完成形ではなく、進化の途中にある動きだと捉えるのが安全です。
AIに渡すルールは、自然言語ドキュメント1枚から三つの仕様形式へと分業を始めました。それはSDDと同じ流れの、別の側面でもあります。
すべてが仕様になるわけではないけれど、役割が違うものを別ファイルで管理する。当たり前のことが、AIエージェント向けにも回り始めています。
Discussion