architecture-advisor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecture Advisor

架构顾问

Core Principles

核心原则

  1. Ask before recommending — Never prescribe an architecture without understanding the project. Run the questionnaire first to gather context about domain, team, lifetime, and constraints.
  2. Right-size the architecture — The best architecture is the simplest one that handles the project's actual complexity. CRUD apps do not need DDD. Startups do not need Clean Architecture. Match complexity to real requirements, not aspirations.
  3. Architecture is not permanent — Every architecture has an evolution path. Start simple and add structure when complexity demands it. Document the decision so the team knows when to evolve.
  4. Four supported architectures — dotnet-claude-kit provides first-class patterns for Vertical Slice Architecture (VSA), Clean Architecture (CA), DDD + Clean Architecture, and Modular Monolith. Each has specific strengths and trade-offs.
  1. 先询问再推荐 — 在不了解项目情况的前提下,绝不直接指定架构。先执行问卷调查,收集领域、团队、生命周期和约束条件等背景信息。
  2. 匹配架构复杂度 — 最佳架构是能够应对项目实际复杂度的最简单方案。CRUD应用不需要DDD。初创公司不需要Clean Architecture。让复杂度匹配实际需求,而非理想化目标。
  3. 架构并非一成不变 — 每种架构都有演进路径。从简单方案起步,当复杂度提升时再增加结构。记录决策过程,以便团队知晓何时需要演进。
  4. 支持四种架构 — dotnet-claude-kit 提供Vertical Slice Architecture(VSA)、Clean Architecture(CA)、DDD + Clean Architecture 和 Modular Monolith 的一流模式。每种架构都有特定优势和权衡。

The Architecture Questionnaire

架构问卷调查

Before recommending an architecture, ask questions across these 6 categories. Not every question applies to every project — skip irrelevant ones.
在推荐架构前,需针对以下6个类别提出问题。并非每个问题都适用于所有项目——跳过无关问题。

Category 1: Domain Complexity

类别1:领域复杂度

#QuestionLow SignalHigh Signal
1How many distinct business entities does the system manage?< 10 entities20+ entities with relationships
2Do business rules involve multiple entities interacting?Rules are per-entity CRUDComplex invariants across entity groups
3Are there business workflows with multiple steps?Simple request → responseSagas, approval chains, state machines
4Do domain experts use specialized vocabulary?Generic terms (create, update)Ubiquitous language (underwrite, adjudicate)
#问题低信号高信号
1系统管理多少个不同的业务实体?少于10个实体20个以上带关联的实体
2业务规则是否涉及多个实体交互?规则为单实体CRUD操作实体组间存在复杂不变量
3是否存在多步骤的业务工作流?简单请求→响应事务序列、审批链、状态机
4领域专家是否使用专业词汇?通用术语(创建、更新)统一语言(核保、裁决)

Category 2: Team & Organization

类别2:团队与组织

#QuestionLow SignalHigh Signal
5How large is the development team?1-3 developers8+ developers, multiple teams
6Do different teams own different parts of the system?Single team owns everythingTeams aligned to business domains
7What is the team's experience level with .NET?Junior or mixedSenior, experienced with patterns
#问题低信号高信号
5开发团队规模有多大?1-3名开发者8名以上开发者,多团队协作
6是否由不同团队负责系统的不同部分?单个团队负责全部内容团队与业务领域对齐
7团队的.NET经验水平如何?初级或混合水平资深,熟悉设计模式

Category 3: System Lifetime & Scale

类别3:系统生命周期与规模

#QuestionLow SignalHigh Signal
8Expected system lifetime?< 2 years, MVP/prototype5+ years, long-lived product
9How many concurrent users or requests per second?< 100 RPS1000+ RPS, variable load
10Will the system need to scale independently by feature area?Uniform loadHot spots need independent scaling
#问题低信号高信号
8预期系统生命周期?少于2年,MVP/原型5年以上,长期维护产品
9并发用户数或每秒请求数是多少?少于100 RPS1000+ RPS,负载波动大
10系统是否需要按功能区域独立扩展?负载均匀热点区域需要独立扩展

Category 4: Regulatory & Compliance

类别4:监管与合规

#QuestionLow SignalHigh Signal
11Are there audit trail or compliance requirements?Basic logging sufficientFull audit trail, SOX/HIPAA/PCI
12Do different parts of the system have different security boundaries?Single auth boundaryMulti-tenant, data isolation
#问题低信号高信号
11是否有审计追踪或合规要求?基础日志即可满足完整审计追踪,符合SOX/HIPAA/PCI标准
12系统不同部分是否有不同的安全边界?单一认证边界多租户,数据隔离

Category 5: Existing Codebase

类别5:现有代码库

#QuestionLow SignalHigh Signal
13Is this greenfield or brownfield?Greenfield, starting freshBrownfield, migrating from legacy
14Are there existing architectural patterns the team follows?No established patternsStrong conventions in place
#问题低信号高信号
13是全新项目还是遗留项目?全新项目,从零开始遗留项目,需从旧系统迁移
14团队是否已有遵循的架构模式?无既定模式有明确的约定规范

Category 6: Integration Complexity

类别6:集成复杂度

#QuestionLow SignalHigh Signal
15How many external systems does this integrate with?0-2 simple APIs5+ systems with complex contracts
16Are there event-driven or async communication needs?Synchronous request/responseEvent sourcing, pub/sub, eventual consistency
#问题低信号高信号
15需要集成多少个外部系统?0-2个简单API5个以上带复杂契约的系统
16是否有事件驱动或异步通信需求?同步请求/响应事件溯源、发布/订阅、最终一致性

Decision Matrix

决策矩阵

Map questionnaire answers to architecture recommendations:
ProfileRecommended ArchitectureWhy
Low domain complexity, small team, short lifetimeVertical Slice ArchitectureMinimal ceremony, fast feature delivery, easy to understand
Low-medium domain complexity, any team size, API-focusedVertical Slice ArchitectureFeature cohesion, one file per operation, natural fit for minimal APIs
Medium domain complexity, medium team, long lifetimeClean ArchitectureEnforced boundaries via project references, testable domain, clear dependency direction
High domain complexity, specialized vocabulary, complex invariantsDDD + Clean ArchitectureAggregates protect invariants, value objects model domain concepts, domain events decouple side effects
Multiple bounded contexts, team-per-domain, independent deployment potentialModular MonolithModule isolation, independent data stores, evolution path to microservices
Brownfield with existing layered architectureClean ArchitectureFamiliar to teams coming from N-tier, preserves layer separation with better dependency direction
将问卷答案映射到架构推荐:
特征推荐架构原因
低领域复杂度、小团队、短生命周期Vertical Slice Architecture仪式感最少,功能交付快,易于理解
中低领域复杂度、任意团队规模、API优先Vertical Slice Architecture功能内聚,每个操作对应一个文件,天然适配极简API
中领域复杂度、中等团队、长生命周期Clean Architecture通过项目引用强制边界,领域层可测试,依赖方向清晰
高领域复杂度、专业词汇、复杂不变量DDD + Clean Architecture聚合根保护不变量,值对象建模领域概念,领域事件解耦副作用
多个限界上下文、按领域划分团队、潜在独立部署需求Modular Monolith模块隔离,独立数据存储,可演进为微服务
遗留分层架构项目Clean Architecture对熟悉N层架构的团队友好,保留分层结构同时优化依赖方向

When Signals Conflict

当信号冲突时

If signals point to different architectures:
  1. Default to simpler — When in doubt, start with VSA and evolve
  2. Domain complexity wins — High domain complexity overrides team size and lifetime signals
  3. Team familiarity matters — A team experienced with CA will be more productive with CA than learning VSA, even if VSA is technically simpler
  4. Compliance drives structure — Regulatory requirements often force stricter boundaries (CA or DDD)
如果信号指向不同架构:
  1. 默认选择更简单的方案 — 存疑时,从VSA开始并逐步演进
  2. 领域复杂度优先 — 高领域复杂度覆盖团队规模和生命周期信号
  3. 团队熟悉度很重要 — 熟悉CA的团队使用CA比学习VSA效率更高,即使VSA在技术上更简单
  4. 合规性驱动结构 — 监管要求通常会强制更严格的边界(CA或DDD)

Patterns

模式

Vertical Slice Architecture (VSA)

Vertical Slice Architecture (VSA)

Organize by feature, not by layer. Each operation is a self-contained slice.
src/MyApp.Api/
  Features/
    Orders/CreateOrder.cs    # Request + Handler + Response + Endpoint
    Orders/GetOrder.cs
  Common/
    Behaviors/ValidationBehavior.cs
    Persistence/AppDbContext.cs
Best for: CRUD-heavy apps, APIs, MVPs, small-medium teams, short-medium lifetime. Load skill:
vertical-slice
按功能而非分层组织。每个操作都是一个独立的切片。
src/MyApp.Api/
  Features/
    Orders/CreateOrder.cs    # Request + Handler + Response + Endpoint
    Orders/GetOrder.cs
  Common/
    Behaviors/ValidationBehavior.cs
    Persistence/AppDbContext.cs
最佳适用场景: 以CRUD为主的应用、API、MVP、中小型团队、中短生命周期。 加载技能:
vertical-slice

Clean Architecture (CA)

Clean Architecture (CA)

Concentric layers with dependency inversion. Domain at the center, infrastructure at the edge.
src/
  MyApp.Domain/              # Entities, interfaces, domain logic
  MyApp.Application/         # Use cases, DTOs, validation
  MyApp.Infrastructure/      # EF Core, external services
  MyApp.Api/                 # Endpoints, middleware
Best for: Medium complexity, long-lived systems, teams familiar with layered patterns. Load skill:
clean-architecture
采用依赖倒置的同心圆分层结构。领域层位于中心,基础设施层在边缘。
src/
  MyApp.Domain/              # Entities, interfaces, domain logic
  MyApp.Application/         # Use cases, DTOs, validation
  MyApp.Infrastructure/      # EF Core, external services
  MyApp.Api/                 # Endpoints, middleware
最佳适用场景: 中等复杂度、长期维护系统、熟悉分层模式的团队。 加载技能:
clean-architecture

DDD + Clean Architecture

DDD + Clean Architecture

Clean Architecture with tactical DDD patterns: aggregates, value objects, domain events.
src/
  MyApp.Domain/              # Aggregates, value objects, domain events, domain services
  MyApp.Application/         # Use cases orchestrating aggregates
  MyApp.Infrastructure/      # Persistence, external service adapters
  MyApp.Api/                 # Thin endpoints
Best for: Complex domains, specialized vocabulary, strict invariants, experienced teams. Load skill:
ddd
+
clean-architecture
结合战术DDD模式的Clean Architecture:聚合根、值对象、领域事件。
src/
  MyApp.Domain/              # Aggregates, value objects, domain events, domain services
  MyApp.Application/         # Use cases orchestrating aggregates
  MyApp.Infrastructure/      # Persistence, external service adapters
  MyApp.Api/                 # Thin endpoints
最佳适用场景: 复杂领域、专业词汇、严格不变量、资深团队。 加载技能:
ddd
+
clean-architecture

Modular Monolith

Modular Monolith

Independent modules in a single deployable unit, each with its own architecture internally.
src/
  MyApp.Host/                # Wires modules together
  Modules/
    Orders/                  # Own features, own DbContext, own architecture
    Catalog/                 # Can use VSA, CA, or DDD internally
  MyApp.Shared/              # Integration event contracts only
Best for: Multiple bounded contexts, team-per-domain, future microservices extraction. Load template:
modular-monolith
单个部署单元内的独立模块,每个模块内部可采用自身架构。
src/
  MyApp.Host/                # Wires modules together
  Modules/
    Orders/                  # Own features, own DbContext, own architecture
    Catalog/                 # Can use VSA, CA, or DDD internally
  MyApp.Shared/              # Integration event contracts only
最佳适用场景: 多个限界上下文、按领域划分团队、未来需拆分微服务。 加载模板:
modular-monolith

Evolution Paths

演进路径

Architecture is not a one-time decision. Systems evolve. Here are the common migration paths:
FromToTriggerHow
VSACADomain logic growing beyond handlersExtract Domain + Application layers, keep features as use cases
VSAModular MonolithMultiple bounded contexts emergingGroup features into modules, add module boundaries
CADDD + CAInvariants becoming complex, primitive obsessionIntroduce aggregates, value objects, domain events
MonolithModular MonolithTeams stepping on each other, shared database couplingSplit into modules with own DbContexts and schemas
Modular MonolithMicroservicesIndependent scaling needs, independent deploymentExtract modules into separate deployable services
架构不是一次性决策。系统会不断演进。以下是常见迁移路径:
触发因素实施方式
VSACA领域逻辑超出处理器承载范围提取Domain + Application层,将功能保留为用例
VSAModular Monolith多个限界上下文逐渐显现将功能分组为模块,添加模块边界
CADDD + CA不变量变得复杂,存在原始类型滥用引入聚合根、值对象、领域事件
单体架构Modular Monolith团队间相互干扰,共享数据库耦合严重拆分为带独立DbContext和模式的模块
Modular Monolith微服务独立扩展需求、独立部署需求将模块提取为独立可部署服务

Anti-patterns

反模式

Picking Clean Architecture for a CRUD App

为CRUD应用选择Clean Architecture

// BAD — 4 projects, 6+ files per feature for simple CRUD
src/MyApp.Domain/Entities/Product.cs
src/MyApp.Application/Products/CreateProduct/CreateProductCommand.cs
src/MyApp.Application/Products/CreateProduct/CreateProductHandler.cs
src/MyApp.Application/Products/CreateProduct/CreateProductValidator.cs
src/MyApp.Infrastructure/Persistence/ProductRepository.cs
src/MyApp.Api/Endpoints/ProductEndpoints.cs

// GOOD — VSA: 1 file for a simple CRUD feature
src/MyApp.Api/Features/Products/CreateProduct.cs
// 糟糕方案 — 简单CRUD功能需要4个项目、6个以上文件
src/MyApp.Domain/Entities/Product.cs
src/MyApp.Application/Products/CreateProduct/CreateProductCommand.cs
src/MyApp.Application/Products/CreateProduct/CreateProductHandler.cs
src/MyApp.Application/Products/CreateProduct/CreateProductValidator.cs
src/MyApp.Infrastructure/Persistence/ProductRepository.cs
src/MyApp.Api/Endpoints/ProductEndpoints.cs

// 良好方案 — VSA:单个文件实现简单CRUD功能
src/MyApp.Api/Features/Products/CreateProduct.cs

DDD Everywhere

处处使用DDD

// BAD — value objects and aggregates for a settings table
public class UserSettings : AggregateRoot  // overkill
{
    public ThemeName Theme { get; private set; }  // value object for "dark"/"light"?
    public void ChangeTheme(ThemeName theme) { /* domain event? really? */ }
}

// GOOD — simple entity for simple data
public class UserSettings
{
    public Guid UserId { get; init; }
    public string Theme { get; set; } = "light";
}
// 糟糕方案 — 为配置表使用值对象和聚合根
public class UserSettings : AggregateRoot  // 过度设计
{
    public ThemeName Theme { get; private set; }  // 为"深色"/"浅色"使用值对象?
    public void ChangeTheme(ThemeName theme) { /* 真的需要领域事件吗? */ }
}

// 良好方案 — 简单数据使用简单实体
public class UserSettings
{
    public Guid UserId { get; init; }
    public string Theme { get; set; } = "light";
}

Premature Microservices

过早拆分微服务

// BAD — splitting into 5 microservices on day one with 2 developers
OrderService (own repo, own DB, own CI/CD)
CatalogService (own repo, own DB, own CI/CD)
IdentityService (own repo, own DB, own CI/CD)
NotificationService (own repo, own DB, own CI/CD)
GatewayService (own repo, own CI/CD)

// GOOD — start as a modular monolith, extract when you have evidence
src/
  Modules/Orders/
  Modules/Catalog/
  Modules/Identity/
  Modules/Notifications/
// 糟糕方案 — 第一天就拆分为5个微服务,仅2名开发者
OrderService (独立仓库、独立数据库、独立CI/CD)
CatalogService (独立仓库、独立数据库、独立CI/CD)
IdentityService (独立仓库、独立数据库、独立CI/CD)
NotificationService (独立仓库、独立数据库、独立CI/CD)
GatewayService (独立仓库、独立CI/CD)

// 良好方案 — 从模块化单体开始,有实际需求时再拆分
src/
  Modules/Orders/
  Modules/Catalog/
  Modules/Identity/
  Modules/Notifications/

Skipping the Questionnaire

跳过问卷调查

// BAD — "I always use Clean Architecture"
User: "Set up a new project for a todo app"
Agent: *immediately scaffolds 4-project CA solution*

// GOOD — ask first, then recommend
User: "Set up a new project for a todo app"
Agent: "Let me ask a few questions about your project to recommend the best architecture..."
Agent: *runs questionnaire, recommends VSA for low-complexity app*
// 糟糕方案 — "我一直用Clean Architecture"
用户:"为待办事项应用搭建新项目"
Agent:*立即生成4项目的CA解决方案*

// 良好方案 — 先询问,再推荐
用户:"为待办事项应用搭建新项目"
Agent:"让我问几个关于您项目的问题,以便推荐最佳架构..."
Agent:*执行问卷调查,为低复杂度应用推荐VSA*

Decision Guide

决策指南

ScenarioRecommendation
New project, unknown requirementsRun the questionnaire
Simple CRUD API, 1-3 developersVSA
Medium complexity, long-lived, experienced teamClean Architecture
Complex domain, specialized vocabularyDDD + Clean Architecture
Multiple bounded contexts, multiple teamsModular Monolith
Existing N-tier codebase, needs modernizationClean Architecture (familiar migration)
MVP / startup, speed is priorityVSA
Regulatory / compliance-heavyClean Architecture or DDD (enforced boundaries)
Will need independent scaling laterModular Monolith (extraction-ready)
场景推荐方案
新项目,需求未知执行问卷调查
简单CRUD API,1-3名开发者VSA
中等复杂度、长期维护、资深团队Clean Architecture
复杂领域、专业词汇DDD + Clean Architecture
多个限界上下文、多团队Modular Monolith
现有N层代码库,需要现代化改造Clean Architecture(熟悉的迁移路径)
MVP / 初创公司,优先追求速度VSA
强监管/合规要求Clean Architecture 或 DDD(强制边界)
未来需要独立扩展Modular Monolith(便于后续拆分)