aep-scaffold

スキャフォールド

エージェント駆動開発のためのプロジェクトをセットアップします。新しいモノレポをスキャフォールドする方法と、既存のプロジェクトをオンボーディングして収束させる方法があります。どちらの方法でも、OpenSpec、ワークスペースセットアップフック、標準の BDD e2e テストスキルを備えたプロジェクトが作成されます。既存プロジェクトの方法は、再実行時にもドリフトを修正する、監査 → 確認 → 収束の冪等なプロセスです。

---

モードの選択

新規プロジェクトか既存プロジェクトかを判定します。

# Check for existing project markers
ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null

• 新規プロジェクト — 空、またはほぼ空のディレクトリで、プロジェクト設定ファイルがありません → 新規プロジェクトのフロー（フェーズ 1〜8）
• 既存プロジェクト — ソースコードと設定ファイルがあります → 既存プロジェクトのフロー — 監査 → 確認 → 収束（フェーズ 0E〜6E）

---

デフォルトのツール

ワークスペースフックと e2e テストスキルを生成する際は、プロジェクトですでに別のものが使われている場合を除き、次のデフォルトを使用します。

言語	パッケージマネージャー	テストランナー	開発サーバー
TypeScript / JavaScript	bun	vitest（Turborepo 経由）	bun run dev
Python	uv	pytest	uv run dev
Rust	cargo	cargo test	cargo run
Go	go	go test	go run .

---

新規プロジェクトのフロー

フェーズ 1：要件の確認

ステップ 1：プロジェクトを理解する

ユーザーが何を構築しているのかを尋ねます。その答えによって、あらゆるスタックの推奨内容が決まります。プロジェクトタイプ別のプリセット、4 つの --template プリセット（t3/pern/mern/uniwind）、すべてのフラグ／オプション／デフォルトの一覧表、各オプションの選択ガイダンスについては、スタックの標準リファレンスである references/stack-guide.md を参照してください。

ステップ 2：デフォルトを提示し、カスタマイズについて尋ねる

デフォルトのスタック（SaaS／ウェブアプリ）： Hono + TanStack Router + Drizzle + SQLite + Better Auth + tRPC + Turborepo + Biome + Bun

何かカスタマイズしますか？それとも、このスタックを使用しますか？

ユーザーが「デフォルトを使う」などと答えた場合は、フェーズ 2 に進みます。

ステップ 3：カスタマイズについて確認する

すべての選択肢を一度に提示するのではなく、次のように自然なまとまりに分けて判断します。

1. コアスタック（フロントエンド + バックエンド + API レイヤー）— アーキテクチャを定義します
2. データレイヤー（データベース + ORM + DB ホスティング）— Convex を使う場合は省略します
3. 認証と決済 — 通常はすぐに決まります
4. アドオン — プロジェクトタイプに応じて提案します
5. ランタイムとデプロイ — 通常はデフォルトで問題ありません

tRPC と oRPC の選択、フレームワークのトレードオフ、アドオンのガイダンスについては、references/stack-guide.md を参照してください。重要な制約として、tRPC は nuxt/svelte/solid/astro と互換性がありません。React 以外のフロントエンドには oRPC を使用してください。

デフォルト：インプレースでのスキャフォールド

想定されるワークフローは、git リポジトリを作成 → このプラグインをインストール → インプレースでスキャフォールドです。そのため、デフォルトのディレクトリは . です。

注： インプレースでのスキャフォールドでは --directory-conflict merge を使うため、README.md、.gitignore、package.json が上書きされます。スキャフォールドを実行するリポジトリは、空または新規作成した状態にしてください。

---

フェーズ 2：ツールの確認

for cmd in bun git gh openspec; do
  printf "%-10s" "$cmd:"
  which $cmd >/dev/null 2>&1 && echo "OK ($(which $cmd))" || echo "MISSING"
done

ツール	インストールコマンド
bun	curl -fsSL https://bun.sh/install | bash
git	xcode-select --install（macOS）
gh	brew install gh
openspec	npm install -g @fission-ai/openspec@latest

---

フェーズ 3：プロジェクトのスキャフォールド

確認した要件に基づいて create-better-t-stack コマンドを組み立て、非対話形式で実行します。

デフォルトのコマンド（インプレース）

bun create better-t-stack@latest . --yes --directory-conflict merge --no-git \
  --frontend <frontend> \
  --backend <backend> \
  --database <database> \
  --orm <orm> \
  --auth <auth> \
  --api <api> \
  --runtime <runtime> \
  --package-manager <pm> \
  --addons <addon1,addon2,...>

ルール

• . は現在のディレクトリにスキャフォールドを生成します。--directory-conflict merge はそのディレクトリにマージし、--no-git は git init をスキップします（リポジトリにはすでに .git があります）。
• 対話型プロンプトをスキップするため、常に --yes を含めてください。
• 値が「none」と異なるフラグのみを含めてください。
• --database none の場合は、--orm と --dbSetup も省略してください。
• デプロイフラグは別々です。--webDeploy cloudflare と --serverDeploy cloudflare を指定します。
• 実行前にコマンド全体をユーザーに提示し、実行前に確認を待ってください。

実行前に、references/stack-guide.md の互換性制約表でフラグの組み合わせを確認してください （tRPC／Clerk には React フロントエンドが必要です。self にはメタフレームワークが必要です。Workers には Hono が必要です。Polar には Better Auth が必要です。turborepo または nx のいずれかを選択してください。 Convex では DB／ORM は不要です）。

---

フェーズ 4：スキャフォールド後の検証

1. 構成、インストール、ビルドを検証します。

   ls apps/ packages/
   bun install
   turbo build
   

2. ワークフローディレクトリが gitignore に含まれていることを確認します。

   # Add agentic workflow directories to .gitignore if not already present
   grep -q '.dev-workflow/' .gitignore || printf '\n# Agentic development workflow\n.dev-workflow/\n' >> .gitignore
   grep -q '.feature-workspaces/' .gitignore || printf '.feature-workspaces/\n' >> .gitignore
   

3. スキャフォールドをコミットします。

   git add -A && git commit -m "feat: scaffold monorepo via Better-T-Stack"
   

   新しいリポジトリはシングルブランチモードです。AEP は main を統合ブランチとして自動検出するため、上書き設定は不要です。 2 ブランチモデル、上書きキー、$BASE の解決方法については、/aep-git-ref の「統合ブランチ」を参照してください。

---

フェーズ 5：OpenSpec を初期化する

ステップ 1：init を実行する

openspec init --tools claude,opencode,pi,codex

これにより、openspec/（config.yaml = プロジェクト設定とコンテキスト、specs/ = 信頼できる仕様の原本、 changes/ = 提案と成果物）と、.claude/skills/openspec-*/SKILL.md の Claude Code スキル （explore、propose、apply、archive）が作成されます。

--tools フラグには、カンマ区切りのリストを指定できます。サポートされているすべてのツールを設定するには、--tools all を使用してください。

ステップ 2：プロジェクトのコンテキストを設定する

プロジェクトの技術スタックに合わせて openspec/config.yaml を更新します。スタックを特定するために package.json と bts.jsonc を読み取ります。

schema: spec-driven

context: |
  Tech stack: TypeScript, <frontend>, <backend>, <database>/<orm>
  Monorepo: Turborepo + <package-manager>
  Auth: <auth-provider>
  API: <api-layer>
  Conventions: conventional commits, trunk-based development

ステップ 3：コマンドエイリアスを設定する

このスキルの 4 つの OpenSpec コマンドエイリアスを templates/opsx/ からプロジェクトの .claude/commands/opsx/ にコピーします。

mkdir -p .claude/commands/opsx
# copy explore.md, propose.md, apply.md, archive.md from this skill's templates/opsx/

ステップ 4：セットアップを検証する

# Check OpenSpec is initialized
openspec list

# Check skills were created
for skill in openspec-explore openspec-propose openspec-apply-change openspec-archive-change; do
  printf "%-35s" "$skill:"
  [ -f ".claude/skills/$skill/SKILL.md" ] && echo "OK" || echo "MISSING"
done

# Check commands were created
for cmd in explore propose apply archive; do
  printf "%-15s" "/opsx:$cmd:"
  [ -f ".claude/commands/opsx/$cmd.md" ] && echo "OK" || echo "MISSING"
done

---

フェーズ 6：OpenSpec をコミットする

git add -A && git commit -m "feat: initialize OpenSpec for spec-driven development"

---

フェーズ 7：ワークスペースセットアップフックを生成する

/aep-build のフェーズ 0 がプロジェクト固有のセットアップを実行するために呼び出すフックを作成します。

mkdir -p .claude/hooks

フェーズ 1 で選択したスタックに合わせて .claude/hooks/workspace-setup.sh を生成します。依存関係をインストールし、 空きポートをスキャンし、開発サーバーを起動し、存在する場合は skills/e2e-test/scripts/seed.sh を呼び出します。 また、/aep-build との取り決めとして、.dev-workflow/ports.env に必ず書き込む必要があります。

WEB_PORT=<port>
SERVER_PORT=<port>
BASE_URL=http://localhost:<web-port>
SERVER_URL=http://localhost:<server-port>

テンプレートと references/workspace-hook.md の完全な取り決めを使用し、フェーズ 1 で 選択したスタックに基づいてプロジェクト固有の値を設定してください。

chmod +x .claude/hooks/workspace-setup.sh

---

フェーズ 8：E2E テストスキルを生成する（委任）

/aep-e2e-skill-scaffolding に引き継ぎます。このスキルは、正規の BDD レイヤーゲート 3 階層構成で、 /aep-build のフェーズ 5～8 が使用するプロジェクトレベルのテスト基盤を生成します。構成要素は、ジャーニーライブラリ （自然言語の Given／When／Then／Verify）、独立した tool-selection.md（環境ごとにブラウザー／デバイス用ツールを解決）、 べき等性のある seed.sh です。フェーズ 1 で選択したスタックを読み取り、テンプレートに値を設定します。また、正規の クロスツールレイアウトも管理します。具体的には、実体となる skills/e2e-test/ ディレクトリと、Claude Code、Codex、 Pi から見える .claude および .agents の検出用シンボリックリンクです。さらに、対象に応じて生成する内容も決定します （none → policy.md と seed.sh のみ、cli／web／mobile／desktop → journeys/ と tool-selection.md も追加）。 これらの対象ルールは /aep-e2e-skill-scaffolding に記載されています。

コミット

コミットする前に、委任先が実際にスキルを生成したことを確認してください（明示的な git add <path> で指定したパスが存在しないと、コミットは中断されます）。その後、作成されたものをすべてステージングします。

test -d skills/e2e-test || { echo "ERROR: /aep-e2e-skill-scaffolding did not produce skills/e2e-test — rerun it"; exit 1; }
git add -A   # stages skills/e2e-test/, the two discovery symlinks, and the workspace hook
git commit -m "feat: add workspace hook and BDD e2e-test skill"

---

次のステップ

スキャフォールディング完了後のプロジェクト全体の構成については、references/resulting-structure.mdを参照してください。

コマンド	内容
/aep-dispatch	次のストーリーを選び、構築を開始します（プロダクトのコンテキストがある場合）
/aep-design	機能の設計を直接開始します（単独で使用、プロダクトのコンテキストなし）
bun run dev	開発サーバーを起動します
openspec list	アクティブな変更を一覧表示します

---

ガードレール

• スキャフォールディングを実行する前にコマンド全体を表示して、確認を待ってください。--yes（非対話型）と--no-git（既存の場所で実行）を含め、既存の場所で実行するとREADME.md、.gitignore、package.jsonが上書きされることを警告してください。
• OpenSpecのアーティファクトをgitにコミットしてください。これらはプロジェクトの記録の一部です。
• 既存のOpenSpec設定を上書きしないでください。openspec initの前にopenspec/config.yamlが存在するか確認してください。
• 手作業で作成したコンテンツは上書きされません（ジャーニー、仕様、文章）。既存プロジェクトのフローでは、レイアウトを標準化し、生成済みのインフラを冪等にアップグレードし、手書きのファイルはそのまま保持します。
• バージョンの再固定は推奨のみです。スキャフォールディングはnpx skills add@<newtag>コマンドを表示します。ユーザーは意図的に独自のPRで再固定を行う際に、そのコマンドを実行します。

---

既存プロジェクトのフロー — 監査 → 確認 → 整合

ソースコードがすでにあるプロジェクト向けです。このフローは冪等です。既存プロジェクトのオンボーディングにも、後から再実行して現在のAEP標準に向けたドリフト（エージェントごとの健全なスキルレイアウト、BDD e2eスキル、最新の固定バージョン）を修正するためにも使えます。上記のガードレールに従い、まず報告し、確認を求めてから整合します。

references/converge-flow.mdをお読みください。このフローの正式な説明として、各監査カテゴリの読み方、可観測性からテレメトリー候補への扱い、カテゴリごとの整合の詳細が記載されています。

以下のコマンドでは、<aep-scaffold-dir>をこのSKILL.mdを含む絶対パスに置き換えてください。これは表記上の記号であり、環境変数でも対象プロジェクトからの相対パスでもありません。

フェーズ0E：ステータス確認（スタック＋固定バージョン）

scripts/audit.shは、言語、パッケージマネージャー、モノレポツール、バックエンド／フロントエンドの兆候、およびAEPの固定バージョンと最新リリースの検出から開始します。これらの結果は、references/converge-flow.mdの「監査結果の読み方」（パッケージマネージャーの推奨、デフォルトのe2e target）に従って解釈してください。

---

フェーズ1E：カテゴリ別監査（ドリフト対応）

読み取り専用の監査を実行します。このフェーズでは何も変更されません。

bash "<aep-scaffold-dir>/scripts/audit.sh"

各チェックについて[ok]／[DRIFT]を表示し、[DRIFT]が残っている間はゼロ以外で終了します（問題がなければ終了コード0）。各カテゴリ（A～E）の意味と可観測性の扱いについては、references/converge-flow.mdを参照してください。

---

フェーズ2E：報告＋方針の確認

カテゴリごとに監査結果を現在 → 目標の形式で要約して示し、適用するカテゴリを尋ねてください（デフォルト＝すべてのドリフト＋不足を修正）。フェーズ3Eでは、確認されたカテゴリのみを整合します。要約の形式については、references/converge-flow.mdの「報告＋確認」を参照してください。

---

フェーズ 3E：収束（冪等）

確認済みの変更のみを適用します。各ステップは、すでに満たされている場合は何も行いません。機械的な修正を実行してから、モデル駆動の 2 つのステップを実行します。各カテゴリの詳細は references/converge-flow.md にあります。

bash "<aep-scaffold-dir>/scripts/converge.sh" --category A --category C

確認済みの機械的なカテゴリ（A、C、E）のみを --category を繰り返して渡します。確認済みのカテゴリがない場合はスクリプトをスキップしてください。E は再ピン留めの推奨事項のみを出力します。B と D は引き続きモデル駆動です。

• B. E2E テストスキル — /aep-e2e-skill-scaffolding に委任します。スキルを冪等に作成またはアップグレードします。
• C. 残りのインフラ — 不足している項目ごとに対応します。git リポジトリ（git init -b main && git add -A && git commit -m "chore: initial commit"）；OpenSpec（フェーズ 5 に従います）；ワークスペースフック（フェーズ 7 に従います）。

---

フェーズ 4E：検証

監査を再実行し、終了コードが 0 になるまで繰り返します。その時点で、確認済みのすべてのカテゴリが [ok] と表示されます。

bash "<aep-scaffold-dir>/scripts/audit.sh"

---

フェーズ 5E：コミット

git add -A
git commit -m "feat: converge agentic development infrastructure"

---

フェーズ 6E：次のステップ

コマンド	機能
/aep-design	機能の設計を開始します（スタンドアロンモード）
/aep-dispatch	次のストーリーを選択します（プロダクトコンテキストがある場合）
/aep-e2e-skill-scaffolding	BDD レイヤーゲート E2E テストスキルを生成／アップグレードします
/aep-git-ref	AEP の git と worktree のリファレンス（worktree のライフサイクル、命名）