Cloudflare Workers 上で React、Hono、Drizzle ORM を使用した本番環境対応アプリケーションを構築するためのフルスタックテンプレート。
- React 19.2.7 - UI ライブラリ
- Vite 8.0.16 - ビルドツール
- React Router 7.17.0 - ルーティング
- TanStack Query 5.101.0 - データフェッチとキャッシング
- shadcn/ui(Base UI 1.6.0)/ Tailwind CSS 4.2.4 - アクセシブルな共通コンポーネントとスタイリング
- TypeScript 5.9+ - 型安全性
- Hono 4.12.25 - 高速で軽量な Web フレームワーク
- Drizzle ORM 0.45.2 - D1 用の型安全 ORM
- Cloudflare Workers - サーバーレスランタイム
- Cloudflare D1 - SQLite データベース
- Cloudflare KV - キーバリューストレージ
- Cloudflare R2 - オブジェクトストレージ
- pnpm 11.16.0 - 高速で効率的なパッケージマネージャー
- Node.js 24.12.0 LTS - 開発ツール用ランタイム
- Wrangler 4.57.0+ - Cloudflare CLI
- ESLint 9.39+ - リンティング(flat config)
- Prettier 3.7.4 - コードフォーマット
- Storybook 10.5.2 - 共通 UI のカタログ、操作、アクセシビリティ検証
- Dev Containers - 一貫した開発環境
- Serena MCP - セマンティックコード検索・編集(OpenCode 統合)
- agent-browser - AI エージェント向けブラウザ自動操作 CLI と OpenCode MCP
主要なソースと運用ディレクトリのみを示します。node_modules/ や生成キャッシュは省略しています。
cfreact-template/
├── mockups/
│ ├── AGENTS.md
│ ├── .storybook/
│ ├── tsconfig.json
│ └── main/
│ └── src/
│ ├── App.tsx
│ └── App.stories.tsx
├── apps/
│ ├── core/
│ │ ├── src/
│ │ ├── typespec/
│ │ ├── drizzle/
│ │ └── wrangler.toml
│ └── main/
│ ├── src/
│ │ ├── frontend/
│ │ │ ├── app/
│ │ │ ├── domain/
│ │ │ └── api/
│ │ └── backend/
│ │ ├── entry/
│ │ ├── app/
│ │ ├── generated/
│ │ ├── modules/
│ │ ├── platform/
│ │ └── types/
│ ├── typespec/
│ └── wrangler.toml
├── packages/
│ ├── core-sdk/
│ │ └── src/
│ ├── ui/
│ └── build-config/
├── infra/
│ └── terraform/
├── openspec/
├── tests/
├── scripts/
├── docs/
├── .devcontainer/
├── .github/
├── pnpm-workspace.yaml
└── package.json
| パス | 役割 |
|---|---|
mockups/<app>/ |
公開アプリごとの統合ReactモックとStorybook表示例 |
apps/main/ |
React、Hono、TypeSpecを一体配備する公開システム |
apps/main/src/frontend/app/ |
Reactのアプリ起動、ルーター、画面 |
apps/main/src/frontend/domain/ |
TanStack Query hooksとprovider |
apps/main/src/frontend/api/ |
main OpenAPI生成SDKとAPIラッパー |
apps/main/src/backend/ |
main WorkerのHono入口と公開API |
apps/main/typespec/ |
main公開API契約の正 |
apps/core/ |
非公開core Worker、共有ドメイン、Repository、D1 |
apps/core/typespec/ |
core内部API契約の正 |
packages/core-sdk/ |
core OpenAPIから生成するサーバー専用SDK |
apps/core/drizzle/migrations/ |
coreが所有するD1マイグレーション |
packages/ui/ |
Base UIベースの共通components/hooks |
infra/terraform/production/ |
productionのD1、KV、R2を管理するTerraform設定 |
apps/には、公開・非公開を問わず独立して起動・配備するシステムを置きます。packages/には、各システムへ組み込む共有ライブラリや共通のビルド設定を置きます。現在の配備対象は、公開アプリのapps/mainと内部サービスのapps/coreです。
React + Hono + TypeSpecのシステムはapps/<name>へ一つのworkspace packageとして追加し、dev、build、check、gen:api、deploy:dry-runを実装します。TypeSpecからそのシステムのHono経路とfrontend SDKを生成し、共有ドメインの操作や問い合わせが必要なHandlerまたはServiceだけが@cfreact-template/core-sdkを利用します。配備対象は.release/deploy-targets.jsonへ明示登録します。
Next.jsなどの一体型システムもapps/<name>へ置き、ルートから見える同じscript契約だけを揃えます。内部構造をReact + Honoへ無理に合わせず、外部APIを所有する場合だけTypeSpecを追加します。
各公開システムは apps/<name> にReact、Hono、TypeSpecをまとめ、一つのWorkerとオリジンへ配備します。現在のapps/mainでは、ブラウザーがmain TypeSpec生成SDKでmain Honoを呼び、main Honoがcore TypeSpec生成の@cfreact-template/core-sdkで非公開core Workerを呼びます。
React -> main SDK -> main Hono -> core SDK -> core Hono -> Service -> Repository -> D1
apps/mainは公開契約、画面固有の応答写像、hello、healthを所有します。apps/coreは共有ドメイン、usersのService、Repository、Drizzleスキーマ、D1、メール、マイグレーションを所有します。mainバックエンドはcore実装を直接インポートせず、packages/core-sdkだけを利用します。
各公開アプリは、そのアプリのユースケースを所有します。ユースケースは、想定利用者、その利用者が置かれた状況、目的、得られる成果によって識別します。想定利用者が異なる場合は、利用するドメイン操作や処理順序が同じでも別のユースケースです。
想定利用者、状況、目的、成果まで同じユースケースが複数の公開アプリに存在する場合は、本当に別アプリとして分ける必要があるかを確認します。別アプリとして提供することが確認済みの要望であれば、その境界を維持します。実装の重複だけを理由にアプリを統合したり、ユースケースをcoreへ移したりしません。
core APIは、各アプリのユースケースから利用されるドメイン境界です。アプリ固有の利用者作業やワークフローではなく、ドメインの概念、状態、操作、問い合わせ、不変条件、状態遷移、整合性を提供します。異なるユースケースが同じcoreドメイン操作を利用することは、ドメインを共有する自然な結果です。
core APIは現在のcreateUser、getUser、listUsersのようにドメインの語彙で定義します。insertUserRow、updateUserFields、汎用的なsaveやfindのように永続化操作をそのまま公開しません。Repositoryを遠隔公開しないことはcore APIの目的ではなく、ドメイン境界を維持した結果です。core APIのDTOはデータベース行やDrizzleスキーマではなく、ドメイン契約を表します。
coreのServiceがドメイン操作、不変条件、状態遷移、副作用調整を所有します。純粋な補助処理は、同じリソースのService内または既存のbackend-module-supportへ置きます。
main固有の判断、複数のcore操作、外部サービスを組み合わせるユースケースは、mainのbackend-module-serviceへ置きます。mainのServiceはcore SDKや外部クライアントを構成起点から受け取り、HTTPに依存しない結果をHandlerへ返します。main固有の判断がなく、一つのcore操作を公開契約へ変換するだけなら、現在のusersと同様にHandlerからcore SDKを直接呼び、不要なServiceを追加しません。
単純な公開変換: route -> main Handler -> core SDK
main固有ユースケース: route -> main Handler -> main Service -> core SDK / 外部クライアント
coreドメイン処理: route -> core Handler -> core Service
core永続化: core Service -> Repository -> Schema / Platform
複数のドメイン操作や外部サービスを組み合わせる順序は、原則としてアプリのユースケースが所有します。ただし、一連の変更がcoreドメインの不変条件を守るために原子的でなければならない場合は、mainから複数回呼び出さず、一つのcoreドメイン操作として提供します。coreはアプリ固有のフローを知らず、mainはcore内部のトランザクションを再現しません。
core SDKは実行時に基底URL、Bearerトークン、Web標準fetchを受け取ります。現在のCloudflare構成ではCORE_API Service Bindingのfetchを渡しますが、通信契約自体はCloudflareへ依存しません。片側または両側を別の実行基盤へ置く場合も、同じTypeSpec契約を証明書検証済みHTTPSとBearer認証で実装します。
| バックエンド | core | 通信方式 |
|---|---|---|
| Cloudflare | Cloudflare | Service Binding + Bearer認証 |
| Cloudflare | Cloudflare外 | HTTPS + Bearer認証 |
| Cloudflare外 | Cloudflare | coreのHTTPS経路 + Bearer認証 |
| Cloudflare外 | Cloudflare外 | HTTPS + Bearer認証 |
main TypeSpec生成経路とcore TypeSpec生成経路は別の契約です。main Handlerはcoreの状態番号とDTOをmain公開契約へ明示的に写像し、core内部のエラー本文や実装型をブラウザーへ透過しません。生成サーバーファイルとSDKは手編集せず、スマートハンドラーの本体だけを実装します。
外部パッケージがHTTP配下経路を所有する場合は、対象Workerの最上位Honoへ具体的にマウントします。外部経路はTypeSpecへ複写せず、製品API向けCORS、400応答整形、生成応答検証の対象外にします。既存のWorker-first接頭辞外へ置く場合はWranglerのrun_worker_firstにも基底パスを追加します。空のプラグイン登録表や動的探索は作りません。
予測して処理する失敗はcore内部でResultとしてRepositoryからService、Handlerへ渡し、core HTTP契約の安全な{ code, message }へ変換します。main Handlerはcore SDK結果をmain TypeSpec契約へ再変換します。core通信の認証失敗、通信失敗、未知の状態番号、生成スキーマ違反は、利用者の認証状態として公開せず、内部原因を記録して固定500を返します。
生成された応答検証処理を使うハンドラーでは、guardResponseValidation が検証処理の外側で最終応答を確認します。検証詳細を含む不安全な 400 応答は例外となり、app.onError が原因を記録して固定の 500 応答を返します。ユーザー作成の 201 応答は生成された CreateUserResponse で明示的に解析し、入力検証が返す不安全な 400 応答は app が固定の INVALID_REQUEST 応答へ置き換えます。
ユーザーのメールアドレス重複は、users.email の一意制約と ON CONFLICT DO NOTHING の結果で判定します。データベースのエラー文は解析せず、重複を USER_EMAIL_ALREADY_EXISTS の 409 応答へ変換します。
- Docker(Dev Containers 用)
- VS Code(Dev Containers 拡張機能付き)
または手動セットアップの場合:
- Node.js 24.12.0 以降
- pnpm 11.16.0 以降
- Cloudflare アカウント(デプロイ用)
- Terraform 1.16(長期Cloudflare資源の管理用)
-
リポジトリをクローン:
git clone <your-repo-url> cd cfreact-template
-
VS Code で開く:
code . -
コンテナで再度開く:
Cmd+Shift+P(Mac)またはCtrl+Shift+P(Windows/Linux)を押す- "Dev Containers: Reopen in Container" を選択
- コンテナのビルドと依存関係のインストールを待つ
注意: Git 設定(
.gitconfig)と認証情報は VS Code によって自動的に共有されます。devとstorybookを起動し、依存導入はComposeの初期化処理で一度だけ行います。VS Codeのポート一覧からApp Mock Storybookを開きます。編集・計画はOpenCode、モックの確認はStorybookで行います。詳細はモック確認環境を参照してください。 -
productionのCloudflareリソースをTerraformでセットアップ:
terraform -chdir=infra/terraform/production init -backend-config=/path/to/production.tfbackend terraform -chdir=infra/terraform/production plan terraform -chdir=infra/terraform/production apply
HCP Terraformのremote backendを使用し、Cloudflare API tokenは環境変数で渡します。Terraform stateやbackend設定をGitへ追加しません。
-
ローカルcore通信用のBearerトークンを設定:
export CORE_API_TOKEN="$(node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('base64url'))")"
mainとcoreを起動する同じシェルへ設定します。
.envや.dev.varsへ保存する場合はGitへ追加しません。 -
ローカルD1へマイグレーションを適用:
pnpm migrate:generate pnpm migrate:apply
productionの未適用マイグレーションはDeploy Workflowがcore配備前に一度だけ適用します。
-
開発サーバーを起動:
# フロントエンドとバックエンドの両方を起動 pnpm dev:all # または個別に起動: pnpm dev:backend # mainとcoreのWorker http://localhost:8787 pnpm dev:frontend # React http://localhost:5173 # 共通 UI catalog を起動 pnpm storybook # Storybook http://localhost:6006
-
アプリケーションにアクセス:
- フロントエンド: http://localhost:5173
- バックエンド API: http://localhost:8787/api/v1
- Storybook: http://localhost:6006
- Drizzle Studio:
pnpm migrate:studio
apps/main/typespecは公開main API、apps/core/typespecは非公開core APIの正です。各TypeSpecからOpenAPI、Hono経路、スマートハンドラー、利用側SDKを生成します。
# 両TypeSpec -> 両Honoサーバー -> frontend SDK + core SDK
pnpm gen:api-sdk個別に実行する場合:
pnpm gen:openapi
pnpm gen:backend
pnpm gen:core生成対象は両OpenAPI、両Workerのgenerated/api/**とスマートハンドラー、main frontend SDK、packages/core-sdk/src/generated/client.tsです。生成物を手で編集せず、TypeSpecまたはOrval設定を変更してから再生成してください。
pnpm check:codegenは両契約を再生成し、両Handler一覧、全生成物のGit管理、シンボリックリンク、生成差分を検査します。
前提条件:
- Node.js 24.12.0 以降
- Python 3.11 以降(Serena MCP 用)
- agent-browser CLI(ブラウザ自動操作用。Dev Container では Chrome for Testing または OS Chromium とあわせて自動導入)
-
依存関係をインストール:
corepack enable pnpm installpnpm-workspace.yamlのminimumReleaseAge: 4320により、npm 公開から72時間未満のパッケージはインストール対象から外れます。リリース前の依存追加・更新は、少なくとも72時間前に完了してください。 -
Wrangler をグローバルインストール:
npm install -g wrangler@4
-
uv をインストール(任意、Python ツール導入用):
# macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
-
OpenCode CLI をインストール(オプション、AI 支援開発用):
npm install -g opencode-ai@latest
-
agent-browser CLI とブラウザをインストール(AI ブラウザ操作用):
sh .devcontainer/scripts/install-agent-browser.sh
-
方法 1 のステップ 4-8 に従ってください。
注意: Dev Container には、これらすべてのツールがプリインストールされています(Node.js 24、Python 3、pnpm、Wrangler、uv、OpenCode CLI、OpenSpec CLI、agent-browser CLI、Chrome for Testing または OS Chromium)。
プロダクトの方向付けと計画は OpenCode、計画完了後の実装は OpenCode で進めます。OpenSpec の仕様は振る舞いの正であり、確認済み要求を意味の根拠とします。
共有プロジェクトスキルは .agents/skills/ に置き、OpenCode のプロジェクト向け Agent Skills 互換検出で読み込みます。OpenCodeは同じリポジトリルートのスキルを使用します。エージェント定義は .opencode/agents/、コマンド定義は .opencode/commands/ に置きます。
-
OpenCode を設定:
opencode auth
-
OpenSpec 設定を確認:
pnpm exec openspec list -
計画を実装へ引き渡す: OpenCode で要求と必要なモックを具体化し、計画完了後に OpenCode またはプライマリエージェント
openspec/applierへ変更識別子を伝えます。詳細はdocs/change-operation.mdを参照してください。
テンプレートは Vite のプロキシを使用して、フロントエンドからの /api リクエストを Workers 開発サーバーに転送します。
バックエンドを起動するシェルには、mainとcoreで共有する開発用CORE_API_TOKENを設定してください。値は利用環境ごとに生成し、ブラウザーへ公開しません。
# ターミナル 1: Workers バックエンドを起動
pnpm dev:backend
# ターミナル 2: React フロントエンドを起動
pnpm dev:frontend
# または両方を同時に起動
pnpm dev:allpnpm dev:backend で Wrangler を起動している状態で、POST /api/v1/users を叩くと
env.EMAIL.send() が呼ばれ、Wrangler がローカルに .eml ファイルを出力します。
-
apps/core/wrangler.tomlのEMAIL_FROMとEMAIL_TOを開発用の値に更新 -
サーバーを起動
pnpm dev:backend
-
別ターミナルでユーザー作成 API を実行
curl --request POST 'http://localhost:8787/api/v1/users' \ --header 'Content-Type: application/json' \ --data '{"name":"Email Test User","email":"email-test@example.com"}'
-
pnpm dev:backend側のログに出る.emlファイルパスを確認
本番で送信を有効化する場合は Cloudflare Email Routing を有効化し、EMAIL_FROM と EMAIL_TO
を運用値に変更してください。
| スクリプト | 説明 |
|---|---|
pnpm dev:frontend |
Vite 開発サーバーを起動(フロントエンド) |
pnpm dev:backend |
Wrangler 開発サーバーを起動(バックエンド) |
pnpm dev:all |
両方のサーバーを同時に起動 |
pnpm storybook |
共通 UI の Storybook 開発サーバーを起動 |
pnpm build |
フロントエンドとバックエンドの両方をビルド |
pnpm build:storybook |
Storybook の静的サイトをビルド |
pnpm check |
TypeScript 型チェックを実行 |
pnpm --filter @cfreact-template/main check:backend |
単一 tsconfig でバックエンドを型検査する |
pnpm gen:api-sdk |
TypeSpec から API 生成物を再生成する |
pnpm lint |
UI 再利用、ESLint、OpenSpec、サプライチェーンを検証 |
pnpm lint:ui-reuse |
公開 UI catalog と UI/app 間のコード clone を検証 |
pnpm lint:supply-chain |
pnpm のサプライチェーン防御設定を検証 |
pnpm format |
Prettier でコードをフォーマット |
pnpm format:check |
CSS/YAML を含むフォーマット差分を検証 |
pnpm test:run |
React/UI試験と純粋なSDK・業務・リリース規則試験を実行 |
pnpm test:frontend |
Reactの顧客向けUI試験を実行 |
pnpm test:storybook |
全 Story を desktop/mobile・Light/Dark で検証 |
pnpm test:e2e |
migration 済み E2E 専用 D1 を使う Playwright を実行 |
pnpm check:codegen |
API 生成差分とバックエンドのハンドラー一覧を検証 |
pnpm migrate:generate |
Drizzle マイグレーションを生成 |
pnpm migrate:studio |
Drizzle Studio を開く |
pnpm deploy |
Cloudflare Workers にデプロイ |
pnpm changeset |
リリース内容とSemVer影響を記録 |
pnpm test:release |
純粋で決定的なリリース規則試験を実行 |
CIは設定済みのPlaywrightブラウザを導入し、pnpm test:runでアプリのReact UI、packages/*/vitest.unit.config.tsで定義する各パッケージのReact/UI、純粋なcore SDK通信規則、バックエンド業務・リリース規則を一度だけ検証します。続けてpnpm test:storybook、pnpm test:e2e、pnpm build:storybookを実行し、共通UIの実ブラウザ状態、高価値の顧客作業、Storybookの静的ビルドを必須検証にします。
このテンプレートは、データベースマイグレーションに Drizzle Kit を使用します。
現在の users テーブルは apps/core/src/modules/users/users.schema.ts が所有し、apps/core/drizzle.config.ts はこのファイルをスキーマ入力にします。所有場所の変更で既存履歴を作り直さず、apps/core/drizzle/migrations/0000_daily_dorian_gray.sql から続く同じマイグレーションストリームを維持します。
-
スキーマを変更:
- 対象リソースの
apps/core/src/modules/<resource>/*.schema.tsを編集
- 対象リソースの
-
マイグレーションを生成:
pnpm migrate:generate
-
ローカルでマイグレーションを適用:
pnpm migrate:apply
-
本番環境でマイグレーションを適用:
Deploy Workflowが
wrangler d1 migrations applyをcore配備前に実行します。手動配備でも同じ順序を維持してください。 -
Drizzle Studio でデータベースを表示:
pnpm migrate:studio
GET /api/v1/hello- Hono と Workers からの挨拶を返す
GET /health- Worker が応答可能であることを返す
GET /api/v1/users- すべてのユーザーを一覧表示POST /api/v1/users- 新しいユーザーを作成GET /api/v1/users/:id- ID でユーザーを取得
詳細な API 仕様は apps/main/typespec/openapi/openapi.json を参照してください。
developのCIが成功すると.github/workflows/prepare-release.ymlがreleaseとRelease PRを作成または更新します。Release PRがmerge commitでmainへ取り込まれると、.github/workflows/release.ymlがvX.Y.Ztag、GitHub Release、main -> develop同期PRを処理します。merge済みのreleaseとsync/main-to-developは.github/workflows/cleanup-release-branches.ymlが自動削除し、次回処理時に最新のbase branchから再作成します。
.github/workflows/release.ymlは新しいvX.Y.ZtagとGitHub Releaseを作成した後、.github/workflows/deploy.ymlへtagを明示してdispatchします。production EnvironmentのCloudflareとHCP Terraform credentialsが設定されている場合だけ、Terraform state確認、migration、core、mainの順で配備します。credentialsがなければデプロイだけを省略します。
Changesets、branch運用、ActionsのPR作成権限、ruleset、Production Environmentを含む生成先repositoryの設定はdocs/release-operations.mdを参照してください。リリース認証はrepository固有のGITHUB_TOKENだけを使い、GitHub App、PAT、Client ID、private keyは不要です。
productionの長期資源はTerraform、WorkerコードとBindingはWrangler、D1 migrationはapps/coreが所有します。同じCloudflare資源をTerraformとWranglerの双方から作成しません。
GitHubのproduction Environmentには次を設定します。
| 種別 | 名前 | 用途 |
|---|---|---|
| Secret | CLOUDFLARE_API_TOKEN |
migrationとWorker配備 |
| Secret | CORE_API_TOKEN |
mainからcoreへの内部Bearer認証 |
| VariableかSecret | CLOUDFLARE_ACCOUNT_ID |
productionのCloudflare account ID |
| Secret | HCP_TERRAFORM_TOKEN |
HCP Terraform remote stateの読み取り |
| Secret | TERRAFORM_BACKEND_CONFIG |
remote backendのorganization/workspace |
| Variable(任意) | WRANGLER_ENVIRONMENT |
未設定時はproduction |
通常リリースはcore、mainの順にすべて配備します。手動再配備ではcoreまたはmainを選択でき、mainを選ぶと同じタグのcoreも先に配備されます。
-
Cloudflare にログイン:
wrangler login
-
アプリケーションをビルド:
pnpm build
-
依存関係のリリース猶予を確認:
pnpm lint:supply-chain
依存追加・更新を含むリリースでは、対象パッケージの npm 公開から72時間以上経過していることを確認してください。
-
Terraform stateからWrangler設定を生成:
terraform -chdir=infra/terraform/production output -json > .wrangler/terraform-outputs.json pnpm release:render-wrangler -- --terraform-outputs .wrangler/terraform-outputs.jsonこれにより
apps/core/wrangler.release.tomlとapps/main/wrangler.release.tomlが生成されます。どちらもGit管理しません。 -
migrationと配備:
pnpm --filter @cfreact-template/core exec wrangler d1 migrations apply DB --config apps/core/wrangler.release.toml --env production --remote pnpm release:deploy-targets -- --targets all --environment production --secrets-file /secure/path/worker-secrets.json--secrets-fileで指定するファイルにはCORE_API_TOKENだけをJSONまたはdotenv形式で保存し、権限を所有者だけに限定して配備後に削除します。GitHub ActionsではDeploy Workflowがこの一時ファイルを作成して除去します。
GitHub Actionsからリリースする場合は、Cloudflare認証情報と256ビット以上のランダムなCORE_API_TOKENをproduction Environmentへ設定します。Deploy Workflowは同じ値をmainとcoreのWorker Secretへ登録します。ActionsのPR作成権限を含む全設定はdocs/release-operations.mdを参照してください。
メール送信元と宛先はapps/core/wrangler.toml、mainのKV/R2とcoreのD1は各Wrangler Bindingで設定します。資源IDはTerraform outputから一時設定へ注入し、公開branchへ保存しません。CORE_API_TOKENは平文のvarsやTerraform stateへ保存せず、利用環境のSecret管理から両バックエンドへ注入します。
変更運用の一次資料は docs/change-operation.md です。すべての変更で、次の三軸を独立に選びます。
Operation Lane:DIRECT、BEHAVIOR、ARCHITECTUREUX Mode:NONE、CONTINUITY、SHAPEReview Depth:STANDARD、DEEP
DIRECT は通常、観測可能な振る舞いも物質的な内部構造も変えない作業です。加えて、このリポジトリ自身の再利用可能なテンプレート保守で、現在のサンプルアプリケーションの振る舞いを維持する変更もDIRECTとしてOpenSpecを作成しません。この例外はテンプレートから生成されたプロダクトリポジトリへ引き継ぎません。BEHAVIORはbehavior-change、ARCHITECTUREはarchitecture-changeを使用します。
OpenSpec の仕様は、確認済み要求を意味の根拠とする、利用者または外部契約から観測できる振る舞いの正です。OpenCode のプライマリエージェントが要求と統合モックを担当し、サブエージェント openspec/planner が提案・仕様・作業パッケージの範囲と該当する skip_specs 設定、openspec/architect が統合設計と計画の最終確認を担当します。
- 主仕様は
openspec/specs/**/spec.mdに置きます。 - 活動中の差分仕様は
openspec/changes/*/specs/**/spec.mdに置きます。 behavior-changeは提案、差分仕様、作業パッケージを管理します。architecture-changeは提案、物質的な設計判断、作業パッケージを管理し、観測可能な振る舞いも変更する場合だけ差分仕様を持ちます。- 観測可能な振る舞いを変更しない
architecture-changeは.openspec.yamlにskip_specs: trueを設定し、差分仕様、Requirement、Scenarioを作成しません。 - Requirement と Scenario には観測可能な終端状態だけを記載します。
tasks.mdは粗い作業パッケージ台帳とし、ファイル、補助処理、試験階層ごとの詳細計画を置きません。
実装時は、現在の作業パッケージ、リポジトリの実態、直前の検証結果を基に、ファイル・補助処理・試験の詳細を段階的に決めます。
Scenario見出しは(USER-MGMT-S001)のような安定した識別子で終えます。追跡はPlaywright E2E試験からScenarioへの一方向であり、試験題名から[USER-MGMT-S001]のように既存Scenarioを参照できます。Scenarioごとの自動試験は要求せず、純粋な単体試験、Reactの顧客向けUI試験、Storybookブラウザ試験はScenario識別子を参照しません。
許可する自動試験は、価値の高い顧客作業を通すPlaywright E2E、顧客成果へ影響する決定的な規則の純粋な単体試験、利用者に見える描画と操作を保全するReact UI試験、顧客向け共通UIを実ブラウザで保全するStorybook試験です。React UI試験では目的に応じてjsdom、MSW、Testing Libraryを利用できます。Workerd固有、実データベース、接続、バックエンドHTTP・OpenAPI契約、ファイルシステム・子プロセスを使うツール自己試験は作成しません。
既定の検査は、活動中差分の構造、識別子の重複、Change間の競合と、Playwright E2E試験題名にあるScenario参照の有効性を確認します。一つのChangeを確認した後、相互作用の最終確認として引数なしの検査も実行します。
node scripts/openspec/verify-scenario-coverage.mjs --change <change-id>
node scripts/openspec/verify-scenario-coverage.mjsこのリポジトリは @fission-ai/openspec 1.11.0、openspec/config.yaml、二つの変更スキーマを使用します。pnpm gen:openspec は new、continue、update、apply、verify、sync、archive のカスタムプロファイルで、公式の --tools agents により .agents/skills/openspec-*/SKILL.md を、--tools opencode により .opencode/commands/opsx-*.md のコマンドだけを再生成します。生成物は手編集しません。手書きの補足スキルは .agents/skills/openspec/** の入れ子構造を維持します。変更は運用区分に対応する --schema を付けた openspec new change で作成します。
pnpm gen:openspec
pnpm exec openspec new change <change-id> --schema behavior-change
pnpm exec openspec list
pnpm lint:openspecOpenCode で所有者に確認できた内容を随時 request.md へ保存します。Request-Status: CONFIRMED は現在の保存内容がすべて確認済みであることを示し、明確な所有者の発言自体が即時更新の確認証拠になります。
NONE はモック不要、CONTINUITY は既存製品の証拠を参照します。SHAPE は要求とモックを同時に具体化し、確認済み要求と所有者が受け入れたモックの相互対応、採用理由、整合性を確認して提案を収束させます。proposal.md の Design Source には OpenCode が読めるパスまたは安定した識別子、対象画面・操作の流れ・状態、受け入れと採用理由を記録します。
プライマリエージェントは、要求・モック、openspec/planner の提案・仕様、architecture-change での openspec/architect の DESIGN、計画担当者の作業パッケージ、設計担当者の READINESS_REVIEW の順に進行します。behavior-change は設計ファイルを持たず、提案・仕様・作業パッケージの完成後に同じ最終確認を受けます。実装開始には最終確認の APPROVED が必要で、CLI 上の成果物完成や計画担当者の自己点検だけでは承認になりません。重要な計画修正後は影響する成果物を再確認します。
生成スキルと入口コマンドにもこの委任境界を適用します。主仕様の同期は openspec/planner へ委任し、アーカイブの進行はプライマリエージェントが担当します。
OpenCode と openspec/applier は計画完了した変更を実装し、計画ファイルでは tasks.md の進捗だけを更新します。要求の UIモック参照 と提案の Design Source から、採用済みの mockups/main/src/App.stories.tsx#Home などのアプリ・画面・状態と mockups/<app>/src/** の React ソースを照合します。UI は対象の apps/<app> と共通 UI に、PRODUCTION_UI -> WIRING -> POLISH -> REVIEW の順に忠実に正式実装します。製品判断の不足や計画の矛盾があれば PLANNING_REQUIRED を返し、OpenCode で解決します。
新規プロダクトでは利用の流れ全体とモックを形にし、成果ごとの複数の変更へ分けます。共有判断が変われば影響する変更を再評価し、独立して計画完了したまとまりから実装へ引き渡します。
このテンプレートには、OpenCode と統合できる Serena MCP Server が設定されています。Serena は Language Server Protocol (LSP) を使用して、IDE 並みのコード理解機能を提供します。
- セマンティック検索: シンボルレベルでのコード検索
- 定義へのジャンプ: "Go to Definition" 機能
- 参照の検索: "Find All References" 機能
- インテリジェント編集: コンテキストを理解したコード編集
- メモリ管理: コードベースのコンテキストを保持
OpenCode などから以下のように使用できます:
# プロジェクトをアクティベート(初回のみ)
"Activate the current dir as project using serena"
# セマンティック検索
"Find all references to the User type using serena"
"Show me the definition of apiClient using serena"
"Find all usages of the createUser function using serena"Serena のダッシュボードにアクセスして、ログやプロジェクト情報を確認できます:
http://localhost:24282/dashboard
.serena/project.yml: プロジェクト固有の設定
デフォルトでは read_only: true に設定されており、ファイルの読み取りのみが可能です。ファイル編集機能を有効にする場合は、.serena/project.yml で read_only: false に変更してください。
詳細については、https://github.com/oraios/serena を参照してください。
このテンプレートには、AI エージェントがローカルの Vite アプリや外部サイトを操作するための agent-browser が設定されています。Dev Container では agent-browser CLI とブラウザを自動導入し、OpenCode からは .opencode/opencode.json の agent-browser mcp 経由で利用できます。Linux ARM64 では Chrome for Testing が提供されないため、Dockerfile で導入した OS Chromium を利用します。
# ローカルフロントエンドを開く
agent-browser open http://localhost:5173
# AI が参照しやすいアクセシビリティツリーを取得
agent-browser snapshot
# スクリーンショットを保存
agent-browser screenshot page.png
# ブラウザセッションを閉じる
agent-browser closeOpenCode では .opencode/opencode.json に agent-browser mcp が登録されています。設定変更後は OpenCode を再起動すると、ブラウザ操作、スナップショット取得、スクリーンショット取得などを MCP ツールとして利用できます。
agent-browser の state ファイルや認証情報を含むエクスポートファイルはセッショントークンを含む可能性があります。agent-browser state save などで作成した認証状態ファイルはリポジトリへ追加せず、必要がなくなったら削除してください。
共通 UI catalog は packages/ui/stories/ にあり、1つの公開対象につき1つの *.stories.tsx で管理します。pnpm storybook で開発サーバーを起動し、pnpm build:storybook で静的出力、pnpm test:storybook で全 Story の interaction と accessibility を desktop/mobile・Light/Dark の4環境で検証します。
Story は製品コードへ import せず、@cfreact-template/ui/* の公開 subpath から対象を直接 import してください。Storybook 固有の依存境界と公式推奨 ESLint ルールは eslint.config.js で強制されます。
pnpm lint:ui-reuse は UI source、package export、root barrel、Story の対応を検査し、Storybook catalog を再実装検知にも利用します。frontend から Base UI などの内部 primitive を直接利用すること、app で公開 UI と同名の値を宣言・再 export すること、packages/ui の実装を app へコピーすることは pnpm lint で失敗します。
OpenCodeは公開アプリごとの統合Reactモックをmockups/<app>/src/で作成します。App.tsxが操作の流れを持ち、App.stories.tsxの引数で初期画面と状態を選びます。共通UIの公開サブパス、固定データ、ローカル状態を使います。
標準の実行環境はDev Containerです。pnpm storybook:hostがプロジェクト選択と開発プレビューを提供し、pnpm storybook:mockupはモック用Storybookを直接起動します。pnpm build:mockupでGit管理対象外のmockups/distへビルドします。共通のmockups/.storybookとmockups/tsconfig.jsonは、共通UIのTailwind CSS 4とReact Compiler設定を再利用します。
要求のUIモック参照と提案のDesign Sourceには、mockups/main/src/App.stories.tsx#Homeやmockups/main/src/App.stories.tsx#UsersErrorのような定義ファイルと表示例の参照を記録します。OpenCodeは所有者確認済みの要求とモックを一緒に更新し、デスクトップとモバイルの実ブラウザで照合します。各アプリの画面・状態と変更は多対多で対応し、共有UIを更新した場合は影響する要求とモックを確認します。変更のアーカイブ後もmockups/を保持し、製品実装は正式なアプリと共通UIを利用します。
起動・ホスト設定はStorybookによるモック確認、編集規則はmockups/AGENTS.mdを参照してください。
共通デザイン token は packages/ui/styles/globals.css、Tailwind v4 の Vite plugin 設定は apps/main/vite.config.ts で管理します。shadcn/ui registry 設定は packages/ui/components.json にあり、base-nova style と @base-ui/react の primitive を使用します。既存の共通コンポーネントは packages/ui/components/ から import できます。
Calendar は mode="range" で範囲日付選択に対応します。OS 標準の picker や form semantics が必要な場合は NativeSelect を、列定義ベースの一覧には DataTable を利用してください。
apps/main/src/frontend/app/pages/にページコンポーネントを作成apps/main/src/frontend/app/router.tsxにルートを追加
apps/main/typespec/src/routes/**と必要なモデルを更新pnpm gen:api-sdkを実行- 生成された
apps/main/src/backend/generated/api/<resource>/のリソース経路を確認 apps/main/src/backend/modules/<resource>/handlers/のスマートハンドラー本体だけを実装apps/main/src/backend/app/server.tsへリソース入口を追加する必要がある場合はappの構成起点として登録pnpm check:codegenでハンドラー一覧と全生成差分を検証
リソースのパス、HTTP メソッド、スキーマ、検証処理は TypeSpec と生成器が所有します。手書きの Hono 経路を別に作ったり、生成された経路ファイルを直接編集したりしません。
共有ドメインの操作や問い合わせを追加する場合はapps/core/typespecとcoreのHandler、Serviceを先に変更し、生成されたcore-sdkをmainのHandlerまたはServiceから利用します。main固有の複合ユースケースはmainのServiceへ置きます。外部パッケージが経路全体を所有する場合だけTypeSpecの対象外とし、最上位Honoへ明示的にマウントします。
このテンプレートには、一貫したコード標準を維持するための自動コード品質ツールが含まれています。
Git フックは Husky を介して自動的に設定されます:
- pre-commit: ステージされたファイルに lint-staged を実行
- commit-msg: コミットメッセージ形式を検証
コミット用にステージされたファイルのみをリント・フォーマット:
# pre-commit で自動実行
pnpm lint-staged.lintstagedrc.json の設定:
- TypeScript/JavaScript ファイル: ESLint 修正 + Prettier フォーマット
- CSS/JSON/Markdown/YAML ファイル: Prettier フォーマット
このプロジェクトは Conventional Commits を使用:
# 有効なコミットメッセージ形式
feat: 新機能を追加
fix: ユーザー認証のバグを修正
docs: セットアップ手順で README を更新
style: prettier でコードをフォーマット
refactor: API ルートを再構築
perf: データベースクエリを最適化
test: ユーザーサービスのユニットテストを追加
build: 依存関係を更新
ci: GitHub Actions を設定
chore: .gitignore を更新
revert: 前回のコミットを取り消す無効なコミットは commit-msg フックによって拒否されます。
必要に応じて手動でこれらのコマンドを実行:
# すべてのファイルをリント
pnpm lint
# すべてのファイルをフォーマット
pnpm format
# 変更なしでフォーマットをチェック
pnpm format:check
# すべてのパッケージの型チェック
pnpm check- ポートが使用中: ポート 5173 または 8787 を使用しているローカルサーバーを停止
- Permission denied: Docker に適切な権限があることを確認
- Database not found:
wrangler d1 createを実行してデータベースを作成 - Bindings error: main/coreのWrangler設定とTerraform outputが一致することを確認
すべてのパッケージの型チェックを実行:
pnpm check詳細は CONTRIBUTING.md を参照してください(ブランチ運用、チェック項目、SDK 再生成手順など)。コーディング規則は CODING_STANDARDS.md にまとめています。