convention-learner

约定学习器

核心原则

1. 先观察，再强制执行 — 在分析现有代码库之前，绝不强加约定。一个包含 200 个 internal sealed class 处理程序的项目，不应该新增 public class 处理程序。先检测，再匹配。
2. 项目约定优先于通用规则 — 如果项目使用 *Service 而不是 *Handler，就遵循项目约定，即使工具包默认设置不同。明确的 .editorconfig 和 Directory.Build.props 规则始终优先。
3. 使用 MCP 工具进行分析 — get_public_api 会揭示命名模式，get_project_graph 会展示结构约定，detect_antipatterns 会跟踪质量趋势。工具提供客观数据；读取文件则用于确认。
4. 记录发现 — 检测到约定后，建议将其添加到项目的 CLAUDE.md。未记录的约定会随着原开发人员离开而失传。
5. 一致性胜过完美 — 数据库列名统一使用 snake_case 的项目，胜过一半使用 snake_case、另一半使用 PascalCase 的项目。匹配现有模式，即使理论上另一种约定更优。

模式

约定检测流程

系统地分析项目的编码约定。加入现有项目或生成新代码前，请运行此流程。

步骤 1：项目结构分析

→ get_project_graph
  Detect:
  - Project naming: PascalCase? Dots? (MyApp.Domain vs Domain)
  - Layer organization: by layer (Domain/Application/Infrastructure) or by feature?
  - Test project naming: *.Tests, *.UnitTests, *.IntegrationTests?
  - Shared project: Common/, Shared/, BuildingBlocks/?

步骤 2：类型命名模式

→ get_public_api (on 3-5 key types across different layers)
  Detect:
  - Class modifiers: sealed? internal? internal sealed?
  - Interface prefix: I* (standard) or no prefix?
  - Suffix conventions: Handler, Service, Repository, Validator, Endpoint?
  - Record usage: for DTOs? for value objects? for commands/queries?
  - Primary constructor usage: consistently? selectively?

步骤 3：文件夹结构模式 扫描文件系统，查找结构约定：

• 功能文件夹：是否使用 Features/{FeatureName}/，并将所有文件放在一起？
• 分层文件夹：是否将 Controllers/、Services/、Repositories/ 分开？
• 共享模式：是否使用 Common/、Extensions/、Middleware/？
• 配置位置：根目录？Config/ 文件夹？Infrastructure/？

步骤 4：配置检测 检查是否存在明确的约定强制规则：

→ Look for Directory.Build.props
  - TreatWarningsAsErrors?
  - Nullable enabled globally?
  - ImplicitUsings?
  - AnalysisLevel?

→ Look for .editorconfig
  - Naming rules: camelCase fields? _prefixed privates?
  - Code style: var preferences, expression bodies, using placement

→ Look for global.json
  - SDK version pinned?
  - Roll-forward policy?

步骤 5：编写约定摘要 将发现整理成结构化摘要：

## Detected Conventions

### Naming
- Classes: `internal sealed class` (95% of handlers/services)
- Suffixes: Handlers end in `Handler`, validators in `Validator`
- Records: Used for DTOs and commands/queries

### Structure
- Architecture: Vertical Slice Architecture
- Features: `Features/{Name}/` with command, handler, validator, endpoint in one file

### Code Style
- Primary constructors: Used consistently for DI injection
- Nullable: Enabled globally, no suppressions (`!`) used
- File-scoped namespaces: 100% consistent

根据需要添加类别：EF Core（配置、命名、迁移）、测试（框架、命名、测试夹具）等。

约定执行

生成新代码或审查现有代码时，应用检测到的约定。

生成代码时： 匹配每一种检测到的模式：

// If existing handlers are: internal sealed class + primary constructor
// Generate matching:
internal sealed class CreateProductHandler(AppDbContext db, TimeProvider clock)
{
    // Not: public class CreateProductHandler
    // Not: internal class CreateProductHandler (missing sealed)
}

// If existing DTOs are records with init properties
// Generate matching:
public record ProductResponse(Guid Id, string Name, decimal Price);
// Not: public class ProductResponse { public Guid Id { get; set; } }

审查代码时： 标记偏离检测到的约定之处：

⚠️ Convention violation: CreateOrderHandler is `public class` but project convention
   is `internal sealed class` (detected in 12/12 existing handlers).
   Change to: internal sealed class CreateOrderHandler

建议强制规则时： 检测到约定后，建议添加 .editorconfig 规则，以便自动强制执行：

# Key .editorconfig rules to suggest based on detected conventions
dotnet_diagnostic.CA1852.severity = warning           # Seal internal types
csharp_style_namespace_declarations = file_scoped:warning
csharp_style_prefer_primary_constructors = true:suggestion
# Add dotnet_naming_rule entries for private field prefix (_camelCase) if detected

反模式跟踪

使用 detect_antipatterns 跟踪多个会话中反复出现的质量问题。

定期检查：

→ detect_antipatterns (scope: solution)
  Track over time:
  - Are the same patterns recurring? (DateTime.Now keeps appearing)
  - Are new patterns emerging? (new HttpClient() in a new module)
  - Is the count trending up or down?

确定优先级：

| Anti-pattern | Count | Trend | Priority |
|-------------|-------|-------|----------|
| DateTime.Now | 12 | ↑ +3 | High — add to CLAUDE.md conventions |
| async void | 1 | → same | Medium — one-off fix |
| new HttpClient | 0 | ↓ -2 | Low — already fixing |

当模式反复出现时，将明确规则添加到 CLAUDE.md：

## Conventions
- **NEVER use DateTime.Now** — Use TimeProvider.GetUtcNow() (12 violations found, fixing)

反模式

未经检测就强制执行

# BAD — Imposing kit defaults on a project with its own conventions
"All handlers should be internal sealed class"
# But this project uses public class with interfaces for testing

# GOOD — Detect first, then follow what exists
→ get_public_api reveals: 8/8 handlers are `public class` implementing `IHandler<T>`
"This project uses public handlers with interfaces. Matching that convention."

覆盖明确的项目规则

# BAD — Ignoring .editorconfig because kit says otherwise
# .editorconfig says: csharp_style_expression_bodied_methods = false
# But generating expression-bodied methods anyway

# GOOD — .editorconfig and Directory.Build.props always win
"Your .editorconfig disables expression-bodied methods.
I'll use block-bodied methods to match your project settings."

将通用约定应用于非典型项目

# BAD — Forcing Clean Architecture naming on a VSA project
"You need a Services/ folder and a Repositories/ folder"
# But this project uses feature folders with everything co-located

# GOOD — Match the project's organizational convention
"This project uses feature folders. I'll add the new feature
at Features/Shipping/ with all related files together."

在没有证据的情况下记录约定

# BAD — "Conventions" based on reading one file
"Convention: Use var everywhere" (based on seeing var in one method)

# GOOD — Document only patterns confirmed across multiple files
→ get_public_api on 5 types: 100% use explicit types for non-obvious cases
"Convention: Use explicit types for non-obvious cases (e.g., method returns),
var for obvious cases (e.g., new MyClass()). Confirmed across 5 files."

决策指南

场景	操作	工具
加入现有项目	运行完整的约定检测流程	get_project_graph, get_public_api
生成新代码	先检查已检测到的约定	之前的检测结果
审查代码	标记偏离约定的情况	get_public_api + comparison
约定冲突（工具包与项目）	以项目为准	—
约定冲突（团队意见不一致）	记录双方意见，并建议使用 .editorconfig	—
未检测到约定	使用工具包默认设置，并记录下来	architecture-advisor skill
反复出现的反模式	将其添加到 CLAUDE.md 约定中	detect_antipatterns
新团队成员入职	运行检测，生成约定文档	完整检测流程
存在 .editorconfig	信任其设置，不要覆盖	读取 .editorconfig
不存在 .editorconfig	建议根据检测到的模式创建一个	检测 + 生成
某个模式只出现过一次	通过 instinct-system skill 以 0.3 置信度创建直觉	instinct-system
某个模式确认出现 3 次或以上	直觉会自动晋升至 0.7，建议将其添加到 CLAUDE.md	instinct-system