Architecture Guardian documentation
Define architectural boundaries in YAML and enforce them in your .NET codebase. These guides explain how to install the product, model your architecture, interpret findings, and share a policy across your editor, CI pipeline and coding agents.
Choose your starting point
Section titled “Choose your starting point”| I want to… | Start here |
|---|---|
| Run my first architecture check | Install the CLI, then follow the quick start |
| Understand the model before writing YAML | Architecture as code, then modules, layers and contracts |
| Learn the configuration language | Write a YAML policy, then use the complete reference |
| Get IDE/build feedback | Install the Roslyn analyzer |
| Check pull requests in CI | Add an independent quality gate |
| Give an AI agent architecture context | Configure MCP, then use the agent workflow |
| Evaluate cost and coverage | Benchmarks, engine differences and known limitations |
Your first architecture gate
Section titled “Your first architecture gate”- Install and verify the tool. CLI/MCP need .NET 10 and the SDK required by the repository you analyze. Use the released NuGet packages.
- Choose a complete scope. Map every loaded project, including references, to exactly one module and layer in a first policy.
- Restore, inspect and scan. Use the same configuration/framework for preparation and analysis.
- Repair a real violation. Try the downloadable examples, inspect evidence, correct the dependency and rerun the gate.
- Keep the check in your workflow. Share YAML with the analyzer and add a solution scan to CI. Use MCP when an agent should inspect and validate architecture.
The quick start takes you through these steps. The installed tools and downloadable samples do not require an Architecture Guardian source checkout.
Core concepts
Section titled “Core concepts”- Architecture as code: how policy, observed code and enforcement fit together.
- Modules, layers and contracts: ownership, technical direction and intentionally shared APIs.
- Dependency analysis: observed evidence, semantic scope and static-analysis limits.
- Diagnostics and outcomes: findings, completion, severities and gates.
Find the task you need
Section titled “Find the task you need”| Use case | Guidance |
|---|---|
| Keep Clean Architecture dependencies pointing inward | Layer boundaries, AG002 and explicit Domain restrictions |
| Isolate a modular monolith | Contracts and cycles, AG001/AG003/AG004 |
| Keep frameworks out of business logic | Technology restrictions, AG005/AG006 and exceptions |
| Adopt enforcement with existing debt | Baseline adoption and Git analysis |
| Make agents respect boundaries | Inspect, implement, validate and correct |
Integrations and reference
Section titled “Integrations and reference”Use the CLI, MCP, analyzer and CI guides for integration. Exact contracts are in the YAML reference, AG001–AG006 catalog, JSON/SARIF reports, baselines, Git comparison, and compatibility policy. Operational guidance covers workspace loading, performance and telemetry and troubleshooting.
Know when a result is usable
Section titled “Know when a result is usable”| CLI exit | Meaning | Next action |
|---|---|---|
0 | Analysis completed and the selected gate passed | Continue with normal build, tests and review |
1 | Analysis completed and the gate failed | Correct or explicitly review the architecture finding, then rescan |
2 | Invalid input, incomplete analysis, failure or cancellation | Resolve the operational issue and rerun before drawing a compliance conclusion |
For MCP, check both status and gateOutcome. Compiler feedback covers its host
compilation; retain solution scans for broader context and AG003 cycles. A
new-finding gate may pass while existing errors remain. An empty incomplete result
never establishes a successful gate.
See release notes and the roadmap for changes and plans. Report reproducible problems through GitHub issues, including tool version, build context, relevant policy and redacted diagnostics.