aep-scaffold

脚手架

为 Agent 开发搭建项目——可以创建新的 monorepo，也可以接入并整合现有项目。两种方式都会生成包含 OpenSpec、工作区设置钩子和规范 BDD 端到端测试技能的项目。现有项目路径采用幂等的审计 → 确认 → 整合流程，重新运行时也会修复偏差。

---

模式选择

判断这是新项目还是现有项目：

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

• 新项目 — 目录为空或几乎为空，没有项目配置文件 → 新项目流程（阶段 1-8）
• 现有项目 — 包含源代码和配置文件 → 现有项目流程 — 审计 → 确认 → 整合（阶段 0E-6E）

---

默认工具链

生成工作区钩子和端到端测试技能时，除非项目已使用其他工具，否则请采用以下默认配置：

语言	包管理器	测试运行器	开发服务器
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：了解项目

询问用户要构建什么——答案将决定所有技术栈建议。有关项目类型预设、四种 --template 预设（t3/pern/mern/uniwind）、完整的标志/选项/默认值表以及各选项的决策指南，请阅读 references/stack-guide.md — 规范的技术栈参考。

步骤 2：介绍默认配置并询问是否需要自定义

默认技术栈（SaaS/ Web 应用）： Hono + TanStack Router + Drizzle + SQLite + Better Auth + tRPC + Turborepo + Biome + Bun

想自定义哪些部分，还是直接使用此技术栈？

如果用户表示“使用默认配置”或类似意思，跳到阶段 2。

步骤 3：逐项确定自定义配置

按逻辑分组进行决策，不要一次性列出所有选项：

1. 核心技术栈（前端 + 后端 + API 层）— 定义架构
2. 数据层（数据库 + ORM + 数据库托管）— 如果使用 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	macOS：xcode-select --install
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 不需要数据库/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 为集成分支，因此不设置覆盖值。关于双分支模型、覆盖键以及 $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 技能 （探索、提案、应用、归档）。

--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：设置命令别名

将此技能的四个 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：生成工作区设置 Hook

创建 /aep-build 阶段 0 调用的项目专用设置 Hook：

mkdir -p .claude/hooks

生成适配阶段 1 所选技术栈的 .claude/hooks/workspace-setup.sh。它会安装依赖、扫描可用端口、启动开发服务器，如果存在 skills/e2e-test/scripts/seed.sh，则调用该脚本，并且必须写入 .dev-workflow/ports.env — 这是与 /aep-build 的约定：

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 处理 — 它会生成项目级测试基础设施，供 /aep-build 阶段 5-8 使用，并采用规范的 BDD 分层门控三层结构：旅程库（自然语言 Given/When/Then/Verify）、独立的 tool-selection.md（根据环境解析浏览器/设备工具）以及幂等的 seed.sh。它会读取阶段 1 所选的技术栈来填充模板，并负责规范的跨工具布局 — 真正的 skills/e2e-test/ 目录以及 .claude 和 .agents 发现符号链接（Claude Code、Codex 和 Pi 均可见）。它还会决定目标生成哪些内容（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 标准偏移的情况（完善的按 Agent 划分的技能布局、BDD e2e 技能、当前固定版本）。它会先报告情况，再征求确认，然后执行收敛，遵循上文的防护措施。

请阅读 references/converge-flow.md——其中详细说明了此流程，包括如何解读各审计类别、如何处理 observability→telemetry 候选项，以及各类别的收敛细节。

在以下命令中，将 <aep-scaffold-dir> 替换为包含此 SKILL.md 的绝对目录；它只是表示法，不是环境变量，也不是相对于目标项目的路径。

阶段 0E：状态检查（技术栈 + 固定版本）

scripts/audit.sh 开始时会检测语言、包管理器、monorepo 工具、后端/前端信号，以及 AEP 固定版本与最新发行版。请参照 references/converge-flow.md →“解读审计”中的说明理解这些结果（包管理器建议、默认 e2e target）。

---

阶段 1E：审计（感知偏移），按类别分组

运行只读审计。此阶段不会进行任何更改。

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

每项检查都会打印 [ok] 或 [DRIFT]，并且只要仍存在 [DRIFT] 就以非零状态码退出（无偏移时退出码为 0）。各类别（A–E）的含义以及 observability 的处理方式，请参阅 references/converge-flow.md。

---

阶段 2E：报告 + 确认方向

按类别给出当前状态 → 目标状态摘要，询问要应用哪些类别（默认 = 修复所有偏移和缺失项），并且只在阶段 3E 收敛已确认的类别。摘要格式见 references/converge-flow.md →“报告 + 确认”。

---

阶段 3E：收敛（幂等）

仅应用已确认的更改；每个步骤在目标状态已满足时都不会执行任何操作。先运行机械修复， 再执行两个由模型驱动的步骤。每个类别的详情见 references/converge-flow.md。

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

仅传入已确认的机械类别（A、C 或 E），重复使用 --category；如果没有确认任何类别，则跳过脚本。E 只会输出重新固定版本的建议；B 和 D 仍由模型驱动。

• B. 端到端测试技能 — 委派给 /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 层门禁端到端测试技能
/aep-git-ref	AEP git + worktree 参考（worktree 生命周期、命名）