Back to Details

project-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Project Setup — Tech-Stack Advisor

项目搭建——技术栈顾问

This skill owns one thing: the kit's recommended tech-stack defaults and why. The workflows that consume it live elsewhere:
  • Initializing a project / generating CLAUDE.md → 
    dotnet-init
    (interactive flow, architecture questionnaire, CLAUDE.md generation)
  • Assessing an existing codebase → 
    health-check
    (the canonical 8-dimension graded assessment)
  • EF Core schema, NuGet, or .NET version migrations → 
    migrate
  • Choosing an architecture → 
    architecture-advisor
    (always ask before recommending)
本工具的核心职责是：提供工具包推荐的技术栈默认方案及其理由。相关的工作流由其他工具负责：
  • 项目初始化/生成CLAUDE.md → 
    dotnet-init
    （交互式流程、架构问卷、CLAUDE.md生成）
  • 现有代码库评估 → 
    health-check
    （标准的8维度分级评估）
  • EF Core架构、NuGet或.NET版本迁移 → 
    migrate
  • 架构选型 → 
    architecture-advisor
    （推荐前务必先询问）

Core Principles

核心原则

  1. Recommend a default, explain the why, let the user choose — Every dimension has a kit default, but defaults are starting points, not mandates. State the trade-off in one line so the choice is informed.
  2. Prefer built-in .NET over third-party — 
    HybridCache
    over Redis-client wrappers, built-in rate limiting over packages, built-in OpenAPI over Swashbuckle. Fewer dependencies means fewer licensing surprises and upgrade breaks.
  3. License-aware picks — MediatR (v13+), MassTransit (v9+), and FluentAssertions (v8+) went commercial. The kit defaults to MIT alternatives: Mediator, Wolverine, plain xUnit asserts.
  4. Add messaging later, not never — Most projects don't need a message bus on day one. Default to "None (add later)" and reach for Wolverine when async workflows actually appear.
  1. 给出默认推荐、说明理由、让用户自主选择 —— 每个维度都有工具包默认方案，但默认方案只是起点而非强制要求。用一句话说明取舍，让用户做出知情选择。
  2. 优先使用.NET内置功能而非第三方工具 —— 用
    HybridCache
    替代Redis客户端封装，用内置限流替代第三方包，用内置OpenAPI替代Swashbuckle。更少的依赖意味着更少的许可问题和升级中断风险。
  3. 考虑许可类型的选型 —— MediatR（v13+）、MassTransit（v9+）和FluentAssertions（v8+）已转为商用许可。工具包默认采用MIT许可的替代方案：Mediator、Wolverine、原生xUnit断言。
  4. 延迟添加消息传递，而非完全不添加 —— 大多数项目在初期不需要消息总线。默认选择“无（后续添加）”，当实际出现异步工作流时再选用Wolverine。

Patterns

模式

Tech-Stack Dimensions and Defaults

技术栈维度与默认方案

DimensionOptionsDefaultWhy
DatabasePostgreSQL, SQL Server, SQLitePostgreSQLOpen source, best EF Core provider outside SQL Server, first-class Testcontainers support
AuthJWT Bearer, OIDC (Keycloak/Auth0), NoneJWT BearerSimplest secure default for APIs; move to OIDC when an external IdP exists
CachingHybridCache, Redis, NoneHybridCacheBuilt-in, stampede protection, L1+L2 — add Redis only as its L2 backend
MessagingWolverine (RabbitMQ), MassTransit, NoneNone (add later)Premature messaging adds ops burden; Wolverine (MIT) when needed
ObservabilitySerilog + OpenTelemetry, Basic loggingSerilog + OTELStructured logs + traces from day one are cheap; retrofitting is not
ResiliencePolly v8 pipelines, Basic retryPolly v8
AddStandardResilienceHandler()
is one line for production-grade defaults
API docsBuilt-in OpenAPI + ScalarOpenAPI + ScalarFramework-maintained spec generation; Scalar replaces Swagger UI
TestingxUnit v3 + TestcontainersxUnit v3 + TestcontainersReal databases in tests; in-memory providers hide real bugs
Once dimensions are chosen, 
dotnet-init
bakes them into the generated CLAUDE.md, and each choice maps to a skill to load when working in that area (
ef-core
, 
authentication
, 
caching
, 
messaging
, 
serilog
, 
opentelemetry
, 
resilience
, 
openapi
, 
scalar
, 
testing
).
维度可选方案默认推荐理由
数据库PostgreSQL, SQL Server, SQLitePostgreSQL开源，是SQL Server之外最佳的EF Core提供程序，支持一流的Testcontainers
认证JWT Bearer, OIDC（Keycloak/Auth0）, 无JWT Bearer是API最简单的安全默认方案；当存在外部身份提供商时再切换到OIDC
缓存HybridCache, Redis, 无HybridCache内置功能，具备缓存击穿防护，支持L1+L2层级 —— 仅在需要L2后端时添加Redis
消息传递Wolverine（RabbitMQ）, MassTransit, 无无（后续添加）过早引入消息传递会增加运维负担；需要时选用MIT许可的Wolverine
可观测性Serilog + OpenTelemetry, 基础日志Serilog + OTEL从项目初期就启用结构化日志和追踪成本很低；后期再改造则难度极大
韧性Polly v8管道, 基础重试Polly v8
AddStandardResilienceHandler()
仅需一行代码即可实现生产级默认配置
API文档内置OpenAPI + ScalarOpenAPI + Scalar由框架维护的规范生成；Scalar替代Swagger UI
测试xUnit v3 + TestcontainersxUnit v3 + Testcontainers测试中使用真实数据库；内存提供程序会掩盖真实bug
确定维度选项后，
dotnet-init
会将其集成到生成的CLAUDE.md中，每个选择都会映射到对应领域工作时需要加载的工具（
ef-core
, 
authentication
, 
caching
, 
messaging
, 
serilog
, 
opentelemetry
, 
resilience
, 
openapi
, 
scalar
, 
testing
）。

Anti-patterns

反模式

Prescribing a Stack Without Asking

未询问就直接指定技术栈

undefined
undefined

BAD — assuming the kit defaults apply everywhere

错误示例——假设工具包默认方案适用于所有场景

"You should use PostgreSQL and Wolverine."
"你应该使用PostgreSQL和Wolverine。"

The team runs SQL Server enterprise-wide and has zero async workflows.

但团队在全企业范围使用SQL Server，且没有任何异步工作流。

GOOD — default + trade-off + question

正确示例——默认方案+取舍说明+询问

"Kit default is PostgreSQL (best OSS EF provider). Any organizational constraint — existing SQL Server licenses, DBA support — that should override it?"
undefined
"工具包默认推荐PostgreSQL（最佳开源EF提供程序）。是否存在组织层面的约束——比如已有的SQL Server许可、DBA支持——需要覆盖默认方案？"
undefined

Re-Running Workflows This Skill Doesn't Own

执行本工具不负责的工作流

undefined
undefined

BAD — improvising a health grading or init flow from this skill

错误示例——在本工具中临时编写健康评分或初始化流程

"Let me grade your codebase across 5 categories..."
"让我从5个维度为你的代码库评分..."

That grading conflicts with the canonical one.

该评分与标准评分体系冲突。

GOOD — route to the owner

正确示例——引导到对应负责工具

Init/CLAUDE.md → dotnet-init | Assessment → health-check | Upgrades → migrate
undefined
初始化/CLAUDE.md → dotnet-init | 评估 → health-check | 升级 → migrate
undefined

Decision Guide

决策指南

ScenarioRoute to
"Set up this project for Claude Code"
dotnet-init
"Which database/auth/caching should I use?"This skill — table above
"How healthy is this codebase?"
health-check
"Upgrade to .NET 10" / "update packages"
migrate
"Which architecture fits?"
architecture-advisor
Stack chosen, ready to build
scaffold
for the first feature
场景引导至工具
"为Claude Code搭建此项目"
dotnet-init
"我应该使用哪个数据库/认证/缓存？"本工具——参考上方表格
"我的代码库健康状况如何？"
health-check
"升级到.NET 10" / "更新包"
migrate
"哪种架构适合？"
architecture-advisor
已选定技术栈，准备开发
scaffold
（用于首个功能开发）