👀 この記事でわかること
- デザイナー2人体制でUI品質を維持するために DESIGN.md を導入した経緯
- AIエージェント向けの DESIGN.md に何を書いたのか
- AIレビュワーが実際にどのような指摘を行ったのか
- 運用して見えてきたメリットと課題
「デザイナーが2人しかいないのに、どうやって複数サービスのUI品質を維持するのか」
これは長い間、チームの課題でした。
社内のデザイナーは実質2人で、複数のWebサービスを横断してUI/UXデザインとフロントエンドを担当しています。
この限られた人数で全サービスのUIレビューを担うのは、なかなか難しい状況でした。
新機能や改修のたびにデザインレビューを行うのが理想ですが、すべてのPRを確認するのは現実的ではありません。
一方で、レビュー頻度を下げるとサービスごとにUIの揺れが発生し、徐々にデザインの一貫性が失われていきます。
そこで私たちは、各サービスのリポジトリに DESIGN.md を整備しました。
当初の目的は、Claude Code などのAIが実装する際の判断基準を明文化することでした。しかし運用を続けるうちに、AIが実装だけでなくデザインレビューも担えるようになっていきました。
この記事では、DESIGN.md を整備した経緯や運用方法、そして実際に使ってみて見えてきた効果と課題について紹介します。
📝 DESIGN.md に何を書いたか
DESIGN.md は、そのサービスのデザインルールをMarkdownで言語化したドキュメントです。カラートークン、ブレークポイント、コンポーネント仕様、禁止事項などを書いています。
人間ではなくAIエージェント（Claude Code、Devin）が読む前提で書いた点が、普通のデザインガイドと違うところです。具体的には次のような構成にしました。
- 冒頭でSSoT（Single Source of Truth）であることを宣言し、「デザインの判断はこのドキュメントが正」とエージェントに認識させる
- 「生hex直書き禁止」「独自ブレークポイント追加禁止」のように、やってはいけないこと（アンチパターン）を具体的に列挙する
- 新規UI実装時にエージェントが自己点検できるチェックリストを置く（例：WCAG AAのコントラスト比を計算してPRに記載する）
-
AGENTS.md（CLAUDE.mdへのシンボリックリンク）を入口にしてDESIGN.mdを参照させ、ファイル数を最小化する
AIにコードを書かせると、コードベースを見ずにそれっぽいテンプレを出したり、仕様から外れたりすることがあります。その逸脱を防ぐガードレールとして用意したのが最初の意図でした。
🤖 実装の指標が、レビューの自動化につながった
DESIGN.md を置いた状態で、GitHub上のAIレビュワー（Devin）にPRレビューを任せたところ、DESIGN.md を根拠にした指摘が出るようになりました。実例を4つ挙げます。
① 独自ブレークポイントの混入
新規コードで 768px が使われていたケースです。DESIGN.md には「新規実装のSPブレークポイントは 736px に揃える」「768px は許容リストにも含まれず追加禁止」と書いてあり、それを引いて修正案まで出してきました。
② トークンがあるのに生hexを直書き
#fff が直書きされていたケース。_variables.scss に $color-white: #FFFFFF が定義済みなのでトークンを使うべき、という指摘で、該当行（line 150, 155, 192）も添えてあります。
人間がやると「細かくてすみませんが」と前置きしたくなる類の指摘ですが、AIにはその遠慮がありません。
③ 禁止事項だが妥当な例外、という判断
機械的に弾くだけではない点が興味深いところでした。DESIGN.md では「tsx内のインラインstyle禁止」としていますが、APIやMCP、WEBごとに色を出し分けるデータ駆動の箇所について、Devinは「SCSSで静的に定義できない値であり、同一機能の別コンポーネントでも同じパターンが使われている。設計判断もコメントに明示されている」として、違反 ではなく Info 扱いに落として報告しました。ルールの背景まで読んだ上で判断していることが分かります。
④ DESIGN.md 自体の更新漏れ
DESIGN.md に「トークン・コンポーネント追加時は本ドキュメントも追従更新する」と書いていました。あるPRで新トークン（$color-error-dark）やButtonの新color（danger）が追加されたのに DESIGN.md が未更新だった点を、Devinが検知しました。danger ボタンの色のコントラスト比を計算してWCAG AAを満たすことまで確認した上での指摘でした。
更新漏れを指摘されたわけですが、これは「AIレビュワーが実際に DESIGN.md を読んでいる」ことの裏付けでもありました。
🔍 チームの振り返りで見えたこと
社内でKPT形式の振り返りをしました。
知見は「DESIGN.md を作るとき」と「運用してみて」の2つの段階に分けられたので、それぞれよかったことと課題を挙げていきます。
DESIGN.md を作るときに分かったこと
整備のプロセスそのものから得た知見です。
👍 よかったこと
- まず1サービスで
DESIGN.mdを固めてから他サービスへ展開する、という順序が無理なかった。最初から全サービス分を完璧に書こうとしなかったのがよかった - 実装するAI（Claude Code）とレビューするAI（Devin）を分けて検証したことで、単一AIでは見逃しやすい問題を捕捉できた
🤔 課題
- Claude Codeは最初の指示がないと、コードベースを見ずにそれっぽいテンプレを書き、既存実装と齟齬を生むことがある。最初のプロンプトで「コードを参照してから実装して」と明示するのが効いた
-
AGENTS.mdから@参照で読み込ませる際、ドキュメントが長すぎるとコンテキスト過負荷になる。行数の管理と、コンテキストの定期的なクリアが必要だった
運用してみて分かったこと
DESIGN.md を実装・レビューに使い始めてから見えてきたことです。
👍 よかったこと
- 2人のデザイナーがUIレビューに毎回入らなくてよくなった
- これまでレビューに充てていた時間を、より重要度の高い作業に回せるようになった
- トークン未使用・生hex・独自ブレークポイントなど、人間だと見落としがちな点をAIが拾う
🤔 課題
- 依頼していないバックエンドの挙動を足したり、仕様から静かに外れたりすることがある。AI出力には人間の検証ポイントを挟む必要がある
-
DESIGN.mdは放置すると実装に置いていかれる。いまは更新漏れをAIが指摘してくれる状態だが、Devinのワークフローで自動更新まで持っていきたい
そして、運用してみて見えたいちばんの課題はこれです。
GitHubでレビュー指摘が出るということは、実装時点で DESIGN.md に準拠しきれていない、ということでもあります。実装段階でもっと DESIGN.md を読み込んでもらえれば、レビュー指摘自体を減らせるはずです。
「レビューで弾く」から「実装で守る」へ、ガードレールを前倒ししていくのが次のテーマです。
📊 DESIGN.md導入で変わったこと
実際に運用してみると、レビュー作業の分担だけでなく、ルール管理やドキュメント運用にも変化がありました。
ルールをドキュメントにしておけば資産として残り、AIが代わりに守ってくれます。
✨ おわりに
DESIGN.md を整備したことで、AI実装時の判断基準が揃っただけでなく、AIによるデザインレビューも実用的なレベルで機能するようになりました。
もちろん、最初から完璧なルールを作る必要はありません。
ルールがまだ言語化されていない場合は、まず「やってはいけないこと」やレビューで繰り返し指摘される内容から書き始めるのがおすすめです。禁止事項はAIが機械的にチェックしやすく、比較的早く効果を実感できます。
私たちもまだ運用の途中ですが、少人数で複数サービスのUI品質を維持したい、レビュー負荷を減らしたいと考えているチームの参考になれば幸いです。
Discussion