フロント実装の前に、ブランドガイドをAIに先出しさせる

Claude CodeとCodexを1台で協業させる話から続く「個人開発を量産するための自動化基盤」シリーズです。今回は、フロント実装に入る前にブランドガイドをAIに生成させておく仕組みを作った話を書きます。

なぜガイドを「先出し」するのか

個人開発でUIを作るとき、よくやりがちなパターンがあります。「とりあえず実装してみて、後からデザインを整える」というものです。

その結果どうなるか。Claudeが生成するコードには必ずデフォルトのTailwind感が漂い、シャドウ・角丸・均一カードグリッドで埋め尽くされた、どこかで見たような画面が完成します。「クリーンでミニマル」という指示では、AIが選ぶのは常に最大公約数的なデザインです。

問題は情報の不均衡にあります。Claudeは指示がなければライブラリのデフォルト設定で実装します。コンポーネントに意志がなければ、フレームワークの意志で埋められます。

逆に言えば、実装前に意図を持ったブランドガイドを渡せば、AIの生成物は一変します。どのプロジェクトにも「これしかない」という方向を先に決めて、色・タイポ・モーション・グラデーション・グレインの意図を明示した状態で実装に入ると、生成コードの品質が桁違いに変わります。

その「先出し」を自動化したのが、~/dev/brand-kit/generate.sh です。

brand-kit の全体像

~/dev/brand-kit/ の構成はシンプルです。

brand-kit/
├── generate.sh        ← メインスクリプト
├── lib/
│   └── strip_fence.py ← コードフェンス除去ユーティリティ
├── output/
│   └── <slug>/        ← 生成物置き場
└── README.md

generate.sh にスラッグ（プロジェクト識別子）とブリーフ（1〜3行の概要）を渡すと、output/<slug>/ に最大4つのファイルが生成されます。

このガイド一式を実装者（Claude Code）に「このガイドに従って実装して」と渡すのが基本の使い方です。ガイドが先にあれば、Claudeは選択を迷わずに済みます。

実際の使い方

bash generate.sh <slug> "<概要・誰向け・何のページか>" [--refs] [--force]

架空の地域工務店案件で動かしてみます。

cd ~/dev/brand-kit
bash generate.sh marui-koumuten \
  "板橋区の地域工務店のリニューアルHP。50〜60代施主向け。職人の手仕事と地域実績で問い合わせを取る"

実行すると、順番に3ファイルが生成されます。

[brand-kit] guideline生成 (試行1/3)…
[brand-kit] ✓ brand-guideline.md
[brand-kit] tokens生成 (試行1/3)…
[brand-kit] ✓ tokens.css
[brand-kit] preview生成 (試行1/3)…
[brand-kit] ✓ preview.html
[brand-kit] 完了: ~/dev/brand-kit/output/marui-koumuten
  - brand-guideline.md
  - tokens.css
  - preview.html
  → preview.html をブラウザで確認。方向が違えば概要を変えて --force で再生成。

方向が気に入らなければ概要を書き直して --force を付けると全ファイルを作り直します。--refs を付けると WebSearch で実在の参考URLを集めた references.md も生成されます（その分だけ時間がかかります）。

設計の核心：なぜ3コールに分けるのか

generate.sh を読むと、guideline・tokens・preview をそれぞれ独立したコールで生成していることがわかります。内部の call() ヘルパはこうなっています。

# 1コール実行ヘルパ: $1=ラベル $2=プロンプト $3=allowedTools
call() {
  local label="$1" prompt="$2" tools="${3:-}" r=""
  local toolflag=(); [ -n "$tools" ] && toolflag=(--allowedTools "$tools")
  for attempt in 1 2 3; do
    echo "[brand-kit] $label (試行$attempt/3)…" >&2
    r=$(timeout "$T" "$CLAUDE" -p "$prompt" "${toolflag[@]}" --model "$MODEL" </dev/null 2>/dev/null)
    [ -n "$r" ] && ! printf '%s' "$r" | grep -qiE \
      'usage limit|rate limit|session limit|hit your session|request timed out' \
      && { printf '%s' "$r"; return 0; }
    sleep 3
  done
  return 1
}

なぜ1コールで全部出さないのか。理由は明確です。guideline.md だけで十分なボリュームがあり、そこに tokens.css と preview.html まで加えると出力が最大トークン数を超えて途中で切れます。CSSが閉じ括弧のないまま終わっていたり、HTMLが </body> を持たない壊れたファイルになったりします。

分割するもう一つのメリットは、後段のコールが前段の出力を入力として受け取れる点です。

GUIDE=$(head -c 6000 "$GFILE" 2>/dev/null)
# ↑ guideline の先頭6000文字を tokens 生成プロンプトに埋め込む

TOKENS=$(cat "$TFILE" 2>/dev/null)
# ↑ tokens.css 全文を preview 生成プロンプトに埋め込む

ガイドラインの意図がトークンに、トークンの値がプレビューに、一貫して引き継がれます。生成物がバラバラにならず、3ファイルが同じ世界観を共有できます。

また各ファイルはすでに存在すればスキップされます。

if [ "$FORCE" = 1 ] || [ ! -s "$TFILE" ]; then
  # tokens を生成
else
  echo "[brand-kit] = tokens.css (既存・skip)"
fi

これが冪等性の肝です。途中でタイムアウトしたり失敗したりしても、再実行すれば欠けたファイルだけが補完されます。brand-guideline.md が成功して tokens.css で失敗した場合、次の実行では brand-guideline.md をスキップして tokens.css から再開します。

踏んだ落とし穴

落とし穴①：</dev/null を忘れるとフリーズする

最初に claude -p をシェルスクリプトから呼び出したとき、コマンドが帰ってこない現象に遭遇しました。

原因は stdin です。claude -p はパイプされた入力を読もうとします。スクリプト内で単純に呼ぶと、Claude がターミナルの標準入力を待ったまま止まります。timeout で囲っていても、タイムアウトまでの間ずっとブロックされます。

# NG: stdin が閉じておらず、対話入力を待ってフリーズする
r=$(timeout 240 "$CLAUDE" -p "$prompt" --model sonnet)

# OK: </dev/null で stdin を閉じる
r=$(timeout 240 "$CLAUDE" -p "$prompt" --model sonnet </dev/null 2>/dev/null)

claude -p をシェルスクリプトや launchd から呼ぶときは </dev/null が必須です。対話的なターミナルで手打ちするときは問題ありませんが、バックグラウンドプロセスや自動化スクリプトでは必ず付けてください。Codex CLI のヘッドレス実行でも同じ罠があります（前回の記事参照）。

落とし穴②：セッション上限エラーで壊れたファイルが生成される

claude -p はセッション上限に達すると、CSSやHTMLではなくエラーメッセージを返します。

You've hit your session limit. Please wait before continuing.

このエラー文字列をそのまま tokens.css に書き出すと、後続の preview.html 生成がエラーテキストを「CSSトークン」として受け取り、ゴミHTMLを生成します。さらにそのままファイルに保存されてしまい、次回実行時には「既存・skip」でスキップされて壊れたままになります。

対策として call() ヘルパの中にガードを入れています。

[ -n "$r" ] && ! printf '%s' "$r" | grep -qiE \
  'usage limit|rate limit|session limit|hit your session|request timed out' \
  && { printf '%s' "$r"; return 0; }
sleep 3

空でなく、かつエラーパターンを含まない場合のみ出力を返します。エラーが返ってきた場合は3秒待ってリトライします。3回失敗すれば return 1 でコール失敗とし、ファイルへの書き込み自体を行いません。

落とし穴③：コードフェンスが応答に混入する

claude -p の応答には、指示しなくても ```css や ```html などのコードフェンスが混入することがあります。CSSファイルにコードフェンスが入ると、ブラウザにそのまま適用できません。

各コールの出力を lib/strip_fence.py にパイプして前処理しています。

# lib/strip_fence.py（抜粋）
t = sys.stdin.read().strip()

# ```lang ... ``` で囲まれている最大ブロックを優先
m = re.search(r'```[a-zA-Z]*\n(.*?)```', t, flags=re.DOTALL)
if m:
    print(m.group(1).strip() + "\n")
    sys.exit(0)

# フェンス無し: 最初の構造的な行以降を採用（前置き散文を落とす）
lines = t.splitlines()
start = 0
for i, ln in enumerate(lines):
    s = ln.lstrip()
    if s.startswith(("# ", "## ", ":root", "` を `preview.html` の先頭行に出力するよう指示が含まれています。これを `/design-sync` スキルで claude.ai のデザインシステム Project に同期すると、以後の Claude Design 生成がこのプロジェクトのトークンを継承して一貫します（`/design-sync` の利用には claude.ai へのログインが必要です）。

## モデルとタイムアウトの調整

`generate.sh` の冒頭に環境変数による設定があります。

```bash
CLAUDE="${CLAUDE:-~/.local/bin/claude}"
MODEL="${BRAND_KIT_MODEL:-sonnet}"
T="${BRAND_KIT_TIMEOUT:-240}"   # 1コールあたりのタイムアウト（秒）

速度優先なら haiku に切り替えられます。ガイドの思考の深さは落ちますが、生成が速くなります。

# haiku で速度優先
BRAND_KIT_MODEL=haiku bash generate.sh marui-koumuten "..."

# タイムアウトを伸ばす（低速ネット環境など）
BRAND_KIT_TIMEOUT=360 bash generate.sh marui-koumuten "..."

生成コストは claude -p（Claude MAX 枠）で完全無料です。APIキーや課金設定は不要です。

まとめ

• 実装前にガイドを先出しすることで、AI生成コードの脱テンプレ化が実現できます
• generate.sh は guideline → tokens → preview の3コール独立設計。1コールで全部出すと出力が途中で切れます
• claude -p はバックグラウンド実行時に**</dev/null が必須**です。忘れると stdin 待ちでフリーズします
• セッション上限エラーの文字列を grep で検出し、壊れたファイルへの書き込みをガードします
• strip_fence.py でコードフェンスと前置き散文を除去し、CSSとHTMLをそのまま使える形で保存します
• 各ファイルは存在すればスキップ——冪等性により再実行で欠けた分だけ補完されます
• tokens.css は oklch()・clamp()・feTurbulence グレインをすべてCSS変数として定義します。グラデーションは全サイトで3箇所限定
• 生成コストは Max 枠で完全無料です

---

Lily（@bokuwalily）― 個人開発者。Claude Code で自動化基盤を組みながら、iOSアプリやWebサービスを量産しています

• 作ったアプリは ポートフォリオ にまとめています📱
• 新着・開発の裏側は X @bokuwalily で発信しています🌍
• OSS: github.com/bokuwalily 🐙

皆さんの ❤️ やシェアが励みになります！