scaffold

/scaffold — 基于架构的功能脚手架生成

内容

根据项目架构生成包含所有必需文件的完整功能。绝不生成半成品功能——每个脚手架都包含端点、处理程序、验证、DTO、EF 配置，以及至少一个集成测试，作为一个整体编写，并采用现代 C# 14 特性（主构造函数、集合表达式、记录、密封处理程序、TypedResults）。

支持的架构（文件放置映射和代码结构模板见 references/architecture-patterns.md）：

• 垂直切片架构（VSA） — 在 Features/ 中以单文件形式组织功能
• 整洁架构（CA） — 文件分布在 Domain、Application、Infrastructure、Api 中
• DDD + 整洁架构 — 聚合根、值对象、领域事件，以及 CA 层
• 模块化单体 — 自包含模块，各自拥有 DbContext 和集成事件

适用场景

• “搭建一个[功能名称]”“为……创建端点”“添加一项功能”
• “为……生成 CRUD”“添加实体”“新建模块”“搭建一个模块”
• /plan 生成获批计划后，开始开发新功能
• 自定义生成模板，或定义完整切片应包含的内容
• 用户想要完整、可运行的功能骨架时

操作方式

第 1 步：检测架构

使用 architecture-advisor skill 确定项目的架构：

• 检查文件夹结构、项目引用和现有模式
• 如果架构不明确，请询问用户，不要猜测
• 加载对应的架构 skill（vertical-slice、clean-architecture、ddd）

第 2 步：明确范围

生成前与用户确认（计划中已有答案的内容可跳过）：

1. 功能/实体名称和所需操作——完整 CRUD 还是部分操作？
2. 新实体的关键字段和不变量
3. 模块放置位置（仅适用于模块化单体）——现有模块还是新模块？

第 3 步：了解约定

使用 convention-learner skill 和 MCP 工具检查：

• 命名模式（*Handler、*Service、*Endpoint、*Command、*Query）
• 文件夹结构、文件组织方式、访问修饰符、密封类型约定
• 现有验证方式（FluentValidation、数据注解、手动验证）
• 测试项目结构和命名（*Tests、*IntegrationTests）

遵循现有做法。不要在已有约定的代码库中强行引入新约定。

第 4 步：生成所有层

按照 references/architecture-patterns.md 中的模板，生成架构所需的每个文件：

• VSA — 阅读 VSA 部分：单文件功能 + 端点组 + EF 配置 + 测试
• 整洁架构 — 阅读 CA 部分：Application 中的 Mediator 命令/处理程序，Api 中的端点
• DDD — 阅读 DDD 部分：包含不变量和领域事件的聚合，以及精简的处理程序
• 模块化单体 — 阅读模块化单体部分：模块 DbContext、DI 注册、集成事件

该参考还介绍了各种架构共用的结构（端点组、验证器、实体 + IEntityTypeConfiguration<T> 配对、测试夹具），以及应避免的反模式。

步骤 5：完整性检查清单（强制）

每个脚手架生成的功能都必须包含以下全部九项。不得跳过任何一项：

• 端点 — 包含路由组的 IEndpointGroup 文件；绝不在 Program.cs 中接入
• 处理器 — sealed，使用主构造函数，每个操作一个
• 验证器 — 使用 FluentValidation 编写有意义的规则（范围、必填项、最大长度），并在变更端点上通过 .AddEndpointFilter<ValidationFilter<T>>() 接入
• DTO — 根据使用者需求设计的记录类型，不得与实体一一对应
• EF 配置 — 使用 IEntityTypeConfiguration<T>；实体上不得使用数据注解
• 集成测试 — 使用 WebApplicationFactory + Testcontainers，并通过 services.RemoveAll<DbContextOptions<T>>() 替换 DI 服务
• OpenAPI 元数据 — .WithName()、.WithSummary()、.Produces<T>()、.ProducesValidationProblem()、.ProducesProblem(404)
• CancellationToken — 每个异步方法都必须包含，并传递给每个异步调用
• Result 模式 — 处理器返回 Result<T>；端点将成功映射为 TypedResults，将失败映射为 ToProblemDetails()

还要检查支撑基础设施；若缺失则生成：列表端点应采用有界分页（page/pageSize，最大值为 50），Program.cs 应包含 app.UseExceptionHandler()，appsettings.json 应包含连接字符串。

步骤 6：验证

报告完成前，证明脚手架可以正常工作：

dotnet build --no-restore
dotnet test --no-build --filter "FullyQualifiedName~{FeatureName}"

如果构建或测试失败，请修复并重新运行，然后再提交结果。

示例

User: /scaffold a Product Catalog feature with CRUD operations

Claude: Detected architecture: Vertical Slice Architecture

Created files:
  src/Features/Products/CreateProduct.cs     -- Command + handler + validator
  src/Features/Products/GetProduct.cs        -- Query by ID + handler
  src/Features/Products/ListProducts.cs      -- Paginated list + handler
  src/Features/Products/UpdateProduct.cs     -- Command + handler + validator
  src/Features/Products/DeleteProduct.cs     -- Command + handler
  src/Features/Products/ProductEndpoints.cs  -- IEndpointGroup, OpenAPI metadata
  src/Features/Products/ProductConfig.cs     -- EF Core configuration
  tests/Features/Products/CreateProductTests.cs
  tests/Features/Products/GetProductTests.cs
  tests/Features/Products/ListProductsTests.cs

Checklist: 9/9 | Build: PASS | Tests: PASS

All files follow your existing conventions (sealed handlers,
primary constructors, TypedResults return types).

相关内容

• dotnet-init — 在生成脚手架功能前初始化项目和 CLAUDE.md
• vertical-slice — VSA 脚手架所遵循的 VSA 模式
• clean-architecture — CA 脚手架背后的分层规则
• ddd — DDD 脚手架背后的聚合和领域事件模式
• project-structure — 各种架构中各文件的存放位置