.NET Development in the Code Agent Era

Code agents are non-deterministic — the same prompt can yield different code. The .NET toolchain is deterministic by design; wire it up as guardrails instead of trusting agent output alone.

Anatomy

File	Purpose
SKILL.md	Guardrail overview + AGENTS.md wiring
references/conventions-and-analyzers.md	.editorconfig, dotnet format, TreatWarningsAsErrors, custom Roslyn analyzer projects
references/testing-contract.md	Test tiers as the behavioral contract, agent failure-triage pattern
references/aspire-agent-native.md	Aspire orchestration, telemetry, and agent-as-service integration
references/hooks-governance.md	Hooks as a governance layer, hook categories, file-based C# scripts

The Six Guardrails

Guardrail	Tool	Enforces	Config
Conventions	dotnet format + .editorconfig	style, naming, import order	.editorconfig
Compiler strictness	TreatWarningsAsErrors	nullability, unreachable code, API misuse	Directory.Build.props
Architecture	custom Roslyn analyzer project	domain/architecture rules with no built-in analyzer	ProjectReference OutputItemType="Analyzer"
Behavior	full test suite (unit/integration/e2e)	correctness, regressions	CI + AGENTS.md instruction
Runtime	Aspire AppHost	service wiring, config, telemetry	AppHost project
Actions	agent hooks	intercept/validate agent edits before they land	hook scripts (file-based C#)

Each is deterministic: same input, same result, every run. That stability is what lets an agent self-correct across turns instead of drifting.

AGENTS.md Wiring

Encode "done" in operational, checkable terms — not "write clean code":

Run `dotnet format` to ensure code style compliance. Issues not automatically fixed
must be resolved manually. A feature is not complete until `dotnet format` exits
with code 0 and the full test suite passes.

Directory.Build.props — Minimum

<PropertyGroup>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>

Set once in Directory.Build.props at the repo root so every project inherits it — see dotnet-solution-setup for the full shared-properties list.

Practical Example

BookStore applies all six guardrails (conventions, analyzers, tests, Aspire, hooks) in one open-source .NET solution.

Reference Files

File	Load When
references/conventions-and-analyzers.md	Wiring .editorconfig/dotnet format/TreatWarningsAsErrors, or scaffolding a custom Roslyn analyzer project
references/testing-contract.md	Deciding test tiers, writing AGENTS.md test instructions, triaging agent-caused test failures
references/aspire-agent-native.md	Using Aspire orchestration/telemetry so an agent can reason about a running distributed system
references/hooks-governance.md	Writing or categorizing Copilot/Claude Code hooks that gate agent actions