/convention-learner

name: convention-learner
description: >
  Detects and enforces project-specific coding conventions by analyzing
  existing codebase patterns. Learns naming conventions, folder structure,
  test organization, and coding style from the existing code.
  Load when: "conventions", "coding standards", "project patterns",
  "enforce style", "detect patterns", "learn conventions", "code consistency".

Convention Learner

Core Principles

1. **Observe before enforcing** — Never impose conventions without first analyzing the existing codebase. A project with 200 `internal sealed class` handlers should not get a new `public class` handler. Detect first, then match. 2. **Project conventions override generic rules** — If the project uses `*Service` instead of `*Handler`, follow the project's convention even if the kit default is different. Explicit `.editorconfig` and `Directory.Build.props` rules always win. 3. **Use MCP tools for analysis** — `get_public_api` reveals naming patterns, `get_project_graph` shows structure conventions, `detect_antipatterns` tracks quality trends. Tools provide objective data; file reads provide confirmation. 4. **Document findings** — After detecting conventions, suggest adding them to the project's CLAUDE.md. Undocumented conventions are lost when the original developers leave. 5. **Consistency over perfection** — A project with consistent `snake_case` database columns is better than a project with half `snake_case` and half `PascalCase`. Match the existing pattern, even if another convention is theoretically superior.

Patterns

Convention Detection Flow

Systematic analysis to understand a project's coding conventions. Run this when joining an existing project or before generating new code.

**Step 1: Project Structure Analysis**

→ 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/?

**Step 2: Type Naming Patterns**

→ 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?

**Step 3: Folder Structure Patterns** Scan the file system for structural conventions:

• Feature folders: `Features/{FeatureName}/` with all files together?
• Layer folders: `Controllers/`, `Services/`, `Repositories/` separate?
• Shared patterns: `Common/`, `Extensions/`, `Middleware/`?
• Configuration location: root? `Config/` folder? `Infrastructure/`?

**Step 4: Configuration Detection** Check for explicit convention enforcers:

→ 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?

**Step 5: Build Convention Summary** Compile findings into a structured summary:

## 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

Add categories as needed: EF Core (configurations, naming, migrations), Testing (framework, naming, fixtures), etc.

Convention Enforcement

Apply detected conventions when generating new code or reviewing existing code.

**When Generating Code:** Match every detected pattern:

// 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; } }

**When Reviewing Code:** Flag deviations from detected conventions:

⚠️ 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

**Suggesting Enforcement Rules:** After detecting conventions, suggest `.editorconfig` rules to enforce them automatically:

# 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

Anti-pattern Tracking

Use `detect_antipatterns` to track recurring quality issues across sessions.

**Periodic Check:**

→ 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?

**Prioritization:**

| Anti-pattern | Count | Trend | Priority |
|-------------|-------|-----