Safe shipping with coding agents: a small operating system that works

#ai #productivity #devops #security

The hard part is not generating a patch

Coding agents are very good at producing a first draft. The expensive part starts after that: keeping the request in scope, proving what changed, and making the release decision legible to someone who did not write the patch.

A lightweight operating system for agent-assisted delivery can be surprisingly small. It needs a repository contract, a repeatable request loop, explicit human boundaries, and evidence at the end.

1. Turn a request into a contract

Before the agent edits anything, write down:

the outcome, not just the implementation
the files or systems that are in scope
the non-goals
the acceptance checks
the owner of the final decision

A short AGENTS.md can make this visible to every contributor:

# Delivery contract

## Before changing files
- Restate the outcome and non-goals.
- Inspect the repository and name the evidence you will use.
- Ask for approval before implementation if scope is unclear.

## Before release
- Summarize changed files and checks run.
- Record known gaps and rollback steps.
- Leave deployment and destructive actions to a human owner.

The file is not a magic prompt. It is a shared boundary.

2. Use a visible loop

A useful loop is:

Triage — clarify outcome, scope, risk, and acceptance.
Inspect — read the relevant code and existing checks.
Plan — propose the smallest coherent change.
Implement — make the change in a bounded slice.
Prove — run checks and capture evidence.
Review — ask what could break and what remains unknown.
Release — a human approves the final action.

This sequence gives speed a shape. It also makes it easier to stop when the request expands.

3. Make evidence part of the pull request

A PR should answer more than “what files changed?” A compact evidence section helps:

## Evidence
- Checks run: ...
- Result: pass / fail / not run
- Risk introduced: low / medium / high
- Rollback: ...
- Human decision needed: yes / no
- Known gap: ...

The goal is not ceremony. The goal is that a reviewer can make a good decision without replaying the entire session.

4. Keep high-impact actions human

Do not give an agent silent authority over:

secrets and private keys
production data
deployments
destructive commands
payments and financial transfers
messages sent outside the team

The agent can prepare a plan, a diff, a transaction draft, or a release note. A human should own the irreversible step.

5. Measure the workflow, not the model

Useful signals are practical:

time from request to first reviewable plan
percentage of PRs with evidence
rework caused by unclear scope
releases rolled back or delayed
human approvals that happened outside the documented path

These measures tell you where the operating system is weak. A faster model does not fix an invisible approval boundary.

A small kit for starting

I put these ideas into a dependency-free set of Markdown templates: a repository contract, issue and bug briefs, PR and release gates, five workflow prompts, security boundaries, a weekly checklist, and an offline board. There is a free preview and expanded team/studio editions here:

The templates are intentionally boring. Boring infrastructure is easier to review, adapt, and trust.

If you use coding agents in a real repository, the most valuable next step is usually not another prompt. It is writing down the boundary that the prompt cannot decide for you.