Agent Instructions as Executable Constraints

A typical AGENTS.md reads like onboarding documentation. It tells the agent to "be careful," "test thoroughly," and "ask if unsure." Three days later the agent has shipped a change with no tests, written to a forbidden directory, and asked nobody anything, because it never knew where the line was.

Instructions work when they are operational and fail when they are aspirational. Write rules the workbench can interpret and a reviewer can score.

An executable constraint is a rule with a name, a category, and a check: something the workbench can run against an agent's work and score as pass or fail. Rules belong in docs/agent-rules.md, away from the short root router.

Five categories that cover most rules

A rule that fits none of these five usually wants to be two rules. Force the split.

Rules are machine-readable

Each rule has a slug, a category, a one-line description, a severity (block, warn, or info; see Production patterns below), and a check field that names a checker function. A real workbench would keep those functions in a module such as rule_checker.py; the demo keeps them in main.py. Adding a rule means adding a check, so the checker grows with the workbench.

Rules are diff-friendly

Rules live one per heading in a single markdown file, which makes renames visible in diffs. New rules go at the top of their category. Stale rules get deleted rather than commented out, because the workbench is the source of truth, not a chat log of how the team felt last quarter.

Rules versus framework guardrails

Framework guardrails (OpenAI Agents SDK guardrails, LangGraph interrupts) enforce rules at the runtime level. The rule set in this lesson is the human-readable, reviewable contract those guardrails implement. You need both: the runtime catches violations during a turn, and the rule set proves the runtime is doing the right thing.

Progressive disclosure: a map, not an encyclopedia

Progressive disclosure means layering instructions: a small root router the agent reads every session, and topic files it loads only when the task touches them.

AGENTS.md keeps growing because every incident adds a rule and no incident removes one. A year in, the file is two thousand lines, and the agent reads the first screen, runs out of attention budget, and acts on a fraction of what it was told. A giant instruction file fails the way a forty-page onboarding doc does: the reader skims it once and never returns to the part that mattered.

A shorter file is not the fix. A layered one is. The router stays small enough to read every session and holds nothing but pointers, while the depth lives in topic files. Give the agent a map, not the whole encyclopedia, and let it walk to the page it needs.

AGENTS.md                  # router, under ~50 lines: what this repo is, where to look, the 5 hard rules
docs/
  agent-rules.md           # the full rule set (this lesson)
  architecture.md          # loaded when the task touches module boundaries
  testing.md               # loaded when the task writes or runs tests
  deploy.md                # loaded only for release work, gated behind an approval rule
feature_list.json          # the backlog (Phase 14 · 36)

Two tests keep the layering honest. The reachability test: an agent should reach any rule in at most two hops from the router, so the router must link every topic doc by path instead of describing it in prose. The freshness test: the router is short enough that a reviewer rereads it on every PR, which is the only thing that stops it from silently growing back into the encyclopedia it replaced. A pointer that no longer resolves is a worse failure than a missing rule, so a broken link in the router is itself a startup-check violation.

code/main.py contains:

• An agent-rules.md parser that loads rules into a dataclass.
• Checker functions, one per check reference. They live in main.py here; a real workbench would move them into a module like rule_checker.py.
• Two demo agent runs: a bad trace that fails all five rules and a good trace that passes all five, each followed by a check pass.

Run it:

python3 code/main.py

It prints the parsed rule slugs and pass/fail per rule for the bad and the good trace (not the traces themselves), and saves a rule_report.json next to the script.

Three patterns separate a rule set that lasts a quarter from one that decays in a week.

Severity tagging at write time. Every rule carries a severity: block, warn, or info. The checker reports all three, but the runtime refuses only on block. Most teams overstate severity early, then quietly weaken it under deadline pressure. Tagging at write time forces that calibration up front. Pair it with the verification gate (Phase 14 · 38), which signs any override of a block rule into an overrides.jsonl audit log.

Rule expiry as a forcing function. Every rule carries an expires_at date (default 90 days from authoring). The checker warns when an unexpired rule has had zero violations for 60 consecutive days, and the next quarterly review either justifies keeping it, weakens it to info, or deletes it. Cloudflare's production AI Code Review data (April 2026, 131,246 review runs across 5,169 repos in 30 days) showed that rule sets with explicit expiry stayed under 30 rules per repo, while sets without grew to 80+ with most never firing.

Markdown as source, JSON as cache. agent-rules.md is the authored file. agent-rules.lock.json is a cache the checker reads in the hot path, regenerated by a pre-commit hook. Markdown diffs stay reviewable and JSON parsing stays out of every turn. It's the same shape as package.json / package-lock.json and Cargo.toml / Cargo.lock.

Three places this shows up in practice:

• Claude Code, Codex, and Cursor read the rules at session start and quote them when refusing actions. The checker re-runs them in CI to catch silent drift.
• OpenAI Agents SDK guardrails register the same checks as input and output guardrails. The markdown is the docs surface and the SDK is the runtime surface.
• LangGraph interrupts fire when an in-flight node violates a rule. The interrupt handler reads the rule, asks the human, and resumes.

The rule set carries across all three because it is just markdown plus function names.

outputs/skill-rule-set-builder.md is a skill that interviews a project owner, sorts their existing prose instructions into the five categories, and emits a versioned agent-rules.md plus a checker stub.

1. Add a sixth category if your product genuinely needs it. Defend why it does not collapse into one of the five.
2. Extend the checker so a rule can carry a severity (block, warn, info) and the report aggregates accordingly.
3. Wire the checker into CI and fail the build if a block-severity rule fails on the latest agent run.
4. Add an expires_at field per rule (default 90 days from authoring) and flag any rule past its date for review. Separately, have the checker warn when an unexpired rule has had zero violations for 60 consecutive days.
5. Find a real AGENTS.md and rewrite it as five-category rules. How many of its lines were operational? How many were aspirational?

• OpenAI Agents SDK guardrails
• LangGraph interrupts
• Anthropic, Building Effective Agents
• Rick Hightower, Agent RuleZ: A Deterministic Policy Engine: block/warn/info severity in production
• Cloudflare, Orchestrating AI Code Review at Scale: 131k review runs, rule composition lessons
• microservices.io, GenAI development platform part 1, guardrails: defense in depth between rules and CI
• Type-Checked Compliance: Deterministic Guardrails (arXiv 2604.01483): Lean 4 as the upper bound on rule-as-check
• logi-cmd/agent-guardrails: merge-gate implementation with scope checks, mutation testing, and violation budgets
• Phase 14 · 32: the minimal workbench this rule set drops into
• Phase 14 · 38: the verification gate that consumes the rule report
• Phase 14 · 39: the reviewer agent that scores rule compliance