loading…

Constraint Layering

Constraint Layering is the architectural practice of allocating software engineering rules, policies, and safeguards to the cheapest and most reliable layer of the agent runtime. The governing operational maxim is:

Prompt for judgment, script the mechanical, gate the consequential, and isolate the dangerous.

flowchart TD
    subgraph Layer 1: Prompt & Context
        P1[Skills & Procedures] --> J[High-Judgment Guidance]
        P2[AGENTS.md & CONTEXT.md] --> D[Domain Truth & Vocabulary]
    end
    subgraph Layer 2: Deterministic Tooling
        L1[Hooks & Linters] --> M[Mechanical Invariants]
        L2[Typecheckers & Compilers] --> T[Static Contracts]
    end
    subgraph Layer 3: System Boundaries
        S1[Protected CI / Oracles] --> G[Merge Gates & Acceptance]
        S2[Sandboxes & Egress Filters] --> I[Blast-Radius Containment]
    end

Layer Allocation Matrix

Layer	Best For	Typical Mechanism	Failure Mode if Misplaced
Skill (SKILL.md)	Judgment-heavy repeatable procedures	Workflow checkpoints, anti-rationalization tables	Over-reliance on prompts for mechanical checks (agent rationalizes skips)
AGENTS.md / CONTEXT.md	Concise, durable repository facts & ubiquitous language	Markdown reference files at repo root	Prompt bloat when packed with transient instructions
Scripts & Pre-commit Hooks	Cheap mechanical invariants	Linters (oxlint — see deterministic lint gates), formatting, import boundaries	Fragile regex hooks that block valid edits
CI / Protected Oracles	Merge-blocking contracts & regression safety	Read-only test suites, containerized builds	Slow feedback loops starving the inner agent loop
Sandbox / Policy Engine	Blast radius, authorization, and network isolation	Filesystem allowlists, ephemeral containers, disabled egress	Relying on prompt instructions to prevent secret leaks or file overwrites
Canary & Rollback	Runtime verification & production recovery	Telemetry metrics, automated rollbacks	Shipping directly to production based on local green tests

Why Prompt-Only Boundaries Fail

Language models are probabilistic reasoning engines that excel at rationalization. If a security or structural constraint is enforced solely via natural language prompts (e.g., “Do not edit files outside src/http”), models under edge-case pressure frequently rationalize breaking the rule to achieve the broader prompt goal. Hard operating boundaries (sandboxes, read-only mounts, and CI gates) convert probabilistic compliance into deterministic guarantees.

---

Related Concepts

• agent containment and blast radius — Restricting agent execution privileges.
• agent harness engineering — Harness architecture and layered runtime controls.
• progressive disclosure — Dynamic context loading based on execution phase.
• five debts of agentic engineering — Structural debts prevented by proper constraint layering.