Principles for working with coding agents

The principles in this section are the tool-independent rules for building software with AI agents: keep the agent read-only until a plan is accepted, define “done” as a failing test, feed each error back as the next specification, ship batches small enough for CI to prove, and keep human judgment at four gates instead of in every diff.

This hub is for developers who run agents every day and tech leads who set the team’s defaults. The situation it answers: the agent hands you 1,200 green lines across 18 files, and the only options feel like “read all of it” or “trust it”. Flags and models change every release; these rules do not, and each one removes a reason to read the whole diff.

Which principle fixes the problem in front of you?

Symptom you recognise	Principle	Page
The agent edited code while you were only asking a question	Stay read-only until a plan is accepted	Agent vs ask mode
The result “looks right” but nothing says what correct means	Write the failing test first	Test-driven development
Fix attempts go in circles on the same failure	Treat each error as the next specification, with a bounded loop	Error-driven development
Pull requests are too big to review or split	One task per commit, a size budget CI enforces	Continuous delivery
Review is the bottleneck, or approvals are rubber stamps	Human judgment at four gates: intent, spec, evidence, and risk class	Human in the loop
Forty agent PRs a week and two reviewers	Earn autonomy loop by loop, capped by a trusted oracle	Software factories
The agent keeps choosing things you would never ship	Constrain, give an example, plan before executing	Prompting techniques

The files these principles produce (intent.md, spec.md, plan.md) are defined once, in the artifact chain.

Apply the principles to your next agent task

1. Start read-only and ask for a plan that names the files, the order of work and the tests that prove it.

   Claude Code

   Start with claude --permission-mode plan, or type /plan in a running session.

   Codex

   Type /plan in the Codex terminal UI before you describe the change.

   Cursor

   Switch the agent to Plan Mode before you describe the change.

   The remaining steps are the same in Claude Code, Codex, and Cursor.

2. Accept the plan, then have the agent write the tests first and show them failing for the right reason.

3. Give the agent one check command, for example npm run typecheck && npm run lint && npm test, and require its output before it reports done.

4. Commit after each task in the plan, and stop the session when the diff reaches the team’s size budget.

5. Open the pull request with the evidence attached, and set the risk class that decides whether a person reads code.

Copy-paste prompt: open a task under the principles

Stay read-only until I approve a plan. First, write a plan that lists
the files you will change, the order of work, and the tests that prove
each step. After I approve it: write the tests first and show me they
fail for the reason the plan predicts; then implement one step at a time,
run `npm run typecheck && npm run lint && npm test` after each step, and
commit each passing step separately. If the same check fails three times
in a row, stop and report the error instead of editing tests or config.

Copy-paste prompt: audit which principles the repository enforces

Audit this repository for how it constrains coding agents. For each rule
below, report the file, hook or CI job that enforces it, or "not enforced":
1. Agents plan before they edit (instructions file, permission settings).
2. New behaviour arrives with a test that failed first.
3. One check command exists and runs in CI.
4. Pull request size is limited by a CI check.
5. Changes to auth, payments, schema or migrations route to a named
   reviewer (CODEOWNERS, branch protection).
Use only what exists in the repository and git history. End with the one
unenforced rule whose fix is smallest, and propose that fix as a diff.

How do you prove the principles are being followed?

A principle that only lives in a wiki does not change what the agent does. Each one earns trust when a machine checks it and a named person owns the exception:

• Tests first: CI shows the new test failing on the base commit and passing on the branch; protecting the oracle stops the agent from editing the tests it is graded by.
• Small batches: a CI job fails any pull request above the size budget.
• Evidence over reading: every agent pull request carries the manifest from the evidence bundle: spec delta, acceptance results, check output, and risk class.
• Human sign-off: the tech lead accepts the spec; a named reviewer merges; code reading is kept for the escalation classes in reading evidence instead of code.

What goes wrong when teams adopt these principles?

• The principles stay prose. The agent never reads your wiki. Recovery: put the rules in CLAUDE.md, AGENTS.md, or Cursor rules, and back each with a hook or CI check.
• The agent passes by weakening tests. A red build turns green because an assertion vanished. Recovery: once you approve the failing tests, deny the agent writes to those test files, require CODEOWNERS approval on them, and run the decisive check in CI from the base branch’s copy of the tests. In Claude Code the lock is a permissions.deny rule or a PreToolUse hook, and a CODEOWNERS entry applies to every tool; protecting the oracle has the per-tool lock for Codex and Cursor. The TDD page’s test-weakening patterns list what to look for.
• Autonomy is declared, not earned. A team switches every repository to unattended runs at once. Recovery: raise autonomy one loop at a time, only where the oracle is strong, as software factories describes.
• Gates become rubber stamps. Approvals arrive in seconds. Recovery: each gate checks a named piece of evidence, and helping the team stop reading every diff covers the staged hand-over.

Principle pages, one per rule

Software factories Meter autonomy loop by loop instead of declaring it factory-wide.

Human in the loop Four gates for human judgment; code reading for escalation classes.

Test-driven development A failing test as the target the agent cannot fudge.

Error-driven development A bounded error-fix-rerun loop and proof that it converged.

Continuous delivery One task per commit, a PR size budget, flags between deploy and release.

Agent vs ask mode When to stay read-only, when to grant writes, when to run unattended.

Prompting techniques Constraints, examples, and plan-then-execute prompts that steer the agent.

Where to go next with the principles

New to the method? Start with the method overview. To see the principles as one process, read the AI-native lifecycle. To place your team’s current practice, use one map. For a third-party loop built on the same ideas, see compound engineering.