scaffold-mvp

Scaffolding MVP

适用场景

• 用户用英语请求或提及此技能（例如：“use /scaffold-mvp”“run scaffold-mvp”）。
• 用户用葡萄牙语请求或提及此技能（例如：“use /scaffold-mvp”“execute scaffold-mvp”）。

触发条件

仅在全新代码库中，且 /write-specs 已确立共用语言、领域并批准 SPEC SDD 后，才会激活此技能；用户明确要求快速搭建 MVP 时也会激活。

黄金法则（不可妥协）

严禁从头构建基础 UI 组件或基础设施。

复用共享组件和成熟的原型开发库，以加快原型开发。这是最高优先级，不可妥协。

• Blazor：优先使用 MudBlazor、Radzen、Fluent UI Blazor 或 Bootstrap Blazor。
• Angular：优先使用 Angular Material、PrimeNG 或 NG-ZORRO。
• .NET 后端：优先使用 ABP Framework、FastEndpoints，或搭配 Carter 的最小 API。
• 移动端/ Web 混合应用：优先使用 MAUI Blazor Hybrid、Ionic Angular 或其他成熟套件。

稳定性与技术节奏（切勿操之过急）

MVP 的开发速度不能以代码不稳定或采用结构性捷径为代价。语法和架构完整性至高无上。Agent 必须遵循以下要求：

1. 增量编译检查：每次安装依赖项或创建基础目录后，都要运行本地构建或类型检查命令（例如 dotnet build、ng build、npm run build）。在确认当前构建通过之前，切勿累积更改。
2. 禁止伪代码：严禁在路由或脚手架文件中使用 // ... 或 // rest of the code here 等注释。每个新建文件都必须自包含，并且具备商业可用性。
3. 安全设置依赖项：固定库的确切版本。始终运行明确的安装命令，确保锁文件（package-lock.json、yarn.lock、pnpm-lock.yaml）更新干净。
4. 构建桥接与契约：如果 MVP 依赖外部服务（数据库、缓存、身份验证、队列、支付），请提供可在本地使用的存根或模拟项。避免首次启动时发生未处理的崩溃。

工作流

阶段 0 — Agent 框架

在编写任何应用程序代码之前，先调用 /create-agent-harness，在新代码库中安装 Agent 框架。

完成后，确认以下文件/目录存在：

• CLAUDE.md / AGENTS.md
• .claude/CONTEXT.md
• .claude/MEMORY.md
• .claude/rules/
• .claude/skills/ 和 .claude/hooks/
• docs/
• 包含 main 分支的 .git

如果框架已存在，则跳过此阶段，改为读取 .claude/CONTEXT.md。

阶段 1 — 项目摘要与技术栈提案

不要进行泛泛的业务提问；前置技能已确立领域。只需询问简要的项目摘要，以完善技术栈提案。

1. 阅读 .claude/CONTEXT.md、docs/architecture/（如果存在）以及已批准的 .specs/SPEC-*.md。
2. 用葡萄牙语请用户提供一句话摘要：

Resumo rapido do projeto: qual e o objetivo principal e quem sao os usuarios?

➡️ Meu palpite: [resumo baseado no SPEC lido]

3. 根据领域，提出最高效的 .NET/Blazor/Angular 技术栈。以顾问的方式给出明确建议，并优先考虑开发速度。

阶段 2 — 技术栈决策

使用下方的决策树。继续之前，用葡萄牙语与用户确认所选技术栈。

类型	默认 MVP 技术栈	UI / 组件库
Web 仪表板 / 管理后台 / SaaS（Blazor）	.NET 8 + Blazor Server 或 Blazor WebAssembly + EF Core	MudBlazor 或 Radzen 或 Fluent UI Blazor
Web 仪表板 / 管理后台 / SaaS（Angular）	.NET 8 Web API + Angular 17+	PrimeNG 或 Angular Material 或 NG-ZORRO
仅 API / 后端	.NET 8 最小 API 或 FastEndpoints 或 ABP	—
CLI / 工作进程	.NET 8 控制台或工作进程服务	—
移动端 / 混合应用	.NET MAUI Blazor Hybrid	MudBlazor 或 Fluent UI

强制验证：

Baseado no nosso contexto de dominio, proponho iniciar com [STACK_ESCOLHIDA] para maxima produtividade sem reinventar a roda.

Voce concorda com esta stack ou temos alguma restricao tecnica ainda nao mapeada?

➡️ Meu palpite: concordo com a proposta.

等待用户明确批准。如果用户希望修改，则调整脚手架方案。如果用户同意，则继续。

阶段 3 — 技术与结构实施

仅在获得用户明确批准后继续。

1. 项目骨架 — 创建解决方案／项目结构：

   • .NET 解决方案（.sln）和项目（src/、tests/）
   • 用于集中管理包的 Directory.Build.props 或 Directory.Packages.props
   • appsettings.json 和 appsettings.Development.json
   • 用于固定 .NET SDK 版本的 global.json

2. 安装基础技术栈 — 安装选定的 UI 套件和核心库：

   • Blazor：MudBlazor、Radzen.Blazor 或 Microsoft.FluentUI.AspNetCore.Components
   • Angular：primeng、@angular/material 或 ng-zorro-antd
   • 共享的 .NET 库：Serilog、FluentValidation、AutoMapper/Mapperly、EF Core 或 Dapper

3. 面向代码复用的敏捷目录结构：

   • src/Web/Components — 来自所选套件的可复用 UI 组件
   • src/Core/ — 领域逻辑、DTO、接口
   • src/Infrastructure/ — EF Core、外部服务、存根
   • tests/UnitTests/ — 可立即运行的首个测试项目

4. 文档目录 — 创建项目决策记录：

   • docs/architecture/
   • docs/architecture/AD-0001-initial-stack.md
   • docs/adr/（供未来的 ADR 使用）
   • .specs/
   • docs/specs/

5. 生成简洁的 README，说明：

   • 本地运行命令（dotnet run、ng serve）
   • 采用的技术栈和架构
   • 如何添加功能（优先复用，并遵循 .claude/CONTEXT.md）

6. 每完成一个重要步骤后运行构建／类型检查。发现错误时，先修复再继续。

阶段 4 — 初始架构决策记录

创建 docs/architecture/AD-0001-initial-stack.md，并写入以下内容：

# AD-0001 — Initial MVP Stack

## Context
[One-paragraph summary from Phase 1.]

## Decision
[Chosen stack: .NET version, Blazor or Angular, UI kit, persistence, DI, logging.]

## Consequences
- Positive: fast prototyping, proven component library, stable build.
- Trade-off: limited custom UI, dependency on the chosen kit.

## Related SPEC
- [.specs/SPEC-{YYYYMMDD}-{slug}.md](../.specs/SPEC-{YYYYMMDD}-{slug}.md)

阶段 5 — 外部服务存根

为每项外部依赖（数据库、缓存、队列、身份验证、对象存储、支付）创建可在本地运行的存根：

• 尽可能使用 Docker Compose 或本地内存实现。
• 提供包含所有必需键和虚构本地值的 .env.example。
• 添加健康检查脚本或端点。
• 服务缺失时，绝不能让应用在启动时崩溃。

返回标准

移交给编排器之前：

• 已安装 Agent 框架（.claude/、CLAUDE.md、AGENTS.md）。
• 已在 .claude/CONTEXT.md 的 技术详情 下更新所选技术栈。
• 已创建包含项目摘要的 .claude/MEMORY.md。
• 已创建 docs/architecture/AD-0001-initial-stack.md。
• .specs/ 和 docs/specs/ 目录均已存在。
• 已创建包含运行命令和简短架构说明的 README.md。
• 构建／类型检查顺利通过。
• 锁文件已更新并提交。
• 脚手架文件中不留伪代码、TODO 或 // ... 占位注释。
• 外部依赖均有本地存根或模拟实现。
• 初始 git 历史已建立，且 main 分支上至少有一次提交。

然后将控制权交还给编排器，并报告基础环境已准备就绪，可开始开发功能。

常见错误

错误	修正方法
自定义 UI 基础组件	使用 MudBlazor、Radzen、Fluent UI、PrimeNG、Angular Material 或 NG-ZORRO。
跳过构建检查	每完成一个结构步骤后运行 dotnet build / ng build。
留下 // ... 注释	每个文件都必须完整且可正常运行。
没有外部服务的本地存根	添加 Docker／内存实现／环境变量示例存根。
未经用户批准技术栈就继续	询问并等待用户明确用葡萄牙语确认。
缺少 Agent 框架或文档目录	在搭建应用脚手架之前安装 /create-agent-harness。

参考资料

• create-agent-harness — 在新仓库中安装 Agent 框架
• write-specs — 编写此技能之前的 SPEC SDD
• create-issues — 将 Epic 转换为 GitHub Issue