DESIGN.mdとは？AGENTS.mdでは扱わない設計理由

DESIGN.md とは何か、AGENTS.md では扱わない内容

DESIGN.md は、リポジトリのルートに置く Markdown ファイルです。コードが現在の形になっている理由を、AI coding agent に伝えます。AGENTS.md は別の問いに答えます。つまり、ここでの作業方法です。ビルドコマンド、テストコマンド、合格させる必要がある lint、変更してはいけないパスなどを記載します。DESIGN.md には、すでに確定している設計上の判断と、その判断を取り消した場合に発生する問題を記録します。

ここでいう coding agent とは、リポジトリを自律的に読み取り、編集する Claude Code や Cursor のようなツールです。coding agent は、デフォルトで確信を持って動作します。認識できないパターンを見つけると、そのパターンを改善します。手書きのキャッシュが Redis（インメモリデータストア）に置き換えられることがあります。モデルがこれまでに読み取ったコードの多くでは、キャッシュはそのように実装されているためです。AGENTS.md だけではこれを防げません。make test はどちらの実装でも通るためです。破られたルールは、agent が読める場所に一度も記載されていませんでした。

まだ最初のファイルを書いていない場合は、そこから始めてください。AGENTS.md と、その隣に置く HUMAN.md で、形式と各ツールがファイルを探す場所を説明しています。ここからは、その次の章です。

公開されている DESIGN.md の実際の内容

形式を最も早く理解するには、企業が自社について公開しているファイルを読むことです。リポジトリ official-design-md では、そのようなファイルだけを追跡しています。収録条件は 1 行で示されており、その 1 行こそがこのコレクションの要点です。

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

2026 年 8 月時点で、掲載されているのは Atlassian、Clerk、Mintlify、Nuxt、Resend、Vercel、VoltAgent の 7 件です。各ファイルは安定した公開 URL に置かれているため、今すぐターミナルで読むことができます。

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

どちらもデザインシステムのドキュメントです。製品の見た目、つまり色、タイポグラフィ、余白、動きをどのように定めるかを説明しています。題材ではなく、文章の構成に注目してください。役立つのは内容よりも、書き方の形です。

Nuxt のファイルは約 2,100 語で、その大部分は理由を添えたルールです。

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Vercel のファイルはさらに長く、2026 年 8 月時点で約 6,500 語あります。そして、もう一歩踏み込んでいます。見出しの 1 つは Reject generated-design reflexes です。その下には、禁止されていない場合に高性能な生成器が選びがちなものの一覧があります。

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

この文がファイルの種類を定義しています。これは、確信を持ったモデルが生成するデフォルト設定を記述した一覧です。モデルがそれらを生成しなくなるように公開します。コミットする価値のある DESIGN.md は、どのドメインでも、そのドメイン向けの一覧になっています。

企業はなぜ独自の DESIGN.md を公開するのか？

コミュニティが先に取り組みました。awesome-design-md には、公開 Web サイトからリバースエンジニアリングした73個のファイルが収録されています。各ファイルは同じ9セクション形式で記述されているため、エージェントに1つを参照させれば、そのデザインに近いものを生成できます。これらのファイルは有用ですが、現在も推測に基づいています。各社の担当者がレビューしたものではありません。

ファーストパーティーのファイルは、出力の解釈ではなく、出力の元になる情報です。Vercel がタイポグラフィのスケールを変更すると、vercel.com/design.md もそれに合わせて変更されます。3月にスクレイピングしたコピーは、古いスケールをエージェントに学習させ続けます。リポジトリ内にも、そのコピーが古くなったことを知らせるものはありません。

公開元が7社という数は少なく、リポジトリもその点を明記しています。この標準は新しく、公式な採用は増加中です。どちらのコレクションも、自身のファイルも公開しているオープンソースのエージェントフレームワーク VoltAgent が管理しています。そのため、この一覧は中立的な全数調査ではなく、動向を追うためのものとして読むべきです。それでも注目する価値があります。理由は、その7社がどの企業かにあります。これらは、他の開発者がフロントエンドコードを最も多くコピーしている企業です。各社のファイルは、DESIGN.md がどのようなものかを示す実例になりつつあります。AGENTS.md がたどった道筋と比較してください。agents.md によると、現在では60,000を超えるオープンソースプロジェクトがこの形式を使用しており、管理は Linux Foundation 傘下の Agentic AI Foundation が担っています。エージェントが読み取れるファイルの規約は急速に定まりつつあり、上位の企業や組織から定着しています。

ユーザーインターフェースがないプロジェクトの DESIGN.md には何を書くか

VPS 上で動作するソフトウェアの多くには、指定すべき視覚的なデザインがありません。それでも、このファイルを置く価値はあります。仕組みと色は関係ないためです。自信のある編集者なら気付かないまま破る制約を、明文化することが目的です。

不変条件。 編集後も必ず成立していなければならないことを、1 文ずつ書きます。「すべての書き込みは queue.enqueue() を経由します。データベースへ直接書き込むと監査ログを迂回します。コンプライアンス用エクスポートが読み取るのは監査ログです。」理由まで併記した不変条件は、想定外の作業にも耐えます。不変条件だけを書くと単なる好みに見え、好みは最適化の過程で削除されます。

却下した代替案。 分かりやすい選択肢と、それを採用しなかった理由を書きます。「キャッシュに Redis は使用しません。サービスは単一の VPS で動作するため、プロセス内の map のほうが高速で、常駐させるデーモンも 1 つ少なくなります。2 台目のアプリケーションサーバーを用意した時点で再検討します。」この段落がなければ、キャッシュを高速化するよう指示されたエージェントは Redis を追加します。その判断は正しいものです。制約を伝えていないためです。このセクションがファイル全体の価値を支えます。

境界。 小さな編集が大きな影響範囲を持つ箇所を書きます。データベーススキーマ。顧客がすでにスクリプトから利用している公開ルートのプレフィックス。アプリケーションの起動前にデプロイ処理が読み取る設定ファイル。1 つのコピーだけが実行される前提の cron エントリです。それぞれを列挙し、変更にどのようなコストが発生するかを記載します。エージェントがオープンウェブにもアクセスできる場合は、検索バックエンドとして接続した自己ホスト型 SearXNG インスタンスを介することも明記します。取得したテキストのうち、コードに影響を与えてよいものと、あなたに引用して返すだけのものをファイルで定義すべきだからです。

用語。 コードで tenant と書き、チームが customer と呼んでいるなら、その対応関係を書きます。ここでエージェントが誤って推測すると、読みやすいのに対象を誤ってモデル化したコードが生成されます。これはレビューで最も見つけにくい種類の誤りです。

本日そのまま使える DESIGN.md

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

本日、記憶だけで書ける invariants と rejected alternatives の 2 セクションを記入し、残りは見出しだけにします。正直な 4 行のファイルは役に立ちます。推測で埋めた 40 行のファイルは役に立ちません。リポジトリに複数のパッケージがある場合、ルートの 1 ファイルですべてを扱うことはできません。ここでも、monorepo 内のネストした AGENTS.md ファイルで有効なディレクトリ単位の分割を適用します。すべてのパッケージで共有する決定事項を記した短いルートファイルと、固有の決定事項を持つ各パッケージの横に置く、より小さなファイルに分けます。

リポジトリのルートにあるすべての markdown ファイルを読み込むツールもあれば、指定された 1 つだけを読み込むツールもあります。そのため、決めつけないでください。AGENTS.md へのポインターを追加します。

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

アンチパターン: READMEを繰り返す DESIGN.md

最もよくある悪い例は、読みやすいのに何も教えない文書です。プロジェクトの概要から始まり、機能を列挙し、インストール方法を説明して、ライセンスで終わります。これらはすべてREADMEにすでに書かれており、なぜその設計になっているのかは何も説明していません。

この重複には、2つのコストがかかります。1つ目はコンテキストです。エージェントが各タスクの開始時に読むファイルは、タスクごとにコストが発生します。固定されたコンテキスト枠の中で、インストール手順の重複は純粋な負荷です。その枠を配分する技術については、Claude Codeでコンテキストウィンドウを管理するで説明しています。要点は簡単です。自動的に読み込まれる内容には、リポジトリ内で最も価値の高い文章を置くべきです。

2つ目のコストは、さらに深刻です。同じ内容を2か所に置くと、両者に差異が生じます。READMEにはサービスが8080で待ち受けると書かれているのに、DESIGN.mdにはまだ3000と書かれている場合、エージェントにはどちらを優先すべきか判断できません。そのため、どちらかを選び、その前提でコードを書きます。常に正しいとは限らないファイルが、常に正しいファイルと同じ確信度で参照されてしまいます。

確認は簡単です。段落の内容がREADMEにそのまま置けるなら、DESIGN.mdから削除してください。残すべきなのは、コードレビューで口頭で説明する内容です。「それはすでに試しました」から始まる部分です。

ファイルが機能しているかどうかを確認する方法

このファイルには linter がありません。ただし、1 分で実行できる確認方法があります。

不変条件に直結するタスクをエージェントに与えます。「古い行を expired としてマークするバックグラウンドジョブを追加してください」と指示します。ファイルが役割を果たしていれば、コードより先に回答へ現れます。エージェントは、直接書き込むと監査ログを迂回するため、ジョブが queue.enqueue() 経由で書き込む必要があると説明するはずです。データベース接続を開いて書き込む場合、考えられるのは 2 つです。ファイルがまったく読み込まれていないか、不変条件の記述が曖昧で反論できる余地があるかのどちらかです。

トークン数も確認してください。このファイルはすべてのターンで読み込まれます。DESIGN.md を追加した後にコンテキスト使用量が増え、回答が改善しない場合、そのファイルにはエージェントがすでに持っている情報が書かれています。Claude Code でトークンカウンターを読むでは、その予算の内訳を確認できます。

これは、エージェントがノートパソコンではなくサーバー上で動作する場合に特に重要です。tmux を使った VPS 上の Claude Code ワークスペースのように、エージェントが長時間実行されるセッションで動作していても、前日の会話を記憶していません。リポジトリが記憶になります。チャットで説明したもののコミットしなかった内容は、次のセッションでは失われます。その説明を残し、次回以降も利用できるようにする場所が DESIGN.md です。

議論になった判断から始めます

最初の版は 20 分で作成できます。レビュアーが「いいえ、ここでは別の方法で実施します」と書いた、直近の pull request をいくつか開きます。こうしたコメントはすべて、まだ文書化されていない不変条件です。また、エージェントが人よりも速く、頻繁に同じ間違いをする箇所でもあります。失敗したときにファイルへ追記し、定期的なスケジュールでは更新しません。通常の開発ワークフローにエージェントをどのように組み込むかをまだ検討中であれば、AI エージェントを学ぶための 2026 ガイドが次に読む資料として適しています。

FAQ

DESIGN.md は公式標準ですか？

AGENTS.md と同じ意味での公式標準ではありません。AGENTS.md には agents.md という公式サイトがあり、60,000 を超えるオープンソースプロジェクトで使われています。また、Linux Foundation の一部である Agentic AI Foundation が管理しています。2026年8月時点で、DESIGN.md には管理団体も公開仕様もありません。存在するのは、Vercel、Nuxt、Atlassian、Resend など7社によるファーストパーティ採用です。これらの企業は公開 URL で DESIGN.md を公開しています。さらに、コミュニティのコレクションには、公開サイトからリバースエンジニアリングされた73件が収録されています。セクション名を検証する仕組みはないため、すぐに採用でき、自由に拡張できる慣例として扱ってください。

DESIGN.md は AGENTS.md の一部にすべきですか？

小規模なリポジトリであれば、そのとおりです。エージェントが確実に読む1つのファイルのほうが、2つのファイルのうち1つが無視される構成より優れています。AGENTS.md の内容を一覧しにくくなった場合や、2つの部分が異なる頻度で変更されるようになった場合に分離してください。AGENTS.md はビルドが変わったときに変更します。DESIGN.md は設計上の決定が変わったときに変更します。後者は発生頻度が低く、影響も大きくなります。分離する場合は、コードを編集する前に DESIGN.md を読むよう AGENTS.md に1行追加してください。すべてのツールがルートディレクトリのすべての markdown ファイルを読み込むわけではないためです。

DESIGN.md は architecture decision record とどう違いますか？

ADR (architecture decision record) は、1つの決定を日付付きで記録したものです。健全なプロジェクトでは、これらをディレクトリに数十件蓄積します。これは履歴であり、エージェントが現在も有効な決定を判断するにはすべて読む必要があるため、読み込みコストが高くなります。DESIGN.md は現在の状態を記述し、すべてのタスクで全文を読むことを前提にしています。すでに ADR を作成している場合は、両方を保持してください。ADR には、何をいつ決定したかを記録します。DESIGN.md には、現在何が正しいかを記述します。エージェントに参照させるのは DESIGN.md です。

DESIGN.md はどのくらいの長さにすべきですか？

毎回の処理で読み込んでも負担に感じない長さにしてください。公開されている例が長いのは、ビジュアル言語全体を定義しているためです。2026年8月時点で、Nuxt のファイルは約2,100語、Vercel のファイルは約6,500語です。バックエンドサービスには、通常これほどの量は必要ありません。まずは1ページから始め、1文で防げたはずの誤りをエージェントが犯した場合にだけ増やしてください。長さは評価基準ではありません。各行は、記載しなければエージェントが誤る内容であるべきです。