ai-agent-guardrails

AI Agent Guardrails

LLMs make confident wrong decisions at scale. The cost of one wrong decision used to be one wrong commit; the cost of one wrong decision by an agent loop can be 30 wrong commits, 100 deleted DB rows, or a whole production site refactored into nonsense in 90 seconds.

This skill is a design checklist — not a runtime tool. It tells you what to put in place before giving an agent write access to anything that matters.

When to invoke

• Designing a new agent, scheduled job, or autonomous workflow
• Granting an existing LLM access to a higher-tier credential or new tool
• After an agent did something unintended (start here; do not just tighten one prompt)
• Reviewing a third-party agent (e.g. an MCP that takes broad actions) before connecting it

The core idea — blast radius

Classify every action an agent can take by what happens if it fires when it should not have.

Tier	Example	Reversible?	Required guard
1	Read a local file, run a query	Trivially	None
2	Modify a single local file, write to a sandbox	Yes, with backup	Backup before action
3	Mutate a staging service or shared dev resource	Recoverable in minutes	Dry-run mode + explicit confirm
4	Production-data write, customer-visible change	Recoverable in hours, with effort	Approval gate + audit log + rollback plan
5	Send mail, spend money, modify DNS, deploy, push to main	Sometimes irreversible, externally visible	Out-of-band approval + rate limit + kill switch

Every tool an agent can call belongs to exactly one tier. If you cannot say which, classify up.

Pattern: dry-run-first

For tier ≥ 3, every write tool should support an explicit dry-run that produces the exact diff/plan that would be applied. The agent runs dry-run first by default; only after the operator approves the plan does it run the real action.

Implementation sketch:

type WriteToolResult =
  | { mode: "dryrun"; plan: ChangeSet; estimate: ImpactEstimate }
  | { mode: "apply"; applied: ChangeSet; receipt: string };

async function update_widget(args: Args, opts: { dryrun: boolean }) {
  const plan = computePlan(args);
  if (opts.dryrun) return { mode: "dryrun", plan, estimate: estimateImpact(plan) };
  const receipt = await applyPlan(plan);
  return { mode: "apply", applied: plan, receipt };
}