DESIGN.mdとは？AGENTS.mdの次に置く理由

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

DESIGN.mdは、リポジトリのルートに置くmarkdownファイルです。コードが現在の形になっている理由を、AIコーディングエージェントに伝えます。AGENTS.mdが答えるのは別の質問です。ここでの作業方法、つまりビルドコマンド、テストコマンド、必ず通過させるlint、変更してはいけないパスを示します。DESIGN.mdには、すでに確定している設計上の決定と、その決定を取り消した場合に壊れるものを記録します。

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

まだ最初のファイルを書いていない場合は、そこから始めてください。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つにつき1文で記述します。「すべての書き込みは queue.enqueue() を経由します。データベースへの直接書き込みは監査ログを迂回し、コンプライアンス用エクスポートが読み取るのはその監査ログです。」理由まで添えた不変条件は、想定外のタスクにも対応できます。理由のない不変条件は単なる好みに見え、好みは最適化の過程で削除されます。

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

境界。 小さな編集が大きな影響範囲を持つ箇所を記述します。データベーススキーマ。顧客がすでにスクリプトから利用している公開ルートのプレフィックス。アプリケーションの起動前に deploy が読み込む config ファイル。1つだけ実行されることを前提とする cron エントリ。それぞれを明記し、変更時に発生するコストを説明します。

用語。 コードが 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行のファイルは役に立ちません。

ツールによってはリポジトリのルートにあるすべての 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分で実行できる確認方法があります。

不変条件に直接触れるタスクをagentに与えます。「staleな行をexpiredとしてマークするbackground jobを追加してください。」ファイルが役割を果たしていれば、コードより先に回答に表れます。agentは、直接書き込むとaudit logをスキップするため、jobがqueue.enqueue()を経由して書き込む必要があると説明するはずです。データベース接続を開いて書き込む場合、考えられるのは2つです。そのファイルがまったく読み込まれていないか、不変条件の記述が曖昧で反論できる程度になっています。

token数も確認してください。このファイルは毎回のturnで読み込まれます。DESIGN.mdを追加した後にcontextの使用量が増え、回答が改善しない場合、そのファイルにはagentがすでに知っている説明が含まれています。Claude Codeでtoken counterを読むでは、その予算の使用箇所を確認できます。

これは、agentがlaptopではなくserver上で動作する場合に特に重要です。tmuxを使用したVPS上のClaude Code workspaceのように、agentが長時間実行されるsessionで動作しても、前日の会話は記憶していません。repositoryが記憶になります。chatで説明したもののcommitしなかった内容は、次のsessionではすべて失われます。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つのファイルより優れています。AGENTS.mdを一覧しにくくなったとき、または2つの部分が異なる頻度で変更されていることに気付いたときに分割してください。AGENTS.mdはビルドが変わると変更します。DESIGN.mdは設計上の決定が変わると変更します。こちらのほうが頻度は低く、影響は大きくなります。分割するときは、コードを編集する前にDESIGN.mdを読むようAGENTS.mdに1行追加してください。すべてのツールがルートにあるすべてのmarkdownファイルを読み込むわけではないためです。

DESIGN.mdはアーキテクチャ決定記録とどう違いますか？

ADR（アーキテクチャ決定記録）は1つの決定を日付付きで記録するもので、健全なプロジェクトではフォルダーに数十件蓄積されます。これは履歴です。履歴の読み込みにはコストがかかります。エージェントは、どの決定が現在も有効かを判断するために、すべての記録を読む必要があるからです。DESIGN.mdは現在の状態を記述したもので、すべてのタスクで全文を読むことを前提に書きます。すでにADRを作成している場合は、両方を維持してください。ADRには何をいつ決定したかを記録します。DESIGN.mdには現在の事実を記述し、エージェントにはこちらを参照させます。

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

毎回の処理で読み込んでも後悔しない長さにしてください。公開例が長いのは、視覚言語全体を定義しているためです。2026年8月時点で、Nuxtのファイルは約2,100語、Vercelのファイルは約6,500語あります。バックエンドサービスでは、通常はこれよりはるかに少なくて済みます。まず1ページから始め、1文で防げたはずの誤りをエージェントが犯したときだけ追加してください。長さは基準ではありません。各行は、記載がなければエージェントが誤る内容にしてください。