はじめに

「AIエージェントに画面を作ってもらったら、昨日と今日でデザインが全然違う…」

個人開発をしていると、こんな経験はありませんか？

AIに指示するたびにフォントが変わる、カラーが変わる、果てはFlaskで作ったはずなのに次はDjangoを提案してくる。毎回ゼロから判断させるから、毎回違う答えが返ってくるのです。

この記事では、awesome-design-mdとTECH.mdという2つのファイルを使って、AIが生成するUIと技術スタックを完全に統一する方法を紹介します。

さらに、ObsidianとVSCode、そしてRenderを組み合わせた開発フロー全体も解説します。

この記事で紹介するツール

awesome-design-md：人気サイトのデザインシステムをまとめたmdファイル集
Obsidian：マークダウンベースのノートアプリ。VaultでDESIGN.mdを一元管理
Codexdian：ObsidianからOpenAI Codexを使えるプラグイン
VSCode：コードの修正・デバッグ・Git管理
Render：GitHubと連携してFlaskアプリを自動デプロイ

問題の本質：AIに毎回「判断」させているから統一できない

AIエージェントにコードを書かせると、次のような問題が起きがちです。

UIのデザインが毎回バラバラ（フォント、カラー、余白…）
技術スタックが毎回違う（FlaskかDjangoか、Jinja2かReactか）
認証方式が毎回違う（bcryptかargon2か、JWTかセッションか）

原因はシンプルです。選択肢を与えているから、毎回違う選択をするのです。

解決策も同じくシンプルです。

選択肢を与えず、答えをmdファイルに書いておく。AIはそれに従うだけにする。それだけです。

STEP 1：awesome-design-mdでUIデザインを統一する

awesome-design-mdとは？

awesome-design-mdは、NotionやSpotify、Appleなど人気サイトのデザインシステムをDESIGN.mdファイルとして収集したリポジトリです。

各ファイルには以下の情報が含まれています。

セクション	内容
Visual Theme & Atmosphere	デザインの雰囲気・哲学
Color Palette & Roles	カラーパレットと役割
Typography Rules	フォントと階層
Component Stylings	ボタン・カード・入力欄のスタイル
Layout Principles	スペーシングとグリッド
Do’s and Don’ts	やっていいこと・やってはいけないこと
Responsive Behavior	レスポンシブ対応
Agent Prompt Guide	AIへの指示用プロンプト集

DESIGN.mdの使い方

GitHubからDESIGN.mdをダウンロードして、プロジェクトに置くだけです。

あとはAIへの指示に「DESIGN.mdを参照して」と一言添えるだけで、毎回そのデザインスタイルに合ったUIを生成してくれます。

さらにPREVIEW.htmlとPREVIEW_DARK.htmlも一緒に使うと効果的です。テキストだけでなく実際の見た目のサンプルもAIに渡せるので、より精度が上がります。

「DESIGN.mdとPREVIEW_DARK.htmlを参照して、
ダッシュボード画面を作ってください」

STEP 2：TECH.mdで技術スタックを固定する

UIデザインと同じ考え方で、技術スタックもTECH.mdに明記しておきます。

ポイントは「使わないものも明記する」ことです。AIは選択肢があると迷います。「これは使わない」と禁止事項を明示することで、毎回同じ構成で生成してくれるようになります。

# Tech Stack

## Language
- Python 3.11

## Web Framework
- Flask

## Template Engine
- Jinja2

## Database
- PostgreSQL
- psycopg2-binary

## ORM
- SQLAlchemy

## WSGI Server
- 開発環境: Flask built-in server
- 本番環境（Render）: Gunicorn

## 認証
- パスワードハッシュ: bcrypt（flask-bcrypt）
- JWTライブラリ: PyJWT
- 認証フロー: JWT + Refresh Token

## 仮想環境
- .venv（python -m venv .venv）

## Shell
- PowerShell必須
- アクティベート: .venv\Scripts\Activate.ps1

## Deploy
- Render

## 注意事項
- DjangoやFastAPIは使わない
- 認証にflask-loginは使わない
- パスワードハッシュはbcrypt以外使わない
- JWTはPyJWT以外使わない
- bashやzshは使わない
- 本番ではFlask built-in serverを使わない

README.mdのルールもTECH.mdに書く

さらに、README.mdに何を書かせるかもTECH.mdに定義しておきましょう。

こうしておくと、AIが毎回正しい形式でREADME.mdを生成してくれます。

## ドキュメントルール
- README.mdには以下のコマンドを必ず記載すること
  - 仮想環境の作成・アクティベート
  - 依存関係のインストール
  - データベースのセットアップ
  - ローカル起動
  - Renderへのデプロイ

STEP 3：ObsidianのVaultで一元管理する

DESIGN.mdとTECH.mdをプロジェクトごとにコピーするのは手間です。

Obsidianのノートアプリを使って、一か所で管理しましょう。

Obsidian Vault/
├── DESIGN.md
├── PREVIEW.html
├── PREVIEW_DARK.html
└── TECH.md

ObsidianにはCodexdianというプラグインがあり、これを使うとObsidianのノートを参照しながらOpenAI CodexにAIコーディングを依頼できます。

わざわざファイルをコピーする必要がなくなります。

なお、機密情報（DBのパスワードやJWTシークレットなど）は.envファイルで管理し、ObsidianのVaultには入れないようにしましょう。.gitignoreに.envを追加するのも忘れずに。

# .env（Gitには絶対上げない）
DATABASE_URL=postgresql://ユーザー名:パスワード@localhost:5432/DB名
SECRET_KEY=your-secret-key
APP_ID=your-app-id
JWT_SECRET=your-jwt-secret

STEP 4：開発フロー全体像

全体の流れをまとめると、こうなります。

Obsidian + CodexdianでDESIGN.mdとTECH.mdを参照しながら初期コードを生成
VSCodeでコードを確認・修正・デバッグ
VSCodeのGit機能でGitHubにプッシュ（Codexに「コミットしてプッシュして」と指示することも可能）
RenderがGitHubのプッシュを検知して自動デプロイ

Renderは起動コマンドにgunicorn app:appを設定しておけば、GitHubにプッシュするだけで本番環境が更新されます。

RenderのダッシュボードにはDATABASE_URLやJWT_SECRETなどの環境変数を事前に設定しておきましょう。

まとめ

この記事で紹介した方法を一言でまとめると、「AIに毎回判断させない」です。

UIはDESIGN.mdで統一
技術スタックはTECH.mdで統一
ファイルはObsidianで一元管理
コーディングはCodexdianでObsidianから直接指示
修正・デバッグ・Git管理はVSCode
デプロイはRenderが自動で対応

mdファイルに答えを書いておくだけで、AIは毎回一貫したコードを生成してくれます。

ぜひ試してみてください。

AIにUIを作らせるたびにデザインがバラバラになる問題を、2つのmdファイルで完全に解決した話