How to put coding agents to work safely

Why this matters

The agent finished the task and damaged the repository#

A coding agent makes the requested change, then “cleans up” a generated file, runs a broad command with excessive permission and declares success after a narrow test. The patch is plausible, yet it violates repository conventions and leaves the next maintainer with a failure that the workflow cannot explain or reverse.

Safe adoption begins by making the repository capable of containing that failure. Instructions, scoped permissions, deterministic checks, independent review and recoverable branches matter before autonomy or throughput; they turn a capable model into a participant in an accountable engineering process.

Containing that failure starts with repository instructions that change observable agent behavior.

Layer 1 · Contract

Write what changes agent behavior#

An AGENTS.md file should tell the agent how to build, test, review and finish work in this repository. It complements the human README; it should not repeat a product story or every convention the code already makes obvious.

Keep mutable priorities elsewhere. A short, command-first contract is easier to audit and less likely to conflict with the current release state. Include boundaries and when not to use a profile.

# Repository contract

## Allowed
- Read the repository and run documented checks.
- Edit only files required by the assigned task.
- Use the existing generator for derived pages.

## Stop conditions
- A command would expose secrets or private content.
- A required product decision is missing.
- The release gate returns HOLD or ROLLBACK.

## Definition of done
- Generated files are fresh.
- Tests and security checks pass.
- An independent reviewer verifies the diff.

Repeated instructions can then become narrow capabilities instead of being rediscovered in every task.

Layer 2 · Capabilities

Turn repeated work into narrow reusable skills#

A useful skill owns one workflow: migration review, citation validation, release preflight or accessibility audit. Its description should make routing clear, and its output should have a verifiable contract.

Do not create a skill for every prompt. Promote a workflow only after the team repeats it and knows which evidence distinguishes done from plausible.

Reusable capability improves execution, but a fresh reviewer must still inspect the actual change.

Layer 3 · Independent review

Review the diff from a fresh context#

The authoring agent has context and commitment to its own choices. A reviewer should receive the task, project rules and diff, then search for evidence that the change fails its contract.

Separate review from repair. Findings need severity, location and consequence; the author can then fix them and ask the reviewer to revalidate only the affected gates.

Review finds contextual mistakes; executable guardrails stop non-negotiable violations earlier.

Layer 4 · Guardrails

Use code for controls the model must not negotiate#

Permissions limit which tools and paths are available. Hooks can run deterministic checks before risky operations or before the agent declares completion. CI remains the shared gate after the session ends.

Instructions are policy; executable checks are enforcement. Neither is sufficient alone: a hook without context blocks blindly, while prose without enforcement can be ignored or misread.

With instructions, capabilities, review, and controls in place, the team can run one bounded pilot.

Adoption path

Start with one task and close the loop#

Apply the sequence to one repeated task in a repository the team already understands. Keep the branch recoverable.

1. 01

   Recognize

   Pick a repeated task in a repository the team knows.

2. 02

   Contract

   Add commands, boundaries and definition of done.

3. 03

   Execute

   Let the agent inspect, change and run checks on a branch.

4. 04

   Review

   Use an independent diff review and repair findings.

5. 05

   Learn

   Turn confirmed failure into a rule, test, or reusable skill.

The pilot produces the evidence needed to answer a checklist before granting more autonomy.

Repository checklist

Before granting more autonomy#

A “no” identifies the next repository capability to build. It is not a reason to hide the gap behind a broader prompt.

• ✓Build and test commands work locally.
• ✓Secrets and sensitive paths are outside the agent’s scope.
• ✓The task has a small, reviewable definition of done.
• ✓AGENTS.md is concise and current.
• ✓Dangerous tools require permission or are denied.
• ✓Deterministic checks run before completion.
• ✓A fresh reviewer inspects the diff.
• ✓The branch and rollback path are recoverable.
• ✓Failures become durable tests or instructions.
• ✓The team can explain when manual work is better.

Autonomy can expand only when the repository can detect, explain, and reverse the same class of failure introduced at the start.

Conclusion

Expand autonomy only after the repository can contain failure#

The useful question is not how much code an agent can generate. It is whether the repository can tell the agent what matters, limit what it may change, detect a broken result, obtain an independent review, and recover without losing work or exposing secrets.

Pilot one repeated, bounded task on a recoverable branch. Write the contract, constrain permissions, run deterministic checks, review from fresh context, and turn the first confirmed failure into a durable test or instruction. Grant more autonomy only when this loop becomes easier to explain—not merely faster to run.