開発効率化

AI開発の成果物が毎回ブレるので、DESIGN.mdを3層に分けた

AI に UI や記事を書かせると、毎回どこか惜しい出力になります。見た目は整っているのに薄い、文章は読めるのに温度感がズレる、というやつです。

最近見かけた DESIGN.md という発想は面白かったのですが、そのまま全部に当てるのは危ないとも感じました。結論から言うと、1 枚の万能ファイルに寄せるより、共通ガイド と 用途別ガイド に分けた方が運用しやすいです。

CREATIVE_GUIDE.md を土台に、その上に BLOG_STYLE.md と各プロダクトの DESIGN.md を重ねる3層構造の図解
1つの万能ファイルに寄せるより、共通原則と用途別ルールを分けた方が、AI にも人間にも扱いやすい。

結論: 1つの DESIGN.md より、3層に分けた方が強い

今回整理したのは次の 3 層です。

  1. 全成果物に効く CREATIVE_GUIDE.md
  2. ブログ用の BLOG_STYLE.md
  3. 各プロダクト固有の DESIGN.md

この形にすると、AI に毎回長い前提を説明しなくても、ある程度同じ方向に寄せられます。しかも、ブログとプロダクト UI のように性格が違う成果物を無理に 1 枚へ詰め込まなくて済みます。

レイヤー 役割 対象
CREATIVE_GUIDE.md 全体の文体、情報設計、避ける表現、色の癖 プロダクト、ブログ、ドキュメント全般
BLOG_STYLE.md 記事構成、導入、見出し、CTA、図版の方針 ブログ記事、記事 LP
DESIGN.md 色、余白、コンポーネント、トーンの個別ルール 各プロダクト固有 UI

なぜ 1 枚の DESIGN.md では足りないのか

DESIGN.md 自体はかなり有効です。特に、AI に「この雰囲気で作って」と曖昧に言う代わりに、色、余白、トーン、コンポーネント方針を明文化して渡せるのは大きいです。

ただ、問題は適用範囲です。たとえば、不動産投資の判定ダッシュボード向けのルールを、そのままブログに当てると重すぎます。逆に、ブログ向けの穏やかな読みやすさを、分析ツールの UI に当てると緊張感が足りません。

要するに、次の 2 つを分ける必要があります。

  • 自分が作るもの全般に共通する好み
  • その成果物にだけ必要なルール

ここを混ぜると、AI にとっても人間にとっても運用が曖昧になります。

今回作った 3 層の中身

1. 共通原則は CREATIVE_GUIDE.md に置く

ここには、成果物全般に効く基準だけを書きます。たとえば次のようなものです。

  • 無難な SaaS テンプレに寄せすぎない
  • 情報をスカスカにしない
  • 日本語は短く直接的にする
  • 色数を増やしすぎない
  • 「革新的」「誰でも簡単」のような薄い表現を避ける

これは、ブログにもプロダクトにも効きます。逆に言うと、この層では「ボタン角丸は 16px」みたいなことは書きません。そこまで行くと個別ルールです。

2. ブログ用は BLOG_STYLE.md に分ける

記事は UI と違って、読み進める体験が重要です。なので、ブログ専用のルールを分けました。

  • 結論を先に出す
  • 導入は 2 から 4 文に収める
  • 1 セクション 1 論点にする
  • 記事末尾に CTA を置く
  • 図版は雰囲気作りではなく説明補助に使う

この層を分けると、「ブログっぽい読みやすさ」と「プロダクトっぽい操作性」を混同しなくて済みます。

3. プロダクト固有の UI は各 DESIGN.md で持つ

たとえば PropertyScore では、ダーク基調、青アクセント、判定色、情報密度、警告の強さ、CTA の見せ方を個別に定義しました。

ここはプロダクトごとにかなり変わります。分析ツール、ポータル、LP、モバイル画面では求められる緊張感が違うからです。

この構成にすると何が楽になるのか

AI への指示が短くなる

以前は毎回、「もっと硬めで」「でも読みやすくて」「色は増やしすぎず」みたいな曖昧な指示を繰り返していました。今は次のように言えば済みます。

Follow ~/Dev/CREATIVE_GUIDE.md.
For blog work, also follow article-drafts/BLOG_STYLE.md.
For product UI, follow that product's DESIGN.md.

これだけで最低限の前提が揃うので、毎回ゼロから好みを教え直さなくて済みます。

成果物ごとのズレを説明しやすい

「この UI は重すぎる」と感じた時に、単に感覚で戻すのではなく、共通原則 と 個別ルール のどちらに反しているのかを見分けやすくなります。

これが地味に大きいです。AI 出力の修正が、好みの押し付けではなく、ルールとの差分として扱えるようになります。

新しいプロダクトを始める時に速い

毎回、デザインや文体のルールをゼロから起こす必要がなくなります。共通層を土台にして、足りない分だけ個別の DESIGN.md を足せばいいからです。

テンプレートリポジトリにこの運用を書いておくと、新規プロダクトでも最初から同じ流れに乗せやすくなります。

ブログにそのまま応用できるか

ここは重要です。DESIGN.md の発想自体はブログにも使えますが、ブログにはブログのルールが必要です。

ブログで欲しいのは、ピクセルパーフェクトな UI というより、次のような品質です。

  • 何の記事かがすぐ分かる
  • 結論までの距離が短い
  • 検索意図からズレない
  • 読み終わったあとに次の行動がある

このため、ブログは BLOG_STYLE.md として別に持った方が素直でした。見出し構成、導入、CTA、図版の使い方まで定義した方が効きます。

運用してみて分かったこと

  • 1 枚の魔法ファイルではなく、レイヤー分けの方が現実的
  • 共通原則は抽象度を上げすぎない方が効く
  • 個別ルールは用途に寄せてかなり具体的に書いた方がいい
  • AI による初稿のブレは減るが、最終判断はやはり人間が必要

特に最後は重要です。ガイドを置けば全部うまくいくわけではありません。ただ、修正の起点が感覚論だけにならないのは大きいです。

これから同じ仕組みを作るなら

  1. まず全体共通の原則を 1 枚にまとめる
  2. 次にブログ、LP、プロダクト UI など用途別ルールを分ける
  3. 最後に個別プロダクトの DESIGN.md を作る

逆順でやると、局所最適のルールが増えて管理しづらくなります。共通層から先に作った方が、あとで流用しやすいです。

まとめ

DESIGN.md は有効ですが、全部を 1 枚に押し込むより、共通原則と用途別ガイドに分けた方が実務では扱いやすいです。

今回の整理では、CREATIVE_GUIDE.md、BLOG_STYLE.md、各プロダクトの DESIGN.md という 3 層にしました。これで、ブログにもプロダクトにも同じ土台を効かせつつ、必要な差分だけを個別に持てるようになりました。

AI に毎回同じことを説明しているなら、一度この形でファイルに逃がした方がいいです。少なくとも、「何がズレているのか」を言語化するコストはかなり下がります。

自分はこの構成をベースに、今後は新しいプロダクトや記事を作るたびにルールを足していくつもりです。最初から完璧なガイドを作る必要はなくて、ブレたポイントを後から追記していく運用の方が現実的だと感じています。

-開発効率化