What a Guardrail Actually Is
A guardrail is a constraint that shapes or blocks what an agent may do. That is the whole definition, and it is worth holding onto, because the word gets stretched to cover very different things. A guardrail can be a hard wall the agent cannot cross — a sandbox that refuses a network call. It can be a soft instruction the agent is asked to follow — a line in a rule file. It can be a check that runs after the agent proposes a change and either passes it or sends it back.
The distinction that matters is not how strict a guardrail sounds. It is where it sits relative to the code the agent writes, and what it can see when it makes its decision. A guardrail that only sees the running process cannot reason about your service boundaries. A guardrail that only sees a paragraph of prose cannot deterministically block an unapproved dependency. Sorting guardrails by what they can see is the fastest way to tell which risks each one covers and which it leaves open.
The Taxonomy: Five Layers of Guardrail
Most stacks running AI coding agents end up with some mix of five layers. They stack; they do not substitute. Here is each one, what it catches, and what it misses.
1. Runtime Guardrails
What it is. Controls on what the agent process can do while it runs: a sandbox, a tool allow-list, resource and rate limits, network egress rules, filters on inputs and outputs. Open-source toolkits such as NVIDIA NeMo Guardrails formalize this layer, adding programmable input, output, dialog, retrieval, and execution rails around an LLM application so tool calls and responses pass through checks before they take effect.
What it catches. Dangerous actions in the moment: a shell command that would wipe a directory, a call to an endpoint the agent should never touch, a prompt-injection attempt, a runaway loop burning tokens. This is the layer that stops an agent doing something destructive or unsafe right now.
What it misses. Everything about whether the code is architecturally correct. A runtime guardrail sees system calls and API traffic; it does not know that your billing logic is supposed to live behind one service, or that the repo standardized on one HTTP client. Perfectly safe code at runtime can still violate every architectural decision the team made. Runtime verification is not architectural verification.
2. Prompt and Rule-File Guardrails
What it is. Instructions given to the model in language: the system prompt, a CLAUDE.md or .cursorrules file, project rule files loaded into context. “Use our logging library.” “Do not add new dependencies without approval.” “Follow the existing error-handling pattern.”
What it catches. Broad tendencies. A well-written rule file nudges the model toward the house style and away from obvious mistakes, most of the time. For small, well-scoped work it raises the hit rate noticeably.
What it misses. Anything the model does not attend to. Rule files are an always-on prompt prefix, and a prompt is a suggestion, not a control. They compete for the same token budget as the task, they have no precedence when two rules conflict, and they do not scale as the ruleset grows past what the model reliably weighs. Section 3 covers this in detail.
3. Policy Guardrails
What it is. Organization-level policy engines: rules about data handling, licenses, secrets, compliance scopes, which model tiers may touch which repositories. Often enforced in CI or a platform layer, expressed as policy-as-code.
What it catches. Cross-cutting organizational rules. A secret committed to a repo, a GPL dependency in a proprietary product, PII flowing to an unapproved destination. These rules are broad and apply across every project.
What it misses. Project-specific architecture. Policy engines are built for uniform, org-wide constraints, not for the decision that this service owns the ledger and that one must call it through an API. The architectural intent of a single codebase is too specific and too local for a policy layer to carry.
4. Architectural Guardrails
What it is. The recorded architectural decisions of a specific system — ADRs, service boundaries, approved patterns — turned into checks that run at edit time, before a change lands. This is executable architectural intent: the decision is stored as structured data with its constraints, retrieved for the change in front of the agent, and checked deterministically.
What it catches. Drift from the system’s own decisions. An agent reaching around a service boundary, adding a second HTTP client, putting business logic in a layer that is supposed to stay thin, introducing a dependency the ADRs ruled out. The specific violations that runtime, prompt, and policy layers all miss.
What it misses. It is not a safety sandbox and not an org policy engine. It will not stop a destructive shell command or catch a committed secret. It governs one thing well — conformance to the architecture — which is exactly the thing nothing else in the stack governs.
5. Engineering-Standards Guardrails
What it is. The team’s conventions and approved technology: naming rules, module layout, the sanctioned frameworks and libraries, the error-handling and logging patterns. Close relatives of architectural guardrails, and enforced the same way — as checks, not prose.
What it catches. Consistency erosion. Code that works but does not look like the rest of the codebase: a new logging approach, an off-pattern name, an unapproved library doing a job an approved one already does.
What it misses. Deeper structural decisions live one layer up, in the architectural guardrails. Standards keep the surface consistent; they assume the boundaries are already being enforced.
| Layer | Catches | Misses |
|---|---|---|
| Runtime | Destructive actions, unsafe tool calls, prompt injection, resource abuse | Whether the code respects any architectural decision |
| Prompt / rule-file | Broad tendencies toward house style | Anything the model does not attend to; no precedence or scale |
| Policy | Org-wide rules: secrets, licenses, data handling | Project-specific architecture and boundaries |
| Architectural | Drift from a system’s own recorded decisions and boundaries | Runtime safety and org policy (not its job) |
| Engineering-standards | Convention and approved-technology consistency | Deeper structural decisions one layer up |
Read the table top to bottom and the gap is visible. Four of the five layers are strong on safety, organization-wide policy, and surface consistency. Exactly one governs whether generated code obeys the architecture of the specific system it is being written into — and that is the layer most stacks are missing. The sections that follow explain why the other common answers do not fill it.
Why Prompts and Rule Files Are Not Enough
Rule files are the most common first guardrail, and the most over-trusted. A CLAUDE.md at the repo root feels like governance: the rules are written down, the agent reads them, the code should follow. In practice a rule file is an always-on prompt prefix, and three properties of that prefix keep it from holding.
Token budget. Every rule competes with the task for the model’s attention. A short file works; a file that has grown to cover every hard-won decision the team ever made stops being reliably weighed. The rules do not get enforced less because they are wrong — they get enforced less because there are too many of them to hold in context at once.
Precedence. When two instructions conflict, a prompt has no defined winner. “Prefer composition” and “match the surrounding code” can point opposite ways on the same edit, and nothing decides which one governs. A check has an explicit verdict. A paragraph does not.
Scope. A rule file is global to the session, but architectural decisions are local to parts of the system. “This boundary is sealed” applies to three modules and is irrelevant to the rest, and prose has no clean way to say so. The result is a document that is either too broad to be precise or too long to be read. Rule files, retrieval, and memory each solve a different problem, and none of them is enforcement.
Why RAG Is Not Enough
The next instinct is retrieval: put the ADRs and standards in a vector store, retrieve the relevant ones for each change, feed them to the agent. This is strictly better than a static rule file — the agent now sees the decisions that actually apply to the edit in front of it. But retrieval solves the seeing problem, not the obeying problem.
Retrieving a decision and placing it in context does not enforce it. The agent still gets to weigh the retrieved text against everything else in its prompt and decide what to do. Retrieval can also miss: embedding similarity is fuzzy, and the one ADR that forbids this exact change may not surface for this exact phrasing. Even when it does surface, a retrieved constraint is still a suggestion. Retrieving context is not the same as enforcing it. RAG improves the input to a decision the agent still makes freely; a guardrail removes the freedom to land a violating change.
Why Memory Is Not Enough
Shared memory across agents and sessions is a real advance — it gives continuity, so an agent is not rediscovering the codebase from scratch every run. Teams reach for it as a governance answer: if all the agents share memory, surely they will share the architecture. They will not.
Continuity is not constraint. Memory tells an agent what was decided; it does not stop the agent from doing something else. An agent can have perfect recall of “billing goes through the billing service” and still write a direct database read, because remembering a decision and being blocked from violating it are different mechanisms. Shared memory is not shared intent. Memory is a better input to the agent’s reasoning. It is not a check on the agent’s output, and only a check can reject a change.
Why Review Is Not Enough
Review is the guardrail most teams trust most, and it works — for human-paced output. A reviewer reads the diff, spots the boundary violation, sends it back. The problem is not that review misses things. It is two structural facts about review.
Review is detection after the fact. By the time a reviewer sees the change, it exists, it has been written into a branch, and reversing it costs more than never landing it would have. The violating pattern may already have been copied by the next agent that read the surrounding code. Review is detection, not governance: it finds problems, it does not prevent them.
Review does not scale with agent output. When agents generate changes faster than people can read them, review becomes the slow step, and the honest failure mode is not rejection — it is approval-by-fatigue. A reviewer who cannot keep pace with the volume waves things through. Human review cannot scale with AI output. The architectural checks that can keep pace are the ones that run automatically at edit time and never get tired.
How Architectural Guardrails Actually Work
An architectural guardrail is not a smarter prompt or a bigger memory. It is a check that runs on the proposed change and returns a verdict. The loop is deliberately boring, and boring is the point:
- Record each architectural decision as structured data with its constraints — the boundary, the approved technology, the forbidden pattern — not a paragraph in a wiki.
- Retrieve the decisions relevant to the current change, whichever agent or model produced it.
- Check the proposed edit against them deterministically — same change, same verdict, every time, independent of the model.
- Reject violations before the change lands, not at review time, returning the exact decision that was broken.
- Return the named violation so the agent can retry compliantly instead of guessing what the rule was.
The worked example makes the difference concrete. An agent is adding a feature and, to save a call, writes a direct read against the billing database — bypassing the billing service’s API boundary. Walk it through the five layers. The runtime guardrail sees a normal database query and allows it; nothing unsafe happened. The rule file may say “go through the billing service,” but that line was one of forty and the model did not weigh it. Policy checks for secrets and licenses and finds none. Review might catch it, if the reviewer is fresh and reading carefully and not forty diffs deep. The architectural guardrail retrieves the recorded boundary decision, matches the direct read against it, and rejects the change before it lands — with a verdict that names the violated ADR: billing data must be accessed through the billing service API. The agent gets the specific rule back and retries through the API.
That verdict is deterministic and it carries its reason. Because the check depends on the recorded decision and not on which model ran, it holds when you swap models or add agents — the property that makes it model-independent governance. And because the verdict names the decision it enforced, every block is traceable to an intent someone recorded on purpose, which is what enforcement provenance means. A guardrail that can tell you which decision it enforced and why is a different kind of object from a prompt that hoped the model would comply.
One more control matters in practice: warn versus block. Not every decision should hard-fail a change. A mature setup blocks on the sealed boundaries and the rules that must never bend, and warns on the softer conventions — surfacing the concern without stopping the work. The verdict is still deterministic; the team chooses the severity per decision.
Choosing the Right Guardrail for the Risk
The five layers are not competitors. A serious stack runs all of them, because each covers a risk the others cannot see. The mistake is not picking one — it is assuming the ones you already have cover a risk they were never built for.
Match the layer to the failure you are actually worried about. Afraid of a destructive action or a prompt injection? That is runtime. Worried about a committed secret or a license violation? That is policy. Want the model to lean toward the house style? A rule file helps at the margin. But if the risk is that a correctly running, safe, policy-clean change quietly violates the architecture your team spent months deciding — the direct database read, the crossed boundary, the second HTTP client — none of those layers is built to catch it. That risk needs a guardrail that sees the architecture and enforces it at edit time. That is the layer to add when the others are already in place and the code is still drifting. See where it fits in a real stack in governance layers for AI coding assistants, or walk through the use cases where architectural guardrails earn their place.