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

核心原则

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.
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.
License-aware picks — MediatR (v13+), MassTransit (v9+), and FluentAssertions (v8+) went commercial. The kit defaults to MIT alternatives: Mediator, Wolverine, plain xUnit asserts.
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.

给出默认推荐、说明理由、让用户自主选择 —— 每个维度都有工具包默认方案，但默认方案只是起点而非强制要求。用一句话说明取舍，让用户做出知情选择。
优先使用.NET内置功能而非第三方工具 —— 用
```
HybridCache
```
替代Redis客户端封装，用内置限流替代第三方包，用内置OpenAPI替代Swashbuckle。更少的依赖意味着更少的许可问题和升级中断风险。
考虑许可类型的选型 —— MediatR（v13+）、MassTransit（v9+）和FluentAssertions（v8+）已转为商用许可。工具包默认采用MIT许可的替代方案：Mediator、Wolverine、原生xUnit断言。
延迟添加消息传递，而非完全不添加 —— 大多数项目在初期不需要消息总线。默认选择“无（后续添加）”，当实际出现异步工作流时再选用Wolverine。

Patterns

模式

Tech-Stack Dimensions and Defaults

技术栈维度与默认方案

Dimension	Options	Default	Why
Database	PostgreSQL, SQL Server, SQLite	PostgreSQL	Open source, best EF Core provider outside SQL Server, first-class Testcontainers support
Auth	JWT Bearer, OIDC (Keycloak/Auth0), None	JWT Bearer	Simplest secure default for APIs; move to OIDC when an external IdP exists
Caching	HybridCache, Redis, None	HybridCache	Built-in, stampede protection, L1+L2 — add Redis only as its L2 backend
Messaging	Wolverine (RabbitMQ), MassTransit, None	None (add later)	Premature messaging adds ops burden; Wolverine (MIT) when needed
Observability	Serilog + OpenTelemetry, Basic logging	Serilog + OTEL	Structured logs + traces from day one are cheap; retrofitting is not
Resilience	Polly v8 pipelines, Basic retry	Polly v8	`AddStandardResilienceHandler()` is one line for production-grade defaults
API docs	Built-in OpenAPI + Scalar	OpenAPI + Scalar	Framework-maintained spec generation; Scalar replaces Swagger UI
Testing	xUnit v3 + Testcontainers	xUnit v3 + Testcontainers	Real 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, SQLite	PostgreSQL	开源，是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 + Scalar	OpenAPI + Scalar	由框架维护的规范生成；Scalar替代Swagger UI
测试	xUnit v3 + Testcontainers	xUnit 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

决策指南

Scenario	Route 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` （用于首个功能开发）