LoadBearing

LoadBearing is a .NET architecture checker that enforces one C# spec and renders the same rules for coding agents.

A long-lived codebase has layers, boundaries and rules. They live in a few heads, no build step checks them, and the diagrams drift. Nothing fails when a change crosses a boundary. A coding agent makes that change quickly and plausibly, and it cannot see which walls are load-bearing. LoadBearing's answer is architecture-as-code. The rules become one C# spec, and the spec produces every surface this page names.

1. Enforcement. One checker passes or fails the rules at the command line, in CI and as named xUnit tests. An agent hook runs the same check when the agent's turn ends.
2. Agent context. The rules render to a managed AGENTS.md block, per-directory rule cards and MCP query tools for coding agents.

Write your architecture once. Use it everywhere.

LoadBearing is pre-alpha. Minor versions can still change the spec API before 1.0. Status holds the current inventory.

Install the tool, build your solution, and check it:

dotnet tool install -g Zphil.LoadBearing.Cli
dotnet build MyApp.sln
loadbearing check MyApp.sln

A rule is one statement:

arch.Rule("layering/domain-independent")
    .Enforce(domain.MustNotReference(application, infrastructure, api))
    .Because("The Domain holds the quote and rate model the rest of the subsystem is built on; it stays free of the layers that depend on it so it can be reasoned about and tested on its own.")
    .Fix("Move the dependency out of Domain: define an interface here and implement it in the outer layer that needs it.");

That is the whole rule. It has an ID, a posture, a constraint, a reason and a fix. Here the posture is Enforce. The rule is committed in the clean-architecture example, and CI holds check green against the codebase it governs.

When an agent breaks a rule

Rules like the one above govern this repository too. One of them keeps the CLI off stdout, because the MCP server speaks JSON-RPC over that channel. Suppose an agent adds a progress printer to the CLI and reaches for Console.WriteLine. When it tries to hand the work back, the Stop hook in hooks/ runs check over the working tree, the rule goes red, and the hook refuses the stop with this report on the agent's stderr:

FAIL cli/no-stdout — The Host layer must not use `Console.Out`, `Console.Write()` or `Console.WriteLine()`.
  because: Stdout is a protocol channel here — the MCP server speaks JSON-RPC over it and CLI output flows through System.CommandLine's console — so a direct Console write corrupts the wire and is invisible to the in-process tests.
  citation: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio
  fix: Write CLI output through the command's InvocationConfiguration console; route server diagnostics to the logger or Console.Error.
  subject: 160 types, 1 generated
  src/Zphil.LoadBearing.Cli/Rendering/ProgressPrinter.cs:10 — Zphil.LoadBearing.Cli.Rendering.ProgressPrinter uses System.Console.WriteLine()
  src/Zphil.LoadBearing.Cli/Rendering/ProgressPrinter.cs:15 — Zphil.LoadBearing.Cli.Rendering.ProgressPrinter uses System.Console.WriteLine()

Every line of that report is something the agent can act on without asking a human. The agent routes the output through the command's console instead, and the next stop is clean.

LoadBearing on itself shows this repository's own spec on the other surfaces too, from the committed rule and the prose it renders to the xUnit run, code scanning and the graph. It also says how every excerpt on both pages is held to its source.

The four postures

Every rule carries one of the first two, and every scope one of the last two.

Enforce failing violations that predate it is what Migrate exists for: loadbearing baseline records a rule's current violations, new ones fail from the next commit, and the baseline only shrinks. At zero, the tool suggests promoting the rule to Enforce. Every scope carries a diff-aware tripwire: with check --diff-base <ref>, a change set that touches the scope draws a warning. For a Caution scope that tripwire is the whole posture: the dragons prose lands on the scope's directory as a card, explain and arch_context serve it, and no reference into the scope is ever a violation.

The three postures after Enforce each answer a way a coding agent goes wrong on an established codebase. Enforce is the law the code already keeps, and a change that crosses it fails wherever the check runs. The Meridian example walks three of those ways on real output.

• An agent copies the majority pattern, the statistical prior. Six of Meridian's eight controllers open a SqlConnection, so inline SQL reads as house style and an agent writes its next controller the same way. Migrate answers it: the rendered context calls that pattern debt rather than style, in words the agent reads before it writes.
• An agent tidies away a gateway, the helpful refactor. A public type inside a module invites a direct call that skips the gateway in front of it. A Quarantine scope makes the gateway the only sanctioned way in.
• An agent corrects load-bearing weirdness. A check-digit table that skips values looks like a bug, and making it contiguous breaks every real container number. The dragons prose on a Quarantine or Caution scope answers it. The card on that scope's directory says what the code does, which part is load-bearing, and how to call in.

One spec produces

Each target below consumes the same reified model, and every violation report carries the rule ID, the generated rule sentence, the reason, the fix, and the exact file:line.

The adapter's failure text is byte-identical to the CLI's: the two share one renderer, and a product test pins them equal. The managed block plus loadbearing explain are also the generated architecture documentation, written for agents first and readable by people; LoadBearing on itself shows the gate that keeps it current.

Claude Code reads AGENTS.md on its own from version 2.1.277, including each per-directory card once it opens a file in that directory. It does so only where no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the directory it was started in or any directory above it. Your own ~/.claude/CLAUDE.md does not count. A repository that already has a CLAUDE.md brings the managed block in with one line in that file, @AGENTS.md, and render warns when it finds such a file without the import. The import covers the root file only. The cards load beside a CLAUDE.md for each developer who sets Claude Code's Project instructions option to claude-md-and-agents-md in /config. That option is a personal setting, and a repository cannot commit it.

The compiler is the source of truth for your code. LoadBearing is the source of truth for your architecture.

Where this sits next to ArchUnitNET and NetArchTest

NetArchTest and ArchUnitNET run architecture rules inside your unit tests, and they are good at it. LoadBearing moves the rules out of test code into one spec (architecture-as-code rather than architecture tests) and renders every surface above from it.