scaffold

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/scaffold — Architecture-Aware Feature Scaffolding

/scaffold — 架构感知特性脚手架

What

功能说明

Generates a complete feature with all required files based on the project's architecture. Never generates half a feature — every scaffold includes the endpoint, handler, validation, DTOs, EF configuration, and at least one integration test as a single unit, written in modern C# 14 (primary constructors, collection expressions, records, sealed handlers, TypedResults).

Supported architectures (file placement maps and code shape templates live in

references/architecture-patterns.md

Vertical Slice Architecture (VSA) — single-file features in
```
Features/
```
Clean Architecture (CA) — files split across Domain, Application, Infrastructure, Api
DDD + Clean Architecture — aggregate roots, value objects, domain events, plus CA layers
Modular Monolith — self-contained modules with their own DbContext and integration events

基于项目架构生成包含所有必需文件的完整特性。绝不生成不完整的特性——每个脚手架都会包含endpoint、handler、验证逻辑、DTOs、EF配置以及至少一个集成测试作为一个整体单元，采用现代C# 14编写（主构造函数、集合表达式、记录类型、密封handler、TypedResults）。

支持的架构（文件布局映射和代码模板定义在

references/architecture-patterns.md

中）：

垂直切片架构（VSA） —
```
Features/
```
目录下的单文件特性
整洁架构（CA） — 文件分散在Domain、Application、Infrastructure、Api层
DDD + 整洁架构 — 聚合根、值对象、领域事件，加上CA分层结构
模块化单体架构 — 包含独立DbContext和集成事件的自包含模块

When

适用场景

"Scaffold a [feature name]", "create an endpoint for", "add a feature"
"Generate CRUD for", "add entity", "new module", "scaffold a module"
Starting a new feature after
```
/plan
```
has produced an approved plan
Customizing generation templates or defining what a complete slice includes
Any time the user wants a complete, working feature skeleton

「Scaffold a [feature name]」「create an endpoint for」「add a feature」
「Generate CRUD for」「add entity」「new module」「scaffold a module」
```
/plan
```
产出已批准的方案后启动新特性开发
自定义生成模板或定义完整特性切片的包含内容
任何需要完整可运行特性骨架的场景

How

使用步骤

Step 1: Detect Architecture

步骤1：检测架构

Use the

architecture-advisor

skill to determine the project's architecture:

Examine folder structure, project references, and existing patterns
If architecture is ambiguous, ask the user rather than guessing
Load the matching architecture skill (vertical-slice, clean-architecture, ddd)

使用

architecture-advisor

技能确定项目架构：

检查目录结构、项目引用和现有代码模式
如果架构不明确，询问用户而非猜测
加载匹配的架构技能（vertical-slice、clean-architecture、ddd）

Step 2: Clarify Scope

步骤2：明确范围

Confirm with the user before generating (skip anything the plan already answers):

Feature/entity name and operations needed — full CRUD or a subset?
Key fields and invariants for any new entity
Module placement (Modular Monolith only) — existing module or new one?

生成前与用户确认（跳过方案已明确的内容）：

特性/实体名称及所需操作——完整CRUD还是子集？
新实体的关键字段和约束条件
模块位置（仅适用于模块化单体架构）——现有模块还是新模块？

Step 3: Learn Conventions

步骤3：学习约定

Use the

convention-learner

skill and MCP tools to check:

Naming patterns (
```
*Handler
```
,
```
*Service
```
,
```
*Endpoint
```
,
```
*Command
```
,
```
*Query
```
)
Folder structure, file organization, access modifiers, sealed conventions
Existing validation approach (FluentValidation, data annotations, manual)
Test project structure and naming (
```
*Tests
```
,
```
*IntegrationTests
```
)

Match what exists. Do not impose new conventions on an established codebase.

使用

convention-learner

技能和MCP工具检查：

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

匹配现有约定，不要在成熟代码库中强加新约定。

Step 4: Generate All Layers

步骤4：生成所有层

Generate every file the architecture requires, following the templates in

references/architecture-patterns.md

VSA — read the VSA section: single-file feature + endpoint group + EF config + tests
Clean Architecture — read the CA section: Mediator command/handler in Application, endpoint in Api
DDD — read the DDD section: aggregate with invariants and domain events, thin handler
Modular Monolith — read the Modular Monolith section: module DbContext, DI registration, integration events

The reference also covers the shared shapes every architecture reuses (endpoint group, validator, entity +

IEntityTypeConfiguration<T>

pair, test fixture) and the anti-patterns to avoid.

根据

references/architecture-patterns.md

中的模板，生成架构所需的所有文件：

VSA — 参考VSA章节：单文件特性 + 端点组 + EF配置 + 测试
整洁架构 — 参考CA章节：Application层的Mediator命令/handler，Api层的端点
DDD — 参考DDD章节：包含约束和领域事件的聚合根，轻量handler
模块化单体架构 — 参考模块化单体章节：模块DbContext、DI注册、集成事件

参考文档还涵盖了所有架构复用的通用结构（端点组、验证器、实体+

IEntityTypeConfiguration<T>

配对、测试夹具）以及需要避免的反模式。

Step 5: Completeness Checklist (MANDATORY)

步骤5：完整性检查清单（必填）

Every scaffolded feature MUST include ALL nine items. Do not skip any:

Endpoint —
```
IEndpointGroup
```
file with a route group; never wired in Program.cs
Handler —
```
sealed
```
, primary constructor, one per operation
Validator — FluentValidation rules with meaning (ranges, required, max lengths), wired via
```
.AddEndpointFilter<ValidationFilter<T>>()
```
on mutating endpoints
DTOs — records shaped for the consumer, never 1:1 entity mirrors
EF configuration —
```
IEntityTypeConfiguration<T>
```
; no data annotations on entities

Integration tests —

WebApplicationFactory

+ Testcontainers, DI replacement via

services.RemoveAll<DbContextOptions<T>>()

OpenAPI metadata —

.WithName()

.WithSummary()

.Produces<T>()

.ProducesValidationProblem()

.ProducesProblem(404)

CancellationToken — on every async method and passed to every async call
Result pattern — handlers return
```
Result<T>
```
; endpoints map success → TypedResults, failure →
```
ToProblemDetails()
```

Also verify supporting infrastructure — scaffold it if missing: list endpoints get bounded pagination (

page

pageSize

, max 50), Program.cs has

app.UseExceptionHandler()

, and appsettings.json has a connection string.

每个脚手架生成的特性必须包含以下全部9项内容，不得遗漏：

端点 — 包含路由组的
```
IEndpointGroup
```
文件；绝不在Program.cs中直接配置
Handler — 密封类、主构造函数，每个操作对应一个Handler
验证器 — 具有实际意义的FluentValidation规则（范围、必填、最大长度等），通过
```
.AddEndpointFilter<ValidationFilter<T>>()
```
配置在可变端点上
DTOs — 为消费者定制的记录类型，绝不与实体1:1映射
EF配置 —
```
IEntityTypeConfiguration<T>
```
；实体上不使用数据注解

集成测试 —

WebApplicationFactory

+ Testcontainers，通过

services.RemoveAll<DbContextOptions<T>>()

替换DI依赖

OpenAPI元数据 —

.WithName()

、

.WithSummary()

、

.Produces<T>()

、

.ProducesValidationProblem()

、

.ProducesProblem(404)

CancellationToken — 每个异步方法都包含，并传递给所有异步调用
结果模式 — Handler返回
```
Result<T>
```
；端点将成功映射为TypedResults，失败映射为
```
ToProblemDetails()
```

同时验证支撑基础设施——如果缺失则自动生成：列表端点支持分页（

page

pageSize

，最大50条）、Program.cs包含

app.UseExceptionHandler()

、appsettings.json包含连接字符串。

Step 6: Verify

步骤6：验证

Prove the scaffold works before reporting done:

bash

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

If the build or tests fail, fix and re-run before presenting results.

报告完成前需证明脚手架生成的代码可正常运行：