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

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:

1. Triage — clarify outcome, scope, risk, and acceptance.
2. Inspect — read the relevant code and existing checks.
3. Plan — propose the smallest coherent change.
4. Implement — make the change in a bounded slice.
5. Prove — run checks and capture evidence.
6. Review — ask what could break and what remains unknown.
7. 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:

• https://jadiface.gumroad.com/shipkit-ai-safer-shipping-with-coding-agents
• https://jadiface.gumroad.com/l/shipkit-ai

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.