Designing policies that scale

One agent with one policy is easy. The trouble starts around agent twenty, when copies of copied policies drift apart, nobody remembers why the invoicing agent may call the deploy tool, and your quarterly access review takes a week. This guide collects the patterns from workspaces that run hundreds of agents with policy sets a human can still read.

Principle 1 — Layer policies, don't clone them

The single biggest predictor of policy health is whether teams compose or copy. govern.sh evaluates policies in layers: a workspace baseline, a team layer, and a per-agent layer, with the most restrictive verdict winning. Put the rules everyone must obey — no production database writes, no payments above the org cap, mandatory holds on new payees — in the baseline exactly once. Agent-level policy should read like a job description, not a legal document.

# workspace baseline — applies to every agent, cannot be widened below
version: 3
defaults:
  effect: deny
rules:
  - action: "db:prod.*.write"
    effect: deny            # no agent writes prod directly, ever
  - action: "payments:*"
    when: { amount_over: 5000_00 }
    effect: hold
    approvers: ["role:finance-lead"]

---
# team layer: support — narrows scope for all support agents
extends: workspace
rules:
  - action: "zendesk:*"
    effect: allow
  - action: "stripe:refund.create"
    effect: allow
    max_amount: 200_00

Principle 2 — Scope verbs, not tools

Granting stripe:* because the agent needs refunds is the policy equivalent of a god-mode key. Every rule should name a verb, and read verbs should be granted separately from writes. A useful review exercise: for each allow rule, ask what the worst action inside its pattern is. If the answer surprises you, the pattern is too wide.

• Prefer explicit verb lists over wildcards; reserve wildcards for read-only namespaces.
• Split read and write grants even within one tool — most agents need ten reads for every write.
• Name rules with an owner and a reason field. Twelve months later, 'why does this rule exist' becomes a lookup, not an archaeology dig.

Principle 3 — Budgets are a hierarchy

Per-agent budgets stop one agent from going rogue; they don't stop forty well-behaved agents from collectively spending 40x what you intended. Set budgets at every layer: a per-action cap, a per-agent daily cap, a team monthly cap. The enforcement point checks all of them on each spend, and runway alerts fire when any layer projects to exhaust before its window resets — so you hear about drift days before a hard stop.

budgets:
  team:support:
    monthly: 50_000_00      # $50k across the whole support fleet
    alert_at: [0.5, 0.8, 0.95]
  agent:refund-agent:
    daily: 2_000_00
    per_action: 200_00

Principle 4 — Keep holds rare, or they rot

Approval fatigue is a security failure mode: when a queue fills with routine holds, humans approve by reflex and the control becomes decoration. Healthy workspaces hold 1 to 3 percent of actions. If yours holds more, don't add approvers — raise thresholds on the action classes with near-100% approval rates and reinvest the attention where rejections actually happen. The approvals dashboard shows approval rate per rule precisely so you can find rules that no longer earn their interruption.

Principle 5 — Treat policy like code, because it is

Policies are versioned and every receipt records the version that judged it — which means policy changes are auditable, diffable, and revertible. Use that. Keep policy definitions in your repo and apply them through CI. Require review on baseline changes the way you would on a schema migration. And before widening anything, run the proposed policy in shadow mode: the engine evaluates the new version alongside the live one and reports where verdicts would differ, on real traffic, with zero enforcement risk.

$ govern policy shadow --file support-v4.yaml --window 24h
Shadow evaluation vs live (v3), 18,204 decisions:
  same verdict     17,988  (98.8%)
  would allow         201  (currently deny)   review below
  would hold           15  (currently allow)
No decisions would move from hold/deny to allow above $500.

A policy set that scales is one your newest teammate can read top to bottom and your risk team can review in an afternoon. Layer the invariants once, scope every verb, cap spend at each level, hold only what deserves a human, and ship changes through the same discipline as code. The fleet can grow tenfold without the policy file doing the same.