Practice · Agent guardrails
What guardrails should I put around autonomous coding agents?
Control what the agent may change, what it may execute and what evidence allows the result to proceed. Keep these controls outside the implementation agent’s discretion, and make exceptions explicit.
Protect the requirement before the agent tries to satisfy it.
Illustrative change: an agent is asked to speed up an importer. The approved requirement says malformed input must leave stored data unchanged. Deleting that check would make the task easier, but it would change the product promise. The agent should propose that trade-off for authorized review, not quietly remove the obligation.
| Boundary | Control | When to stop |
|---|---|---|
| Intent | Versioned requirements and authorized amendments. | The task conflicts with an existing promise. |
| Execution | Repository permissions, isolated runners, scoped credentials. | A tool requests an action outside its permitted scope. |
| Evidence | Required checks and inspectable current-revision results. | A check fails, is stale or does not establish the claim. |
| Acceptance | Saved approval policy and named authority. | A decision or exception exceeds delegated authority. |
| Delivery | Required repository checks and separate merge/deploy permissions. | The revision or provider prerequisites change. |
Follow one attempted shortcut through the controls
In the importer example, the agent proposes removing the rollback check to meet a speed target. The requirement still says malformed input must leave stored data unchanged. This is a proposed workflow, not a recorded blocked run.
| Attempt | Enforcing mechanism | Remaining limit |
|---|---|---|
| Edit the requirement to allow partial writes. | Protect the authoritative requirement and amendment policy with repository permissions and required review. | A prompt instruction alone cannot prevent an authorized writer from editing a file. |
| Delete the regression and report that the suite passed. | Require an independently controlled CI job to check required evidence and execute the preserved failure case. | A green status is insufficient if the candidate can also remove the check that produces it. |
| Merge despite the unresolved behavior. | Require the current-revision result and restrict bypass permission in the repository. | Proof output alone does not enforce the hosting provider’s merge rules. |
The next action is to keep the promise and fix the implementation, or request an authorized amendment with its consequences visible. Test the boundary with a deliberately failing candidate before giving the agent unattended access.
A CI job becomes a gate when the repository requires it.
Run the relevant Proof checks in your existing CI, retain their reports and make the job a required status check. Explicitly select the failure threshold so the job does not depend on a project override. Protect the policy and check configuration from being weakened by the same change.
proof audit --fail-level warn
proof audit --check acceptance_criteria_witnessed
proof review-pr --format comment
The audit default in the current CLI is warn; project.audit.fail_level may override it when the command has no explicit flag. With the shown threshold, warnings and errors return a nonzero exit. Use the full audit and applicable executions for readiness. The acceptance-criteria check evaluates recorded witnesses and their eligibility; it does not establish that their assertions cover every promised behavior. review-pr generates a deterministic brief of requirement edits and recorded impact, not a semantic code review or merge gate.
- Run against the exact proposed revision and relevant base.
- Require the named result from the intended CI integration in branch protection or repository rules. Propagate failures rather than continuing with a successful job.
- Restrict bypass and changes to the workflow or acceptance policy.
- Recheck after relevant head or base changes, using an up-to-date branch or merge queue as appropriate. Invalidate the decision when its relevant basis changes.
On GitHub, a skipped or neutral check can satisfy a required status check. Make the required job verify that all required evidence actually ran, and test the gate with a deliberate failure. See GitHub’s required-check behavior.
Choose delegation deliberately.
Proof records approval under the saved project policy. Current initialization permits agent approval at every assurance level. For higher-consequence work, configure the levels that require a person before relying on that workflow. See the current and recommended policy. Approval does not run the verification suite or grant merge authority.
Instructions in a repository file help the agent understand the task. They are useful context, but they do not replace runtime permissions or an enforced acceptance gate. Proof supplies the intent and evidence model; your agent runtime, repository and deployment system still enforce their own access boundaries.
Use workflow guidance to define the boundaries.
The US defense AI & Agentic Workflow Design and Governance play describes explicit task-level autonomy and review gates. It is marked GA, updated 15 March 2026, as checked on 2 October 2026. Apply it within the customer’s actual program and authority. Guidance is not an authorization to operate.
Start with a change you need to trust.
Bring one component, its build path and a change you are not comfortable delegating yet. We can identify the intended behavior, missing evidence and decisions together.