Skip to content

Agent-Assisted Coding Principles

Overview

We use tools like Claude Code to move faster and take the pain out of mundane, repetitive work. They're improving quickly and finding new uses all the time, so we don't hem them in with rigid rules — that would only leave velocity on the table. But an agent is there to amplify your judgement, not replace it. We stay accountable for everything we ship, which means never outsourcing our understanding of the code to a third party.

When to use agent-assisted coding

Low-risk, well-bounded work where it's easy to tell whether the result is correct. Agents do their best work when the problem is clear and the surrounding code already shows what "good" looks like.

  • Research — exploring an unfamiliar library, API, or corner of the codebase.
  • Prototyping — throwaway spikes to test an idea before you commit to it.
  • Wide but shallow refactors — renames, restructuring, simple migrations; many files, little logical risk.
  • Internal tooling — scripts and utilities where the blast radius is small.
  • Well-tested scope — changes inside a comprehensive test suite, so regressions announce themselves.
  • Existing patterns — following a convention already established elsewhere.
  • Boilerplate — repetitive, low-judgement scaffolding.

When to avoid agent-assisted coding

High-judgement work that sets precedent or is hard to walk back. An agent can inform these — it shouldn't make them.

  • New patterns — the first instance becomes the template everyone copies; it deserves deliberate design.
  • Infrastructure decisions — wide operational and cost impact.
  • Core refactors — the critical paths and abstractions everything else leans on.
  • Defining test cases — deciding what to test is a question of intent, and intent is ours to own.

Best practices

It all comes back to doing the thinking up front. If you can't articulate the problem, you can't expect the agent to understand it — or judge what it gives back.

  • Load the project's context. Make sure CLAUDE.md and AGENTS.md are read in so the agent works to our conventions.
  • Explore before you build. Let the agent search and explain the relevant code first, so its changes fit what's already there.
  • Plan before you generate. Use plan mode to agree the approach — cheaper to redirect a plan than a diff.
  • Explain the goal, not just the task. Give the business outcome, how it needs to scale, and what to optimise for.
  • Seed the shape. Sketching the models, contracts, or interfaces yourself gives the agent guardrails toward clean code.
  • Keep sessions small. Break large tasks into focused sessions with just the context they need — sharper context, better output.
  • Be specific about tests. Hand it the edge cases and paths that matter, so tests verify real behaviour not a coverage number.
  • Mind your tokens. Tools like Caveman trim token usage without dropping detail. This also helps against context rot as you remove noise from the window.

Reviewing agent-generated code

Generated code earns the same scrutiny as anything a person wrote. If you authored it, review it as thoroughly as a teammate's before putting it in front of anyone else — you're accountable either way.

As a reviewer, you're free to say — without judgement — that a change was too complex to be a good fit for generation, and is better reworked by hand or restarted. Pay extra attention to:

  • Abstraction complexity — unnecessary layers or over-engineering.
  • Unfamiliar patterns — approaches that don't match how we do things.
  • Tests that cheat for coverage — assertions that pass without exercising the behaviour they claim to.

Testing requirements

Prove behaviour end-to-end; don't trust static checks alone.

  • Unit tests alone are a weak net for generated code — the interesting failures live in the seams between components.
  • Where you can, get the agent to run the project and exercise it for real, not just check it compiles.

Limitations & anti-patterns

Working well with these tools means knowing how they fail.

  • Silent hallucination. Starved of context, agents invent plausible-looking code and won't flag it.
  • Context rot. Output degrades as the window fills — clear context and start fresh more often than feels necessary.
  • Deferred effort. Generating before you understand doesn't save work; it moves it downstream, usually costing more than it saved.