convention-learner

規約の学習

基本原則

1. 強制する前に観察する — 既存のコードベースを分析せずに、規約を押し付けてはいけません。internal sealed class のハンドラーが200個あるプロジェクトに、新たな public class のハンドラーを追加してはいけません。まず検出し、その後で合わせます。
2. プロジェクトの規約は一般的なルールより優先される — プロジェクトで *Handler ではなく *Service を使っている場合、キットの既定値と異なっていても、プロジェクトの規約に従います。明示的な .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 + 比較
規約の競合（キットとプロジェクト）	プロジェクトを優先	—
規約の競合（チーム内の意見の相違）	両方を記録し、.editorconfig を提案	—
規約が検出されない	キットのデフォルトを使用し、記録する	architecture-advisor スキル
繰り返し見られるアンチパターン	CLAUDE.md の規約に追加	detect_antipatterns
新しいチームメンバーのオンボーディング	検出を実行し、規約ドキュメントを生成	検出フロー全体
.editorconfig が存在する	それを信頼し、上書きしない	.editorconfig を読み取る
.editorconfig が存在しない	検出されたパターンに基づく作成を提案	検出 + 生成
パターンが一度だけ見られた	instinct-system スキルで確信度 0.3 のインスティンクトを作成	instinct-system
パターンが 3 回以上確認された	インスティンクトが自動的に 0.7 に昇格。CLAUDE.md への追加を提案	instinct-system