DESIGN.md：AIエージェントと「デザインの意図」を共有するための新標準

AIに「いい感じのUIを作って」と頼んでも、プロジェクト独自の色味や、角丸サイズといったこだわりまではなかなか再現してくれません。

この「AIと人間の認識のズレ」を解決し、AIエージェントを強力なフロントエンドエンジニアに変えるための新標準、それが google-labs-code/design.md です。

今回は、この DESIGN.md の仕様を本サイト sawara.me に導入し、Gemini CLI でどのように活用しているかをご紹介します。

AIには「言葉」だけでは伝わらない

従来のプロジェクトでは、デザインの仕様は Figma や Wiki、あるいはコード内の CSS 変数に散らばっていました。AIエージェントに指示を出す際、これらの情報をすべて伝えるのは現実的ではありません。

結果として、AIは「なんとなくモダンなデザイン」を生成してしまい、後から人間が修正するという二度手間が発生しがちです。

DESIGN.md：AIとデザインの「意図」を共有する

Google Labs が提案している DESIGN.md は、この問題を「一つのファイル」で解決します。

その最大の特徴は、YAML による厳密なデータ定義（Tokens） と、Markdown による設計根拠（Prose） の統合です。

---
version: 1.0.0
tokens:
  color:
    brand:
      primary: "#3366cc"
  border:
    radius:
      card: 16
---
# Design Guidelines
...

• Tokens (YAML): AIがコード生成時に直接参照できる正確な数値。
• Prose (Markdown): デザインの雰囲気や「なぜその色なのか」という、数値化できない意図。

AIはこのファイルを読み込むことで、「このプロジェクトのプライマリーカラーは #3366cc で、角丸は 16px を使うべきだ」という知識を、明示的に指示される前に獲得します。

Gemini CLI での活用：明示的なインポート

Gemini CLI（のエージェント）は、プロジェクトルートにある GEMINI.md を開発におけるベース・コンテキストとして読み込みますが、DESIGN.md のような別名のファイルは、以下のように GEMINI.md 内で明示的にインポート することで認識されるようになります。

@./DESIGN.md

# Project Guidelines

...

このようにインポート設定を行うことで、エージェントは自動的に DESIGN.md をスキャンし、開発時に以下のような判断を下せるようになります。

1. 色の選択: tokens.color.brand.primary に定義された青色を使用する。
2. コンポーネントの形状: tokens.border.radius.card に基づき、角丸を 16px に設定する。
3. コーディング規約: 本文の Markdown にある「MUI v6 を使用し、CSS Modules でスタイルを定義する」という指示に従う。

人間が細かなスタイルを毎回指示しなくても、最初からプロジェクトのトーンに合ったコードが生成されるのです。

正しく読み込まれているか確認する

設定した DESIGN.md が正しくコンテキストに含まれているか不安な場合は、Gemini CLI の対話インターフェース内で以下のコマンドを実行して確認できます。

• /memory show: 実際にモデルに送信されている、インポートが展開された後のコンテキスト全文を表示します。

/memory show を実行して DESIGN.md の中身が表示されれば、AIエージェントのコンテキストにデザイン仕様が正しく反映されており、一貫性のある提案が可能な状態になっています。

本サイトでの実践：リファクタリングと検証

実際に、本サイトの DESIGN.md を Google Labs 仕様にアップデートしました。

ただ書き換えるだけでなく、公式の検証ツールを使用して、仕様に準拠しているかを確認できます。

npx @google/design.md lint DESIGN.md

リファクタリング前は「YAML が見つからない」という警告が出ていましたが、アップデート後はエラー・警告ともにゼロでパスしました。この検証ステップがあるおかげで、AIにとっても読み取りやすいクリーンな状態を維持できます。

リファクタリング前に検証ツールで出力された警告

{
  "findings": [
    {
      "severity": "warning",
      "message": "No YAML content found. Expected frontmatter (---) or fenced yaml code blocks."
    }
  ],
  "summary": {
    "errors": 0,
    "warnings": 1,
    "infos": 0
  }
}

リファクタリング後は警告がなくなった

{
  "findings": [],
  "summary": {
    "errors": 0,
    "warnings": 0,
    "infos": 0
  }
}

まとめ：DESIGN.md は 「AIエージェントと一緒に開発するためのインターフェース」 です

デザインドキュメントは、もはや「人間が後から確認するための資料」だけではありません。 「AIエージェントと一緒に開発するためのインターフェース」 へと進化しています。

プロジェクトのルートに DESIGN.md を置くだけで、AIはより賢く、より一貫性のある提案をしてくれるようになるはずです。