NetFabric/NetFabric.Numerics / .agents/skills/dotnet-agent-guardrails
dotnet-agent-guardrails
VerifiedDeterministic guardrails for defining the review/validation process in .NET/C# development agents and agent squads: .editorconfig + dotnet format, TreatWarningsAsErrors, custom Roslyn analyzers, full test suites, Aspire telemetry, and Copilot/Claude Code hooks as the gates a change must pass. USE FOR: defining what 'done' means and which deterministic checks gate an agent-generated .NET change before merge, for a single agent or a squad of agents/subagents sharing a repo. DO NOT USE FOR: general AGENTS.md authoring for non-.NET repos (agents-md); C# style rules (csharp-best-practices); non-agent solution scaffolding (dotnet-solution-setup); BenchmarkDotNet usage (dotnet-benchmarking).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.2 KB |
| references/aspire-agent-native.md | markdown | 2.2 KB |
| references/conventions-and-analyzers.md | markdown | 3.7 KB |
| references/hooks-governance.md | markdown | 1.9 KB |
| references/testing-contract.md | markdown | 1.6 KB |
references/conventions-and-analyzers.md
View on GitHub# Conventions & Analyzers
## .editorconfig + dotnet format
`.editorconfig` defines indentation, spacing, naming conventions, `using` ordering, and analyzer severities — enforceable identically by every editor, IDE, and CLI. It removes the ambiguity that produces inconsistent agent output.
[`dotnet format`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-format) applies the rules in `.editorconfig` across the whole solution:
```bash
dotnet format # fix whitespace, style, and analyzer-fixable issues
dotnet format --verify-no-changes # CI check: fails if anything would change
```
- Anything it can't auto-fix surfaces as a diagnostic that must be resolved manually.
- Exit code `0` means the codebase fully complies with the conventions — use this as the literal "done" signal in AGENTS.md/CLAUDE.md.
- Run `dotnet format --verify-no-changes` in CI so drift never merges.
## Warnings as Errors
[`TreatWarningsAsErrors`](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/errors-warnings#treatwarningsaserrors) turns every compiler warning into a build failure. Set it once, repo-wide, in `Directory.Build.props`:
```xml
<PropertyGroup>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
```
`Directory.Build.props` centralizes MSBuild properties for every project under the directory tree — one place instead of repeating settings across dozens of `.csproj` files. Full property list (Nullable, ImplicitUsings, EnforceCodeStyleInBuild, EnableNETAnalyzers, etc.) → [dotnet-solution-setup/references/directory-build-props.md](../../../../apm_modules/netfabric/intelligentium/plugins/dotnet/.apm/skills/dotnet-solution-setup/references/directory-build-props.md).
Why it matters for agents: a permissive compiler leaves room for interpretation; a strict one reports nullability, unreachable code, unused variables, and API misuse the same way every time. That determinism is what an agent (or reviewer) can react to reliably.
## Roslyn Analyzers as Architecture Enforcement
[Roslyn analyzers](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/overview?tabs=net-10) run at compile time and report diagnostics when code violates a rule — deterministic, since the same code always produces the same diagnostics.
- The .NET SDK ships built-in analyzers for correctness/performance/style; NuGet adds framework-specific ones (ASP.NET Core, EF Core, security).
- When neither covers a project-specific architecture or domain constraint, write a custom analyzer.
**Scaffolding a custom analyzer project:**
1. Create a standard C# class library referencing the Roslyn SDK (`Microsoft.CodeAnalysis.CSharp`, `Microsoft.CodeAnalysis.Analyzers`).
2. Implement rules against syntax trees or the semantic model.
3. Reference it from the analyzed project as an analyzer, not a runtime dependency:
```xml
<ProjectReference Include="..\BookStore.ApiService.Analyzers\BookStore.ApiService.Analyzers.csproj"
OutputItemType="Analyzer"
ReferenceOutputAssembly="false" />
```
`OutputItemType="Analyzer"` + `ReferenceOutputAssembly="false"` tells MSBuild to load the analyzer during compilation without adding a runtime reference to its assembly.
Once wired, an agent that introduces a violation fails the build on every subsequent compile until the code is fixed — the analyzer enforces the architecture rather than relying on the agent remembering it.
### Agents Can Help Build Analyzers
Agents can propose rule definitions from recurring codebase patterns, scaffold the initial analyzer + code-fix, refine rules against failing diagnostics, and update analyzers as the architecture evolves. This is a feedback loop: analyzers guide agents, agents help maintain analyzers.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |