How to put coding agents to work safely

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.

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.

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.

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.

Adoption path

Start with one task and close the loop#

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.

Repository checklist

Before granting more autonomy#

• ✓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.