The System Guardrails Pyramid - How to get better code from AI agents

I've been exploring software factories and how to build faster while maintaining quality with AI agents.

My current theory is:

• Durable Context, Disposable Code - The context around what the system is supposed to do is far more important now that code is cheap.
• Durable Context Hierarchies - Ways to structure the context so the requirements of the system are clear and organized.
• System Guardrails - Hierarchies of guardrails to enforce that the system actually does what it's supposed to do.

Here I want to talk about the System Guardrails Pyramid and how to think about setting up your system to continuously improve.

The System Guardrails Pyramid

System Guardrails are similar to the testing pyramid. The idea is to shift feedback left in the development cycle. The farther left it is, the earlier and cheaper it is to course correct.

The testing pyramid favors many fast, focused tests and fewer tests with broader system scope. Broader scope allows you to test more things (especially the interaction between things) but typically suffers in speed, cost, and determinism.

• Unit tests - Fast, cheap checks of focused behavior in isolation. Use many of these.
• Integration tests - Check components working together, such as vertical slices, backend workflows, APIs, and database. Use these to catch boundary and wiring failures.
• E2E tests - Check complete user journeys. Usually slower and more prone to flakiness, so focus on critical flows.

System Guardrails are similar:

• Structural Guardrails - Provide one clear paved road with types and constrained APIs that make invalid states and routes unrepresentable.
• Mechanical Guardrails - Catch rule violations early with deterministic checks such as compilers, linters, and tests. These are fast and deterministic for the rules they can encode but they can't typically encode as much as other rulesets (languages like Rust can offer more out of the box than others)
• Judgement Guardrails - Use human or AI reviewers to interpret results and assess whether they match the intended outcome. Has high trigger determinism but lower certainty it will cover everything asked of it.
• Guidance Guardrails - Describe the system's intent and workflows through durable context, skills, and instructions. Has broad scope (literally anything you can write down) but iffy determinism.

Next

AI problems are often just human / organizational problems magnified. We've dealt with code quality issues before and the approaches are largely the same with AI.

Observe issues in your system - where developers (human or ai) make mistakes and ratchet up rules + guardrails to prevent them.

• A bug made it to prod? Write a test covering it. Better yet update the Durable Context to make the requirements + verification clear.
• Using an unsafe / deprecated API? Delete the API or write lint rules to prevent new usages while you rip it out. Make doing the right thing easy and the wrong thing hard.

As you improve the System Guardrails, quality will start to improve. And because quality improves it means less rework which tends to lead ot faster speeds overall.

See an issue? Improve the system to prevent it from happening again. That's basically all a software factory is doing - that and building new features on that solid foundation.

If you want to see the full AI dotfiles I use for agentic engineering, I snapshot them each month and make them available to HAMINIONS Members.

If you liked this post you might also like:

• System Guardrails for Software Factories - Building Pits of Success for Agents and Humans
• Durable Context, Disposable Code - Building Systems with Speed and Quality in the Agentic Era
• Context Architecture - Aligning Humans and Agents at Scale