この投稿は、AI コーディングエージェントに渡される指示ファイルが、重なり合わない 3 つの層に分かれてきたと読み解く。エージェント全体の前提、役割、禁止事項を扱う AGENTS.md（およびそのツール固有の相当物である CLAUDE.md）、再利用可能な個々のタスクを扱う SKILL.md、そしてデザインシステムの仕様を扱う DESIGN.md である。投稿のきっかけはこの 3 つ目の登場 — Google Labs が 2026 年 4 月に DESIGN.md の仕様を公開した — であり、著者はこれを競合の追加ではなく、一揃いが完成したものと受け止めている。
投稿がこの観察の上に組み立てる議論は、各層が機械可読なコンテンツと人間可読なコンテンツのバランスをどこに置くかに関するものであり、肥大化した 1 つの CLAUDE.md を分割するための実践的な基準として、この 3 分割を提示する。後半では、3 つの層を 仕様駆動開発 と対比し、共通の思想を持ちながらも時間軸が異なることを見出している。
投稿は著者自身による指示ファイルのリポジトリの運用に基づいて書かれており、3 層への分割は目指すべき到達状態ではなく、それに見合う場面で採用する選択肢であると明言している。
要点
- 3 つのファイル形式は競合するのではなく、対象によって分担している。
AGENTS.mdはエージェントの前提と境界を、SKILL.mdは再利用可能なタスク実行の単位を、DESIGN.mdは生成される UI が持つべき見た目を扱う。投稿は、それぞれが扱う範囲は重ならないと述べている。 - 機械可読／人間可読という軸の上で各形式が占める位置は層ごとに異なり、投稿はそれをこの分担の本質として提示する。
AGENTS.mdは、コンテキストとニュアンスを伝えることがその目的であるため、ほぼ全体が人間可読な散文である。SKILL.mdは冒頭の YAML だけを構造化する。DESIGN.mdは両者を明示的に分け、機械可読なデザイントークンをフロントマターに、人間可読なデザインの意図を本文に置く。 - 投稿は、既存の
CLAUDE.mdを分割すべきかを判断する方法として 3 つの問いを示す。デザインシステムの規約が含まれているか（それはDESIGN.mdに移す）、特定のタスクの手順が含まれているか（それはSKILL.mdに移す）、そして残ったものがエージェントの前提と境界であり、それがAGENTS.mdの層である。 - 著者の読みでは、仕様駆動開発と 3 層への分割はいくつかの姿勢を共有している — 実装の前に書くこと、機械可読なコンテンツと人間可読なコンテンツを一緒に保持すること、AI が毎回参照できる永続的なコンテキストを保つこと、決定事項を既知の場所に固定すること — が、時間軸が異なる。SDD の仕様はこれから作るものを記述し、機能が完成すればアーカイブされるのに対し、3 層のファイルは維持され成長していく恒常的な規範を記述する。
- 著者は、すべてを仕様化すべきではないと論じる。示される基準は、そのルールが形式的に検証可能かどうかである。コントラスト比や用語の置き換えは検証可能だが、文書のトーンや全体的なスタンスはそうではなく、後者は無理に仕様に押し込めるとその実質を失うとされる。
- 投稿は、2026 年 5 月時点では 2 つのコミュニティがまだ実質的に交わっていなかったと報告する — SDD の議論は機能をどう作るかに、3 層の議論は規範をどう引き渡すかに集中している — そして、自然な接続点は機能仕様が永続的な
DESIGN.mdのトークンを参照することだと示唆する。ただし、これはまだ広く確立された実践ではないと述べている。
背景
投稿による問題の捉え方は、構造化されていない自然言語の指示文書には 2 種類のルールが混在しているというものである。形式的にチェック可能なルールと、判断を要するルールである。両者が同じファイルにあるため、チェック可能なルールまでもが人間のレビューに頼ることになる。3 つの形式は、この特定の混在に対する答えとして提示されている。
投稿の主張が著者自身による指示ファイルのリポジトリの運用 — 約 150 行の文章スタイルガイドと、約 15 の役割別の指示ファイル — に基づいている箇所では、投稿はそのことを明記しており、それらの箇所は調査に基づく実践ではなく一人の実務者による記述である。各形式が何のためのものかについての説明は、それらを公開しているプロジェクトから引かれている。