---
title: "Constraint Layering"
section: "concepts"
type: "concept"
created: "2026-08-27"
updated: "2026-08-27"
tags: ["agentic-patterns", "harness-engineering", "security"]
canonical: "https://pyweb.dev/wiki/constraint-layering"
---
# 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.*

```mermaid
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](/wiki/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](/wiki/agent-containment-and-blast-radius) — Restricting agent execution privileges.
- [agent harness engineering](/wiki/agent-harness-engineering) — Harness architecture and layered runtime controls.
- [progressive disclosure](/wiki/progressive-disclosure) — Dynamic context loading based on execution phase.
- [five debts of agentic engineering](/wiki/five-debts-of-agentic-engineering) — Structural debts prevented by proper constraint layering.

---

## Agent Navigation

cluster: person (170 pages) | betweenness: 116.9

### References (outbound)
- [Deterministic Lint Gates](https://pyweb.dev/wiki/deterministic-lint-gates.md)
- [Agent Containment and Blast Radius](https://pyweb.dev/wiki/agent-containment-and-blast-radius.md)
- [Agent Harness Engineering](https://pyweb.dev/wiki/agent-harness-engineering.md)
- [Progressive Disclosure](https://pyweb.dev/wiki/progressive-disclosure.md)
- [Five Debts of Agentic Engineering](https://pyweb.dev/wiki/five-debts-of-agentic-engineering.md)

### Referenced by (inbound)
- [Agentic Code Quality](https://pyweb.dev/wiki/agentic-code-quality.md)
- [Agentic Vulnerability Lifecycle](https://pyweb.dev/wiki/agentic-vulnerability-lifecycle.md)
- [Deterministic Lint Gates](https://pyweb.dev/wiki/deterministic-lint-gates.md)
- [Five Debts of Agentic Engineering](https://pyweb.dev/wiki/five-debts-of-agentic-engineering.md)
- [Christoph Nakazawa](https://pyweb.dev/wiki/christoph-nakazawa.md)

### Evidence (verified primary sources)
- [agentic-engineering-systems-evidence-report-2026](https://pyweb.dev/wiki/raw/articles/agentic-engineering-systems-evidence-report-2026.md) | origin: local:/opt/data/cache/documents/doc_7d5c60122087_agentic-engineering-report.md | ingested: 2026-08-27 | sha256: a02a8dda475212f9204bfd621ee63b7b285e0ba722cbf8536e8328fe77d9dfc8
- [addy-osmani-agent-skills-2026](https://pyweb.dev/wiki/raw/articles/addy-osmani-agent-skills-2026.md) | origin: https://addyosmani.com/blog/agent-skills/ | ingested: 2026-08-27 | sha256: 8b3508b787f042786af718b0044ee01b0e16c202905d36e09a5403b16c80b54e
- [anthropic-agent-skills-2025](https://pyweb.dev/wiki/raw/articles/anthropic-agent-skills-2025.md) | origin: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills | ingested: 2026-08-27 | sha256: a327a81032aecf7e3f3a569b591008364c27a40e3bcac2dc486f7a23ff74e747

### Machine endpoints
- Knowledge graph: https://pyweb.dev/api/graph.json
- Graph analysis: https://pyweb.dev/api/graph-analysis.json
- Context index: https://pyweb.dev/llms.txt