Playbook

Build / Playbook / Demo の設計ルール

内部デモ、外部デモ、Build、Playbookを増やすときの役割分担と導線ルール。

content-modelbuildplaybookdemooperations

なぜ整理するか

タスク管理・問い合わせ管理・Zustand Playground と小システムが増え、外部 Playground も扱い始めたことで、Build と Playbook の役割が混ざりやすくなりました。Admin Content Inventory で公開状態を確認する前提になったことも踏まえ、次の追加で構造が崩れないよう設計ルールを明文化します。

用語定義

Demo

実際に触る画面です。2 種類あります。

  • 内部 Demo: TOOLS BOX 内の route（例: /tasks）
  • 外部 Demo: Vercel など外部の URL（例: https://zustand-test-gamma.vercel.app/zustand-demo）

Build

完成例を見せるページです。「何ができるか」「どこへ行けるか」「どの Playbook と関係するか」を説明します。実装手順は書きません。

Playbook

作り方を説明するページです。フェーズ構成・実装手順・設計判断・完了条件・次に足せるものを説明します。完成例の紹介だけにはしません。

役割分担表

種類URL 例役割書くこと書きすぎないこと
Demo/tasks実際に触るUI・動作長い説明
External Demohttps://...外部で触る実験・Playground本体依存コード
Build/builds/tasks完成例何ができるか・導線細かい手順
Playbook/playbooks/tasks作り方手順・設計判断完成例だけの紹介

frontmatter ルール

Build

---
title: "タスク管理"
slug: tasks
summary: "..."
status: reviewed
tags:
  - tasks
demoPath: "/tasks"          # 内部 route のみ
externalDemoUrl: "https://..." # 外部 URL のみ（内部と混ぜない）
repo:
  url: "https://github.com/..."
  isPrivate: true        # private の場合のみ追加（省略 = public）
relatedPlaybooks:
  - tasks
relatedSamples:
  - example-sample
createdAt: "YYYY-MM-DD"
updatedAt: "YYYY-MM-DD"
---

ルール:

  • demoPath は内部 route のみ（/ 始まり）
  • externalDemoUrl は外部 URL のみ（https:// 始まり）
  • 内部 Demo と外部 Demo を同じフィールドに混ぜない
  • 外部 Demo URL がない場合は externalDemoUrl を省略する（空文字は入れない）
  • repo.url はコードを見る導線。GitHub の場合でも他のホストでも可
  • repo.isPrivate: true は private リポジトリの場合のみ設定する（省略 = public）。設定すると /builds 一覧と詳細ページで「Private Repo」と表示され、リンクは非表示になる

Playbook

---
title: "タスク管理画面を作る"
slug: tasks
summary: "..."
status: reviewed
tags:
  - tasks
createdAt: "YYYY-MM-DD"
updatedAt: "YYYY-MM-DD"
---

ルール:

  • 5 フェーズ構造を基本にする
  • 完成例リンク（Demo または外部 Demo）を冒頭に置く
  • Build リンクを冒頭に置く
  • 設計判断まとめを入れる
  • 次に足せるものを入れる

status 公開ルール

status公開用途
reviewed公開レビュー済み、一般公開
review_required非公開レビュー待ち
draft非公開作成中
deprecated非公開廃止済み
hidden非公開意図的に非表示

注意事項:

  • Admin Content Inventory で全コンテンツの公開状態を確認できる
  • review_required を暫定公開しない
  • 公開前に npm run validate / npm run build / npm run test:e2e を通す

hidden の扱い

非表示にしたいコンテンツは status: hidden で管理します。hidden: true のような専用フィールドは使いません。公開判定は status のみを見るため、フィールドを増やす必要がありません。

ルール:

  • status: hidden で非表示にする（hidden: true は使わない）
  • 公開かどうかは status === "reviewed" のみで判定する
  • hidden にするときは Admin Actions の status select で変更する
  • hidden toggle ボタンは実装しない

導線ルール

内部 Demo がある Build

demoPath: "/tasks"

/builds/[slug] ページに「デモを見る」ボタン（青）が表示されます。

外部 Demo がある Build

externalDemoUrl: "https://..."

/builds/[slug] ページに「外部デモを見る」ボタン（緑）が表示されます。

repo がある Build

repo:
  url: "https://github.com/..."

/builds/[slug] ページに「GitHub で見る」ボタン（グレー）が表示されます。

Playbook 連携

Build の relatedPlaybooks に slug を設定し、Playbook 本文にも Build へのリンクを置きます。双方向の導線が揃っている状態を保ちます。

既存コンテンツへの適用例

問い合わせ管理

項目値
Demo/contact-requests（内部）
Build/builds/contact-requests
Playbook/playbooks/contact-requests
demoPath/contact-requests

タスク管理

項目値
Demo/tasks（内部）
Build/builds/tasks
Playbook/playbooks/tasks
demoPath/tasks

Zustand Playground

項目値
External Demohttps://zustand-test-gamma.vercel.app/zustand-demo（外部）
Build/builds/zustand-playground
Playbook/playbooks/zustand-playground
Repohttps://github.com/kei-juness/zustand_test（現在 private）
externalDemoUrlhttps://zustand-test-gamma.vercel.app/zustand-demo
repo.urlhttps://github.com/kei-juness/zustand_test

Admin Content Inventory との関係

Admin Content Inventory（/admin/content）で Build・Playbook の公開状態を一覧確認できます。

  • reviewed 以外のコンテンツは公開 route に出ない
  • 追加・変更後は admin で公開状態を確認する
  • 将来的に externalDemoUrl の有無・repo の private/public 状態も admin で確認できると運用しやすい（現時点は拡張候補）

新規追加時のチェックリスト

内部 Demo を追加するとき

  • route がある（src/app/xxx/page.tsx）
  • Build に demoPath がある
  • Playbook がある（5 フェーズ構造）
  • E2E がある（tests/xxx-flow.spec.ts）
  • Admin で public 確認できる

外部 Demo を追加するとき

  • 外部 URL がある（デプロイ済み）
  • Build に externalDemoUrl がある
  • repo リンクがある場合は repo.url を設定
  • repo が private なら本文に注記
  • Playbook がある
  • 本体に直接組み込まない理由を Build または Playbook に書く

今後の改善候補

  • Admin Content Inventory に externalDemoUrl の有無を表示する
  • Build 一覧で内部 Demo / 外部 Demo をアイコンや badge で区別する
  • Playbook 一覧でカテゴリ（admin-ui / playground / patterns）を表示する
Playbook 一覧に戻る