DESIGN.mdとは？AIエージェントの勝手な修正を防ぐ書き方

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年10月時点で、11件が掲載されています。Ant Design、Atlassian、Clerk、Juspay、Microsoft FAST、Mintlify、Nuxt、Oxide Computer、Resend、Vercel、VoltAgentです。各ファイルは公開 URL にあり、多くは公開元のドメイン上、残りは公開 GitHub リポジトリにあります。そのため、今すぐターミナルで読むことができます。

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

どちらもデザインシステムのドキュメントです。プロダクトの見た目、つまり色、文字、間隔、動きを定義しています。テーマそのものではなく、文章の構成に注目してください。役立つのは内容よりも、文章の形です。

Nuxt のファイルは、2026年10月27日時点でおよそ2,000語です。その大部分は、理由を添えたルールで構成されています。冒頭では、ダークモードをデフォルトテーマとすることを明記しています。ブランドカラーとして緑 #00DC82 を挙げ、ブランドカラーについて「ロゴ、ソーシャル画像、印刷物に使用します。UI コードの値として直接使用しないでください」と注記しています。終盤には Reject these という見出しのセクションがあり、次の内容が含まれています。

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Vercel のファイルはさらに長く、2026年10月時点でおよそ6,000語あります。そして、もう一歩踏み込んでいます。見出しの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 には、2026 年 10 月 27 日時点で README に記載されている数として、公開 Web サイトから抽出した 84 個のファイルが収録されています。各ファイルは同じ 9 セクション形式で書かれているため、エージェントにその 1 つを参照させれば、近い見た目を生成できます。これらのファイルは有用ですが、あくまで推測に基づくものです。各企業の担当者が内容を確認したわけではありません。

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

11 社という数はまだ少なく、リポジトリ自身もその点を明記しています。この標準は新しく、公式採用は増加中です。どちらのコレクションも、独自のファイルも公開しているオープンソースのエージェントフレームワーク VoltAgent が管理しています。そのため、この一覧は中立的な全数調査ではなく、採用状況を追跡するものとして読むべきです。それでも注目する価値があります。掲載企業に理由があるからです。複数の企業が、他の開発者が最も多くコピーするフロントエンドコードを提供しています。また、Ant Design、Microsoft FAST、Juspay、Oxide Computer などの新しい掲載企業は、他のチームが基盤として利用するデザインシステムです。これらのファイルは、DESIGN.md がどのようなものかを示す実例になりつつあります。AGENTS.md がたどった道筋と比較してください。agents.md は現在、この形式を使用する 60,000 を超えるオープンソースプロジェクトを数え、管理は Linux Foundation 傘下の Agentic AI Foundation が担っています。DESIGN.md も同じ道を歩み始めました。2026 年 4 月 21 日、Google はこの形式の仕様案をオープンソース化し、Apache-2.0 ライセンスの下で、トークンスキーマと CLI を備えた google-labs-code/design.md として公開しました。2026 年 10 月時点では、この形式は alpha バージョンで、現在も活発に開発されています。中立的な財団ではなく Google Labs が管理しており、ビジュアルアイデンティティを定義しています。そのため、バックエンド用ファイルに必要な不変条件については何も述べていません。エージェントが読み取れるファイルの規約は急速に固まりつつあり、その方向性は上流から決まりつつあります。

ユーザーインターフェースを持たないプロジェクトにおける DESIGN.md の役割

VPS 上で動作するソフトウェアの多くには、定義すべき視覚言語が存在しません。それでもこのファイルが必要なのは、その仕組みが色やデザインとは無関係だからです。これは、熟練の編集者であっても気づかぬうちに侵害してしまうような制約を書き留めるためのものです。

不変条件 (Invariants)
編集後も常に真でなければならない事柄を、それぞれ1文で記述します。「すべての書き込みは queue.enqueue() を経由する。データベースへの直接書き込みは監査ログをスキップするが、コンプライアンス上のエクスポートは監査ログを参照する」といった具合です。理由が添えられた不変条件は、予期せぬタスクに直面した際にも維持されます。理由のない不変条件は単なる好みに過ぎず、最適化の過程で排除されてしまいます。

却下された代替案 (Rejected alternatives)
明白な選択肢と、それが採用されなかった理由を記述します。「キャッシュに Redis は使用しない。サービスは単一の VPS 上で動作するため、プロセス内マップの方が高速であり、維持すべきデーモンを1つ減らせるためである。2台目のアプリケーションサーバーが必要になった時点で再検討する」といった内容です。この記述がなければ、キャッシュの高速化を求められた担当者は Redis を追加するでしょう。それは正しい判断ですが、制約を伝えていなかったことが問題です。このセクションこそが、ファイル全体の価値を決定づけます。

境界 (Boundaries)
小さな変更が大きな影響を及ぼす箇所を指します。データベースのスキーマ、顧客が既にスクリプトで利用している公開ルートのプレフィックス、アプリケーション起動前にデプロイが読み込む設定ファイル、単一インスタンスの実行を前提とした cron エントリなどが該当します。これらを列挙し、変更に伴うコストを明記してください。もしエージェントがオープンな Web にアクセスできる場合、例えば 検索バックエンドとして接続された自己ホスト型の SearXNG インスタンス を経由するようなケースは、境界として書き留める価値があります。取得したテキストのうち、コードに影響を与えてよいものと、単に引用するだけのものを区別して記述すべきだからです。

語彙 (Vocabulary)
コード内で 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.

不変条件

• すべてのコンポーネントは、設定ファイルなしでデフォルト値で起動できる必要があります。
• 外部サービスへの依存は、常にタイムアウトと再試行のロジックを伴う必要があります。
• ログ出力は、構造化された JSON 形式で標準出力に行う必要があります。
• 認証情報は、環境変数またはファイルシステム経由で注入する必要があります。

却下された代替案

• データベースの直接操作: 複雑性を避けるため、すべてのデータアクセスは API 経由に限定しました。
• 設定の動的リロード: 状態の一貫性を保つため、設定変更にはプロセスの再起動を必須としました。

コンポーネントの設計

ネットワークプロトコル

セキュリティモデル

拡張性

リポジトリ内に複数のパッケージが存在する場合、すべてを網羅する単一のルートファイルでは不十分です。モノレポ内のネストされた AGENTS.md ファイルと同様のディレクトリ分割を適用します。共有される決定事項を記述した短いルートファイルと、各パッケージの横に配置された小規模なファイルに分けます。

一部のツールはリポジトリルートのすべての Markdown ファイルを読み込みますが、指定されたファイルのみを読み込むツールもあります。そのため、前提を置かないようにしてください。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 に存在しており、なぜその設計になっているのかという理由はどこにも書かれていません。

これは二重のコストを生みます。最初のコストはコンテキストです。エージェントがタスクの開始時に毎回読み込むファイルは、タスクごとにコストがかかります。重複したインストールセクションは、固定されたウィンドウに対する純粋なオーバーヘッドです。このウィンドウの予算管理はそれ自体がスキルであり、Claude Code におけるコンテキストウィンドウの管理で解説されています。要約すると、自動的に読み込まれるものは、リポジトリ内で最も価値の高いテキストであるべきです。

2つ目のコストはさらに深刻です。同じ内容のコピーが2つあると、内容が乖離します。README にはサービスが 8080 で待ち受けるとあるのに、DESIGN.md には 3000 と書かれている場合、エージェントはどちらを優先すべきか判断できず、どちらかを選んでコードを書いてしまいます。時折間違った情報を出すファイルは、常に正しいファイルと同じ信頼度で参照されてしまいます。

テストは簡単です。ある段落が README にあっても違和感がないなら、DESIGN.md から削除してください。残るべきは、コードレビューで口頭で説明するような、「それはすでに試した」という文脈から始まる部分です。

ファイルが機能していることを確認する方法

これを確認するリンターは存在しません。1分で実行できるチェック方法があります。

エージェントに、不変条件（invariant）に直接抵触するタスクを与えてください。「期限切れの行をマークするバックグラウンドジョブを追加して」といった内容です。正しく機能しているファイルであれば、コードを提示する前に回答の中にその旨が現れます。エージェントは、直接書き込むと監査ログをスキップしてしまうため、そのジョブは queue.enqueue() を経由して書き込む必要があると指摘するはずです。もしエージェントがデータベース接続を開いて直接書き込むようなコードを提示した場合、ファイルが全く読み込まれていないか、不変条件の記述が曖昧で解釈の余地があるかのどちらかです。

トークン数も監視してください。このファイルはすべてのターンで読み込まれるためです。DESIGN.md を追加した後にコンテキストの使用量が増加し、かつ回答の質が向上していない場合、そのファイルにはエージェントが既に持っている情報が冗長に含まれています。Claude Code でのトークンカウンターの読み方 に、その予算がどこで消費されているかが示されています。

この点は、エージェントがノートPCではなくサーバー上で動作している場合に最も重要になります。tmux を使用した VPS 上の Claude Code ワークスペース のような、長時間実行されるセッションで作業するエージェントには、昨日の会話の記憶がありません。リポジトリがその記憶となります。チャットで説明しただけでコミットしなかった内容はすべて次のセッションでは失われます。DESIGN.md は、そうした説明を永続化させるための場所です。

議論の対象となる決定事項から始める

最初のバージョンを作成するのにかかる時間は20分です。レビュー担当者が「いいえ、ここでは別のやり方をします」と指摘した直近のプルリクエストをいくつか開いてください。こうしたコメントの一つひとつが、これまで明文化されていなかった不変条件です。これらは、エージェントが人間よりも速く、かつ頻繁に同じミスを繰り返す箇所でもあります。スケジュールに従うのではなく、失敗したタイミングでファイルに追加してください。エージェントを通常の開発ワークフローにどのように組み込むべきか検討中であれば、2026年版 AIエージェント学習ガイドが次のステップとして適切です。

FAQ

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

AGENTS.md と同じ意味での公式標準ではありません。AGENTS.md には agents.md という公式サイトがあり、60,000 を超えるオープンソースプロジェクトで使用され、Linux Foundation の一部である Agentic AI Foundation が管理しています。DESIGN.md には公開仕様がありますが、中立的な管理主体はありません。Google は 2026 年 4 月 21 日に仕様のドラフトをオープンソース化し、Apache-2.0 ライセンスの google-labs-code/design.md リポジトリで公開しています。2026 年 10 月時点では alpha 版で、現在も活発に開発されています。仕様では、色、タイポグラフィ、レイアウト、コンポーネントなどのビジュアルアイデンティティを定義しています。DESIGN.md はファーストパーティでの採用も進んでおり、Vercel、Nuxt、Atlassian、Resend など 11 社・プロジェクトが公開しています。また、コミュニティのコレクションには、2026 年 10 月 27 日時点で公開サイトから抽出されたものがさらに 84 件収録されています。バックエンドの不変条件と却下した代替案を記録するファイルとしては、該当するセクション名を定めた仕様がないため、今すぐ採用でき、自由に拡張できる慣例として扱ってください。

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

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

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

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

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

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