Skip to content

CLAUDE.md

Latest commit

 

History

History
226 lines (162 loc) · 10.2 KB

CLAUDE.md

File metadata and controls

226 lines (162 loc) · 10.2 KB
Raw

dotnet-claude-kit — Development Instructions

These instructions are for developing THIS repository. For user-facing project templates, see templates/.

Repository Purpose

dotnet-claude-kit is an opinionated Claude Code companion for .NET developers. It provides skills, agents, templates, knowledge documents, and a Roslyn MCP server that make Claude Code dramatically more effective for .NET development.

Philosophy

  • Guided over prescriptive — We ask the right questions, then recommend the best approach with clear rationale
  • Modern .NET only — Target .NET 10 and C# 14. No legacy patterns, no backwards compatibility with .NET Framework
  • Architecture-aware — We support VSA, Clean Architecture, DDD, and Modular Monolith with an advisor skill that recommends the best fit (see ADR-005)
  • Token-conscious — Every file respects context window limits. Skills max at 400 lines
  • Practical over theoretical — Every recommendation includes a code example and a "why"

Skill Structure

Skills follow the Agent Skills open standard. Each skill lives at skills/<skill-name>/SKILL.md.

Frontmatter Schema (Required)

---
name: skill-name           # kebab-case, matches directory name
description: >
  What this skill does and when Claude should load it.
  Include trigger keywords and specific scenarios.
---

Required Sections

  1. Core Principles — 3-5 numbered, opinionated defaults with rationale
  2. Patterns — Code examples with explanation. Each pattern has:
    • A descriptive heading
    • Working C# code (must compile conceptually)
    • Brief explanation of why this is the recommended approach
  3. Anti-patterns — What NOT to do, with BAD/GOOD code comparison
  4. Decision Guide — Markdown table: Scenario → Recommendation

Quality Standards

  • Maximum 400 lines — Every line must earn its place. Respect token budgets.
  • Every recommendation has a "why" — No bare rules without justification
  • Code examples must be modern C# — Primary constructors, collection expressions, file-scoped namespaces, records
  • No Swashbuckle — Use built-in .NET OpenAPI support
  • No repository pattern over EF Core — Use DbContext directly
  • TimeProvider over DateTime.Now — Always

Agent Structure

Agents live at agents/<agent-name>.md.

Frontmatter Schema (Required)

---
name: agent-name           # kebab-case, matches file name
description: >
  What this agent is an expert in and when Claude should delegate to it.
  Include concrete trigger scenarios — Claude routes subagent work based on this.
model: sonnet              # optional — tier alias only (fable/opus/sonnet/haiku), never a pinned version ID
memory: project            # optional — persistent agent memory scope
disallowedTools: Write, Edit  # optional — tools the agent must never use (e.g. read-only reviewers)
isolation: worktree        # optional — run the agent in an isolated git worktree
---

Plugin agents must NOT declare permissionMode, hooks, or mcpServers — those fields are reserved for user/project-level agents. The optional memory, disallowedTools, and isolation fields ARE allowed — use them deliberately (e.g. disallowedTools: Write, Edit keeps review agents read-only; isolation: worktree isolates cleanup agents).

Required Sections

Below the frontmatter, each agent contains:

  1. Role definition — What this agent is an expert in
  2. Skill dependencies — Which skills this agent loads (by name)
  3. MCP tool usage — When to use cwm-roslyn-navigator tools vs reading files
  4. Response patterns — How to structure guidance
  5. Boundaries — What this agent does NOT handle

Template Structure

Templates live at templates/<template-name>/. Each contains:

  • CLAUDE.md — Drop-in file for user projects
  • README.md — When and how to use this template

Templates reference skills by name and should be self-contained — a user copies just the CLAUDE.md into their project.

Knowledge Documents

Knowledge files at knowledge/ are NOT skills. They're reference material that agents and templates point to. They don't follow the skill frontmatter format.

  • dotnet-whats-new.md — Updated per .NET release
  • common-antipatterns.md — Patterns Claude should never generate
  • package-recommendations.md — Vetted NuGet packages
  • breaking-changes.md — Migration gotchas
  • decisions/*.md — ADRs using the template format

Workflow Skill Structure (Orchestrators)

Claude Code merged slash commands into skills, so the kit no longer has a commands/ directory. Workflow orchestrators (e.g., /verify, /scaffold, /tdd) are skills like any other — they live at skills/<name>/SKILL.md and register /name automatically — but follow a different body structure than knowledge skills.

Frontmatter Schema (Required)

---
name: workflow-name        # kebab-case, matches directory name; registers /workflow-name
description: >
  What this workflow does and its trigger phrases.
# Optional: disable-model-invocation: true — for explicit /name invocation only
---

Required Sections

  1. What — What the workflow does
  2. When — When to use it (trigger phrases)
  3. How — Step-by-step execution flow (invokes skills/agents)
  4. Example — Example output or usage
  5. Related — Related workflows

Quality Standards

  • Maximum 200 lines — Orchestrators are not encyclopedias (knowledge skills get 400)
  • One skill per concern — A workflow skill carries its methodology inline; never create a separate knowledge twin for a workflow (no verify + verification-loop pairs). Twin skills double the always-loaded description surface and cause routing collisions.
  • Deep reference material goes in references/ — If methodology genuinely exceeds the budget (e.g. per-architecture code templates), put it in skills/<name>/references/<topic>.md and point to it from SKILL.md. References load only on demand — this is the token-friendly progressive-disclosure pattern.
  • Clear trigger phrases — Users should know when to reach for this workflow. When merging skills, the surviving description must absorb the absorbed skill's trigger phrases.

Rule Structure

Rules live at .claude/rules/<rule-name>.md. Rules are always loaded into context.

Frontmatter Schema (Required)

---
alwaysApply: true
description: >
  What this rule enforces.
---

Quality Standards

  • Maximum 100 lines — Rules are always in context, so every line costs tokens
  • Prescriptive with rationale — Each rule has a brief "why"
  • DO/DON'T format — Clear, scannable rules
  • Total rules budget: ~600 lines — All rules combined must stay lean

Roslyn MCP Server

The MCP server lives at mcp/CWM.RoslynNavigator/. It's a .NET 10 application using the ModelContextProtocol SDK.

Building

dotnet build mcp/CWM.RoslynNavigator/CWM.RoslynNavigator.slnx
dotnet test mcp/CWM.RoslynNavigator/CWM.RoslynNavigator.slnx

Key Rules

  • Tools are read-only — No code generation, no modifications
  • Responses are token-optimized — Return file paths, line numbers, and short snippets, never full file contents
  • The workspace must handle graceful loading — Return "loading" status instead of errors during initialization

Workflow Standards

How Claude should work on this repository (and any project using dotnet-claude-kit templates).

Plan Before Building

  • Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
  • Iterate on the plan until it's solid before writing code
  • If something goes sideways mid-implementation, STOP and re-plan — don't keep pushing through a broken approach
  • Write detailed specs upfront to reduce ambiguity — vague plans produce vague code

Verify Before Done

  • Never mark a task complete without proving it works
  • Run dotnet build and dotnet test after changes — green builds are the minimum bar
  • Use get_diagnostics via the Roslyn MCP to catch warnings after modifications
  • Ask yourself: "Would a staff .NET engineer approve this?" — if not, iterate
  • Diff behavior between main and your changes when relevant

Fix Bugs Autonomously

  • When given a bug report: investigate and fix it. Don't ask for hand-holding
  • Point at logs, errors, failing tests — then resolve them
  • Go fix failing CI tests without being told how
  • Zero context switching required from the user

Demand Elegance (Balanced)

  • For non-trivial changes: pause and ask "is there a more elegant way?"
  • If a fix feels hacky, step back: "Knowing everything I know now, implement the elegant solution"
  • Skip this for simple, obvious fixes — don't over-engineer. Three lines of clear code beats a premature abstraction
  • Challenge your own work before presenting it

Use Subagents for Parallel Work

  • Use subagents liberally to keep the main context window clean
  • Offload research, exploration, and parallel analysis to subagents
  • One task per subagent for focused execution
  • For complex problems, throw more compute at it via subagents rather than doing sequential work

Learn from Corrections

  • After ANY correction from the user, capture the pattern in auto memory (MEMORY.md)
  • Write rules that prevent the same mistake from recurring
  • Review memory at session start for project-relevant lessons
  • This is a compounding system — mistake rate should drop over time

Contribution Workflow

  1. Check the spec at docs/dotnet-claude-kit-SPEC.md for the full vision
  2. Follow the skill/agent/template/command/rule structure defined above
  3. Run dotnet format --verify-no-changes before committing
  4. Ensure knowledge skills stay under 400 lines, workflow/orchestrator skills under 200, rules under 100
  5. Every new pattern needs a BAD/GOOD code comparison in Anti-patterns
  6. Ensure all cross-references (skills → skills, agents → skills) resolve to real files
  7. All orchestrators are skills — never create a commands/ directory; workflow skills need name + description frontmatter
  8. New rules must have alwaysApply: true in frontmatter
  9. Agents must have YAML frontmatter with name and description (trigger scenarios included); model references use tier aliases only