コーディングエージェントは、自信があり、高速ですが、指示されない限り、コードベースのアーキテクチャについて何も知りません。Claude CodeやCodexに曖昧なチケットを渡すと、コンパイルされ、簡単なテストに合格するコードを喜んで作成しますが、ドメイン層とHTTP層の境界を静かに侵害します。エージェントは設計ドキュメントを読んでいません。見ることのできるファイルを読み、パターンを照合し、推測しただけです。DESIGN.mdファイルは、エージェントが必ず参照する唯一の場所、つまりリポジトリ自体にアーキテクチャの意図を書き留めることで、この推測の問題を解決します。
TL;DR (要するに)
DESIGN.mdは、コードベースのアーキテクチャの意図、制約、設計上の決定をプレーンなMarkdown形式で記録するコミュニティ慣習のリポジトリファイルです。これにより、コーディングエージェント（Claude Code、Codex、Cursor）がシステムに適合するコードを生成し、システムと衝突するのを防ぎます。これは「なぜコードはこのように設計されているのか」に答え、AGENTS.mdは「どのようにビルドし、テストするのか」に答えます。
はじめに
コーディングエージェントを導入するすべてのチームが1週間以内に遭遇する失敗パターンがこれです。決済サービスに返金エンドポイントを追加するようエージェントに依頼すると、コントローラーからデータベースを直接呼び出し、ゲートウェイエラーを飲み込み、すでに存在する通貨タイプに気づかずに新しい通貨タイプを発明する動作するハンドラーが返ってきます。差分はきれいで、テストもパスします。しかし、アーキテクチャを知っているレビュアーだけが気づく3つの点で間違っています。エージェントはコーディングが下手なのではなく、あなたの頭の中、Notionのページ、または8ヶ月前のSlackスレッドにある決定事項を見落としているのです。
DESIGN.mdは、多くのチームがたどり着いた答えです。これは、リポジトリのルートにコミットされる単一のMarkdownファイルで、レイヤー化のルール、決して破ってはならない不変条件、意図的に選択したパターン、そして却下したパターンなど、システムに関する重要な事実をすべてのエージェントに伝えます。ベンダーの仕様でもなければ、それを所有する委員会もありません。これは、ARCHITECTURE.mdやCONTRIBUTING.mdと同様に、慣習です。しかし、エージェントがすでに読んでいるツール固有の指示ファイルと自然に組み合わされ、APIやバックエンドの作業においては、作成できる最もレバレッジの高いドキュメントの一つです。
DESIGN.mdとは実際には何か
DESIGN.mdは、なぜあなたのコードがそのように見えるのかを記録したプレーンテキストです。何をするのか（それはREADME）、どう実行するのか（それはAGENTS.md）ではなく、新入社員に重要なものを触らせる前に、シニアエンジニアが初日に説明するであろう推論です。
どのファイルにもない会話を考えてみてください。「リクエストスレッドから決済ゲートウェイを呼び出すことはありません。ゲートウェイは負荷がかかるとタイムアウトするため、すべてアウトボックステーブルを経由します。」「金額は常に最小単位の整数カウントです。丸め誤差の事件の後、浮動小数点数を禁止しました。」「Account集約が残高の変更を所有しています。他は台帳に書き込みません。」これらは設計上の決定です。これらはソースコードを読むエージェントには見えません。なぜなら、ソースコードは決定そのものではなく、その理由も示さず、決定の結果を示すからです。エージェントはAccount.debit()が存在することを見ることができます。しかし、あなたが意図的にそれを唯一の書き込みパスにしたことを見ることはできないため、喜んで2番目のパスを追加するでしょう。
この慣習は、古くから確立されたプラクティスにルーツを持っています。ARCHITECTURE.mdパターン（Alex Kladovの広く引用されている著作で普及）は、コードベースの構造と不変条件を説明する高レベルのマップをリポジトリに含めるべきだと主張し、コードと行ごとに同期を保とうとはしません。アーキテクチャ決定記録（ADR）は、個々の決定とその理由を時系列で捉えます。DESIGN.mdは、そのようなドキュメントをコーディングエージェントを含む読者向けに作成したものです。簡潔で、宣言的で、意思決定指向であり、エージェントが実際に読み込む場所に配置されます。
これが機能するのには2つの特性があります。リポジトリ内に存在するため、エージェントはコードを読むのと同じツールでそれを読み込みます。プラグインやAPI呼び出しは不要です。そして、それは意図に関するものであるため、ファイルが移動しても有用性を保ちます。パッケージ名を変更するとREADMEのスクリーンショットは古くなりますが、「ドメインロジックはウェブフレームワークをインポートしない」というルールは依然として真です。
DESIGN.md vs AGENTS.md vs CLAUDE.md vs README
これらのファイルは、人々を混乱させるほど重複していますが、一つにまとめるのが間違いであるほど異なります。簡潔に言えば、READMEは人間のオンボーディング用、AGENTS.mdはエージェントの運用契約、CLAUDE.mdはClaude固有の指示ファイルであり、DESIGN.mdはこれらすべてが恩恵を受けるアーキテクチャ上の推論です。
AGENTS.mdは現在、広く採用されている実際のフォーマットです。agents.mdプロジェクトでは、「コーディングエージェントをガイドするためのシンプルでオープンなフォーマット」と説明されており、数万のプロジェクトで利用され、Linux FoundationのAgentic AI Foundationの下で管理されています。その役割は運用上のもので、ビルド手順、テストコマンド、コードスタイル、コミット規約など、新しいチームメイトが作業を滞りなく進めるために伝えるような事項です。AnthropicのClaude Codeのメモリに関するドキュメントによると、CLAUDE.mdはClaude専用に同様の指示の役割を果たします。ドキュメントでは、すでにAGENTS.mdがある場合、@AGENTS.mdでそれをインポートするCLAUDE.mdを作成し、両方のツールが単一の真実のソースを読み込むようにすることも推奨しています。
これらの説明に欠けているものに注目してください。それは深いアーキテクチャ上の根拠です。AGENTS.mdとCLAUDE.mdは短く保たれるように調整されています。Claude Codeのドキュメントでは、長いファイルはコンテキストを消費し、モデルがそれらに従う信頼性を低下させるため、CLAUDE.mdを200行未満に保つことを明示的に推奨しています。真のアーキテクチャの説明、境界、不変条件、却下された代替案、データモデルのルールなどは、肥大化させずにそこに収めることはできません。そのため、代わりにそれを参照します。DESIGN.mdが深いドキュメントとなり、AGENTS.md / CLAUDE.mdは単一行でそれを指し示します。
| ファイル | 対象読者 | 何に答えるか | 寿命 / 変更頻度 | 長さ |
|---|---|---|---|---|
README.md |
人間（ユーザー、新規コントリビューター） | これは何か、どうやって始めるか | 機能に応じて変更 | 中 |
AGENTS.md |
あらゆるコーディングエージェント | ここでどうビルド、テスト、リント、コミットするか | ツールに応じて変更 | 短（運用向け） |
CLAUDE.md |
Claude Code専用 | AGENTS.mdと同じ、加えてClaude固有のルール | ツールに応じて変更 | 短（約200行未満） |
DESIGN.md |
エージェント + エンジニア + レビュアー | なぜシステムはこのように設計されているのか；決して破ってはならないものは何か | アーキテクチャに応じて変更（稀） | 中、決定事項が密集 |
これらの関係は補完的であり、競合するものではありません。Claude + Codexを使用する環境でのクリーンなセットアップは次のようになります。人間向けのREADME.md。ビルド/テスト/スタイルに関するAGENTS.md。@AGENTS.mdにClaude専用の2行を追加したCLAUDE.md。そして、アーキテクチャを保持するDESIGN.mdはAGENTS.mdからリンクされ、すべてのエージェントがオンデマンドでそれをロードします。重複はなく、各ファイルには一つの役割があります。これらのファイル間でClaudeのコンテキストを構造化する方法についてさらに詳しく知りたい場合は、Claude Codeワークフローで実際のメモリモデルについて解説しています。
DESIGN.mdに何を含めるべきか（テンプレート付き）
DESIGN.mdは、エージェントがコードから推測できない質問に答えるべきです。システムの形状、どの単一ファイルにも現れないルール、そして意図的に下した決定などです。宣言的に記述してください。各セクションは、エッセイではなく、レビュアーが強制するルールのように読めるべきです。
以下を網羅してください:
- システム形状: レイヤーやモジュール、および依存関係の流れの方向。境界ごとに1文。
- 不変条件: 常に真でなければならないこと。それらを絶対的なものとして記述します。「承認された当座貸越以外では、残高がマイナスになることはない。」「すべての外部呼び出しは、リクエストキーによって冪等である。」
- 主要な決定とその根拠: 理由を知るまでは任意に見える選択。理由を含めること。その根拠こそが、エージェントがそれを「修正」するのを防ぎます。
- 却下された代替案: 意図的に行わなかったこと。これにより、エージェントがそれを新しいアイデアとして提案するのを防ぎます。この単一のセクションで、多くの悪い提案を回避できます。
- データとドメインのルール: 金額表現、時刻/タイムゾーン処理、識別子、ソフトデリート、マルチテナンシー。
- APIコントラクトの信頼できる情報源: OpenAPI仕様がどこに存在するか、手書きの型よりもそれが権威であるというルール。
- 新規コードの配置場所: エージェントがロジックを散乱させないように、「Xを追加するならYに属する」という短いマップ。
- 範囲外 / 触らないで: 生成されたファイル、移行中のレガシーモジュール、エージェントが手を出すべきでないもの。
以下に、現実的な決済APIサービス向けに書かれた完全なテンプレートを示します。これをコピーし、該当しない部分を削除し、残りを埋めてください。
# DESIGN.md: 決済APIサービス
このファイルは、アーキテクチャの意図と、その背後にある決定を記録します。
コードを生成または変更する前にこれを読んでください。変更がここにあるルールと衝突する場合は、回避策を講じるのではなく、作業を中止して問題を指摘してください。
## システム形状
階層化されており、依存関係は内側のみを指します。
http (handlers, DTOs) -> app (use cases) -> domain (entities,
invariants) <- infra (db, gateway clients)
- `domain/`は`http/`、`app/`、または任意のフレームワークからのインポートを一切持ちません。
- `infra/`は`domain/`または`app/`で宣言されたインターフェースを実装します。
- `http/`はデータベースや決済ゲートウェイを直接操作しません。
`app/`のユースケースを呼び出します。
## 不変条件（常に保持されるべき）
- 台帳エントリは一度書き込まれると変更できません。修正は新しい相殺エントリであり、更新や削除ではありません。
- 口座残高は台帳エントリから導出され、コードが直接設定できる可変フィールドとして保存されません。
- 金額は最小単位（セント）の整数カウントとISO-4217通貨コードで構成されます。浮動小数点数は決して使用せず、単一の操作で複数の通貨を混合しないでください。
- 外部決済ゲートウェイへのすべての呼び出しは、`idempotency_key`によって冪等です。リトライによって二重課金されてはなりません。
- 明示的な`OverdraftPolicy`がその口座に許可しない限り、残高がマイナスになることはありません。
## 主要な決定と根拠
- **ゲートウェイ呼び出しのアウトボックスパターン。** ハンドラーは、ビジネス変更と同じDBトランザクションで意図行を書き込み、その後ワーカーがゲートウェイを呼び出します。根拠: ゲートウェイは負荷がかかるとタイムアウトし、インラインで処理するとリクエストの遅延とエラー処理が不明確になりました。リクエストハンドラーからゲートウェイを呼び出さないでください。
- **集約ごとの単一書き込みパス。** `Account.post_entry()`のみが台帳に書き込みます。根拠: 2番目の書き込みパスが2025年3月の残高ずれを引き起こしました。新しい動作は集約のメソッドとして追加し、新しいクエリとして追加しないでください。
- **台帳のみのイベントソーシング。** システムの残りの部分はCRUDです。根拠: 金額については完璧な監査証跡が必要であり、それ以外の部分での完全なイベントソーシングはコストが高すぎました。
## 却下された代替案（再導入禁止）
- 集約間のORM遅延読み込みは、N+1問題と不明確なトランザクション境界を引き起こしました。リポジトリは完全にロードされた集約を返します。
- 残高をその場で更新される列として保存することは禁止されています。残高ずれのインシデントを参照してください。残高は常に導出されます。
- レジストリから取得した汎用`Money`ライブラリは使用しません。独自の`domain/money.py`を使用してください。
- リクエストスレッドからの加盟店への同期Webフックは、ブロックしてサイレントに失敗します。通知キューを使用してください。
## データとドメインのルール
- すべてのタイムスタンプはUTCであり、timestamptzとして保存され、エッジでRFC 3339形式にフォーマットされます。素朴な日時型が関数境界を越えることはありません。
- IDはアプリ層で生成されるULIDであり、DBのオートインクリメントは使用しません。
- ソフトデリートは使用されません。レコードはアクティブであるか、明示的なユースケースによってアーカイブテーブルに移動されます。
- マルチテナント: すべてのクエリは`tenant_id`でスコープされます。テナントスコープのないリポジトリメソッドはバグです。
## APIコントラクトの信頼できる情報源
- `api/openapi.yaml`にあるOpenAPI 3.1仕様が権威です。
リクエスト/レスポンスタイプはそこから生成されます。`http/generated/`内の生成されたタイプを手動で編集しないでください。
- 新規または変更されたエンドポイント: まず`api/openapi.yaml`を更新し、その後再生成し、実装します。仕様は、コード変更前にApidogで設計およびレビューされます。
- エラー応答はRFC 9457（problem+json）に準拠します。共有の`problem()`ヘルパーを使用してください。アドホックなエラー形状を考案しないでください。
## 新規コードの配置場所
- 新しいエンドポイント: ルートは`http/routes/`、DTOは`http/dto/`、ユースケースは`app/usecases/`、ドメインロジックは`domain/`に配置します。
- 新しい外部統合: クライアントは`infra/clients/`、インターフェースは`app/ports/`に配置します。
- 横断的関心事（認証、ロギング、冪等性）: ミドルウェアは`http/middleware/`に配置し、ハンドラーにインラインで記述しないでください。
## 範囲外 / 触らないで
- `http/generated/`: OpenAPIから再生成されるため、編集は失われます。
- `legacy/billing_v1/`: 凍結されており、移行中です。拡張しないでください。
- `migrations/`: 適用済みのマイグレーションを編集しないでください。新しいものを追加してください。
## 迷ったとき
要求された変更が上記のルールを破る必要がある場合、正しい対応は、沈黙してルールを回避するのではなく、その旨を伝え、最小限の設計整合性のある代替案を提案することです。
最後のセクションは、見た目以上に重要です。要求が設計と衝突した場合にエージェントにどうすべきかを伝えることで、そのファイルは受動的なドキュメントから能動的なガードレールへと変わります。これがなければ、制約にぶつかったエージェントはそれを回避し、その回避策を出荷する傾向があります。
コーディングエージェントはどのようにDESIGN.mdを実際に消費するか
エージェントは特別なDESIGN.mdパーサーを持っていません。彼らは他のファイルと同様に、ファイルツールで読み込み、その内容をコンテキストとして扱うことで消費します。したがって、それを読み込むメカニズムが重要であり、ツールによって若干異なります。
信頼できるパターンは、各エージェントが起動時にすでに読み込んでいる指示ファイルからDESIGN.mdを参照することです。Claude Codeの場合、それはCLAUDE.mdです。メモリに関するドキュメントでは、@pathインポート構文が記述されており、@DESIGN.mdはセッション開始時にファイルをコンテキストに展開します。AGENTS.mdエコシステムの場合、AGENTS.mdにそれを指し示す行を追加します（「アーキテクチャと設計ルール: DESIGN.mdを参照。構造変更の前に読んでください」）。ディレクトリツリーを辿るエージェントは、最も近いAGENTS.mdを検出し、ポインタを見て、アーキテクチャに関わる作業の場合にDESIGN.mdをプルします。どちらの方法でもコンテンツを複製することはありません。短い運用ファイルを短く保ち、詳細なファイルには詳細を記述します。
これらのツールがどのように動作するかに関する3つの実用的な注意点：
第一に、エージェントはそのファイルを強制的なルールとしてではなく、コンテキストとして扱います。Claude Codeのドキュメントは、CLAUDE.mdの内容はモデルが従おうとするガイダンスであり、厳格な制約ではないと明言しています。これは、そこから参照するすべてに当てはまります。そのため、テンプレートではすべてをテスト可能な絶対的なものとして記述し、明示的な「迷ったとき」の指示を追加しています。曖昧な記述はプレッシャーの下で無視されがちですが、明確なルールはより頻繁に守られます。
第二に、長さと構造は順守度に影響します。モデルは読者と同じように構造をスキャンするため、ヘッダーと箇条書きは段落よりも優れています。3ページの建築哲学の塊はざっと読まれるだけですが、明確な見出しの下にある10の明確な不変条件は利用されます。散文のためではなく、検索のために記述してください。
第三に、このファイルは生成だけでなく、レビューの経済性も変えます。エージェントが部分的に無視したとしても、レビュアーが違反したルールを指摘すれば、エージェントは一度の修正でそれを直します（「これはDESIGN.mdの単一書き込みパスのルールに違反しています」）。書かれた決定に基づいて修正を行うこのフィードバックループこそが、多くの真の価値が生まれる場所です。独自のエージェントハーネスを構築するチームは、まさにこれに依存しています。独自のClaude Codeを構築するを参照して、そのループが自律的なフローにどのように組み込まれるかを確認してください。
アンチパターンと陳腐化させない方法
DESIGN.mdを無価値にする最も速い方法は、Wikiページのように書くことです。陳腐化した設計ファイルは、存在しないよりも悪いです。なぜなら、エージェントと人間の両方がそれを信頼し、誤解を招くからです。以下を避けてください。
- コードの再記述。 「
UserServiceクラスはユーザーを処理する」という記述は、エージェントがuser_service.pyから読み取れる以上の何も伝えません。ファイルを読むことで真となる文は削除してください。コードでは伝えられないこと、つまり根拠、不変条件、却下されたパスのみを記述してください。 - チュートリアルの肥大化。 「機能を追加する方法」といったステップバイステップのチュートリアルは、
CONTRIBUTING.mdやスキルガイドに属するものであり、ここではありません。DESIGN.mdにシェルコマンドやコピペスニペットが含まれるようになった瞬間、それは間違ったドキュメントであり、ツールの速度で陳腐化します。 - 願望を事実として記述すること。 システムの半分がCQRSを使用していないのに「システムはCQRSを使用している」と書くと、エージェントは架空の事実に合致するコードを生成するように訓練されます。現在真であることと、意図的に目指している方向を記述し、その違いを明確にしてください。「目標: すべての書き込みはユースケースを介する。現状:
legacy/はこのルールをバイパスしている。これを拡張してはならない。」 - 所有者なし、レビューのトリガーなし。 誰も責任を負わない設計ファイルは、四半期ごとに陳腐化します。トリガーと紐付けましょう。モジュールを追加する、レイヤー境界を変更する、または新しい外部依存関係を導入するすべてのPRで
DESIGN.mdをレビューしてください。そのルールをPRテンプレートに含めてください。一部のチームは、「この変更はDESIGN.mdの決定を変更するか？もしそうなら、同じPRで更新する」というチェックリスト項目を追加しています。 - 同期の劇場。 コードと行ごとに同期させようとしないでください。それは負け戦であり、アーキテクチャドキュメントが放置される理由です。年に数回しか変わらない決定事項のレベルに留め、毎週変わる関数シグネチャのレベルにしないでください。matkladの
ARCHITECTURE.mdのガイダンスは、ここで正しい直感を提供します。頻繁に変わる可能性が低いものだけを書き留めてください。 - 他の指示ファイルとの矛盾。
AGENTS.mdがエラー処理についてあることを述べ、DESIGN.mdが別のことを述べている場合、エージェントは任意にどちらかを選択します。運用ルールはAGENTS.md/CLAUDE.mdに、アーキテクチャルールはDESIGN.mdに保持し、それらが重複しないようにしてください。お互いを参照する必要がある場合、一方がもう一方を指し示し、両方が同じ事実を主張することはありません。
健康的なDESIGN.mdは、短く、密度の高く、宣言的で、所有され、トリガーに基づいてレビューされます。もしあなたのものが長く、物語的で、最後に触られたのが1年前であれば、エージェントはフィクションを読んでいることになります。
APIおよびバックエンドコードベースのためのDESIGN.md
ここでこのファイルが真価を発揮します。APIおよびバックエンドサービスには、エージェントが最も苦手とする、目に見えない高コストな制約がまさに存在します。コントラクト境界、トランザクションセマンティクス、冪等性、データ整合性、レイヤー化などです。これらはどれも単一のファイルから明らかになるものではなく、誤って実装すると、本番環境や金銭に影響するバグを引き起こします。
これらのAPI固有の事項をDESIGN.mdに記述することで、バックエンドチケットにおけるエージェントの出力品質が飛躍的に向上します。
- 契約が信頼できる情報源であり、その場所を明記する。 OpenAPI仕様が権威であり、生成された型を手動で編集してはならないことを明確に記述します。エージェントは、ビルドが通るように生成された型を「親切にも」修正するのを好みますが、
DESIGN.mdに1行書くだけでそれを止められます。仕様ファイルのパスを指し示してください。まずApidogで契約を設計し、OpenAPIドキュメントをリポジトリにエクスポートする場合、DESIGN.mdはそのファイルをすべてのエンドポイントが準拠しなければならないものとして指定でき、エージェントは明確なターゲットを得ることができます。コードの前に契約を設計することの議論は、AIエージェント向けAPIの設計でカバーされています。設計優先の契約こそが、エージェントが生成したハンドラーを安全に受け入れることを可能にします。 - トランザクションと一貫性の境界。 トランザクションはどこで始まり、どこで終わるのか？その中で何が許されるのか？「DBトランザクション内では外部呼び出しは決して発生させない。アウトボックスを使用する。」ファイルがそれを禁止しない限り、エージェントは毎回素朴なインライン呼び出しをデフォルトとします。
- 冪等性とリトライ。 冪等性戦略を不変条件として記述します。決済、注文、プロビジョニングのエンドポイントでは、冪等性キーの欠落が二重課金につながります。エージェントはハンドラーを読むだけではこれを推測しません。
- エラーモデル。 一文で記述します。「すべてのエラーは
problem()ヘルパーを介したproblem+json形式である。エラーの形状を考案してはならない。」これがないと、エンドポイントごとに異なるエラーエンベロープが生成され、すべてのクライアントが破損します。 - 認証とテナンシーのスコープ。 「すべてのクエリはテナントスコープされる。スコープされていないリポジトリメソッドはバグである。」これはセキュリティ上の不変条件であり、個々のクエリでは目に見えないため、まさに書き記しておくべきルールです。
- バージョン管理と破壊的変更ルール。 何が破壊的変更と見なされるか、どのようにバージョン管理するか、マイナーリリースで何が許されるか。エージェントは喜んでレスポンスフィールドの名前を変更するでしょうが、そのファイルはそれがプロセスを伴う破壊的変更であることを彼らに伝えます。
バックエンドの作業では具体的な効果が得られます。レイヤー違反が減り、予期せぬインラインゲートウェイ呼び出しがなくなり、一貫したエラーおよびページネーションの形状が実現し、エージェントがスキーマを推測するのではなくOpenAPI仕様を指示されたため、契約に準拠したハンドラーが生成されます。エージェントは発明をやめ、準拠し始めます。エージェントが作成したAPIも動作させたい場合、契約と設計の組み合わせにより、ツールとエージェントは既知のインターフェースに対してテストできます。Apidogをダウンロードすると、設計優先のワークスペース、DESIGN.mdが指し示すOpenAPIエクスポート、および生成されたエンドポイントが実際に契約に合致しているかを確認するためのMCPサーバーとAIエージェントデバッガーが提供されます。
結論
DESIGN.mdは、あなたのコードがなぜそのように設計されているのか、つまりエージェントがソースから読み取ることができない不変条件、決定、却下された代替案を記録します。AGENTS.mdやCLAUDE.mdを置き換えるのではなく補完します。それらは短く運用的なままであり、DESIGN.mdは詳細なアーキテクチャを保持し、それらから参照されます。- 受動的な散文ではなくガードレールとして機能するように、テスト可能な絶対的なものとして宣言的に記述し、「迷ったら回避するのではなく指摘する」というルールを加えてください。
- 契約境界、トランザクション、冪等性、テナンシーのスコープが見えず、誤ると高価な代償を伴うAPIやバックエンドのコードベースで最も効果を発揮します。
- オーナーを設定し、PRテンプレートに紐付けたレビューのトリガーを設定することで、陳腐化を防ぎましょう。コードと行ごとに同期させてはなりません。
- バックエンドにおける最大の成果は、OpenAPI仕様を権威あるものとして指定することで、エージェントがスキーマを発明するのではなく、契約に準拠するようになることです。
- まずその契約を設計してください。ApidogをダウンロードしてAPIを設計優先で進め、
DESIGN.mdが指し示すOpenAPI仕様をエクスポートし、エージェントが生成したエンドポイントが実際にそれに合致するかをテストしてください。
よくある質問
DESIGN.mdはAGENTS.mdのような公式標準ですか？
いいえ。AGENTS.mdは、Linux FoundationのAgentic AI Foundationの下で管理されている、明確に定義され広く採用されているフォーマットです。DESIGN.mdは、ARCHITECTURE.mdやADRと同じ系列の、単一の所有者や仕様を持たないコミュニティ慣習です。準拠すべき標準ではなく、適応する有用なパターンとして扱ってください。
AGENTS.mdやCLAUDE.mdをすでに持っている場合でも、DESIGN.mdは必要ですか？
もしあなたのアーキテクチャに自明でない制約があるなら、はい、必要です。AGENTS.mdとCLAUDE.mdは短く運用的に保つことを意図しており、Claude CodeのドキュメントではCLAUDE.mdを約200行未満に保つことを推奨しています。深いアーキテクチャ上の根拠は、肥大化させずにそこに収めることはできず、順守度を損なうため、DESIGN.mdに記述して参照します。運用ファイル自体については、AGENTS.mdファイルの書き方を参照してください。
DESIGN.mdはARCHITECTURE.mdとどう違うのですか？
主に意図と対象読者が異なります。ARCHITECTURE.mdは、コードベースをマッピングする人間向けコントリビューターを対象とした古い慣習です。DESIGN.mdは、コーディングエージェントを含む読者向けに書かれた同じアイデアであり、より宣言的で、決定と不変条件に焦点を当て、エージェントの指示ファイルから明示的に参照されることでコンテキストに読み込まれます。多くのチームは1つのファイルと1つの名前を使用しますが、原則は同じです。
DESIGN.mdはどのくらいの長さにするべきですか？
エージェントが繰り返し間違える決定をカバーするのに十分な長さで、すべての行が存在する価値があるほど短くするべきです。包括的であるよりも、決定が凝縮されている方が優れています。チュートリアルのように読めたり、コードを再記述している場合は削除してください。不変条件と根拠に焦点を絞った2〜4ページは、エージェントがじっくり読まない15ページの物語よりも優れています。
エージェントに実際に読ませるにはどうすればよいですか？
エージェントが起動時にすでに読み込むファイルからそれを参照します。Claude Codeの場合、CLAUDE.mdから@DESIGN.mdでインポートします。AGENTS.mdエコシステムの場合、AGENTS.mdに、構造変更の前にDESIGN.mdを読むようにエージェントに指示するポインタ行を追加します。全体を短いファイルに貼り付けず、運用ファイルを短く保つために参照してください。
エージェントは常にDESIGN.mdに従いますか？
いいえ、そしてそのことを考慮して設計する必要があります。エージェントの指示ファイルは、モデルが従おうとするコンテキストであり、強制される設定ではありません。ルールは明確な絶対的なものとして記述し、「競合を指摘し、回避しない」という明確な指示を追加し、レビューサイクルに依存してください。DESIGN.mdで違反したルールを指摘することで、最初のパスで見落とされた場合でも、迅速かつ正確な修正が得られます。
DESIGN.mdは特にAPI契約の問題に役立ちますか？
大いに役立ちます。その最も価値の高いバックエンドでの利用法は、OpenAPI仕様が権威であり、そのファイル名を指定することで、エージェントがスキーマを発明したり生成された型を手動で編集したりする代わりに、契約に準拠するようにすることです。Apidogのようなツールでまずその契約を設計することで、エージェントはあなたのDESIGN.mdが直接指し示すことができる明確なターゲットを得られます。
DESIGN.mdはリポジトリのどこに置くべきですか？
リポジトリのルートに、README.mdやAGENTS.mdの隣に置くべきです。そうすることで、エージェントも人間も検索することなく見つけられます。モノレポの場合、システム全体のルール用のルートDESIGN.mdと、ローカルアーキテクチャ用のパッケージごとのDESIGN.mdがうまく機能します。これは、エージェントがディレクトリツリーで最も近いAGENTS.mdを読み込む方法を反映しています。