How we actually use AI to build software: what's in the Handbook's AI-Augmented Development page

Not long after we relaunched the Handbook with a faster, more searchable design, we added a section that answered a question we get asked constantly by candidates and clients alike: how do you actually use AI to write code?

Not "do you use AI?" because we've been public about that for a while now. The question is how. So we wrote it down as its own page, AI-Augmented Development, and it's been sitting there for a few months now, quietly answering that question for anyone who reads that far into our very own company Handbook. We never got around to writing about it here, which in hindsight is a bit backwards for a company that talks about AI as much as we do, but to be fair and square, we’re frigging busy lately. So, better late than never.

Research, Plan, Implement

The core of the page is a framework called RPI (Research, Plan, Implement), widely used in agentic development out there, which has existed for a while now.

• Research: understand the problem, the codebase, the dependencies, before a single line of code gets written. This phase ends with a written account of what exists, what's missing, and what's likely to go wrong.
  
• Plan: use Claude Code's plan mode to turn that research into a step-by-step plan, with specific files named and specific trade-offs flagged for a human to decide on.
  
• Implement: execute the plan, in chunks small enough to fit a context window, flagging any deviation from what was agreed.

A bad step in a plan produces hundreds of wrong lines, and that's the whole reason the framework exists. Catching a bad assumption during planning costs you a few extra prompts, iterating until you get it right. Catching it during implementation costs you an afternoon of debugging code that looks plausible but does the wrong thing.

There are three points in that loop where a human actually has to look at the output: after research (did we understand the right problem?), after planning (is this approach sound?), and after implementation (does what came out match what we asked for?). For simpler tasks, some of those are optional, so there’s definitely elbow room for adapting to your actual needs, like in all good frameworks.

CLAUDE.md is doing more work than people expect

Every one of our repositories carries a CLAUDE.md file: build commands, conventions, architecture decisions, the workflows that would otherwise live only in one person's head. We also lean on a .claude/rules/ directory for anything that only applies to a specific file type or directory, rather than cramming everything into one file that nobody reads end to end.

The instruction that keeps coming up in our own reviews of these files is that they work best when they're concise, specific, and verifiable. Vague guidance like "write clean code!!!" or "make no mistakes" does nothing. A rule that says exactly which command to run and what a passing result looks like gets followed.

Context is a resource, too

This is the part that surprised us most once we started paying attention to it: how a session's context gets managed matters almost as much as what you ask for. The page covers the basics we now consider default hygiene:

• Starting fresh with /clear when the task actually changes, instead of dragging unrelated history along.
  
• Using /rewind to go back to a known-good point rather than asking the model to talk itself out of a mistake it already made. The latter creates even more context pollution and leads to disastrous results faster.
  
• Compacting long sessions before they degrade.
  
• Pushing noisy, self-contained work into subagents so the main thread stays legible.

Even if all of this sounds exotic to some of you, it did sound exotic to us too a year or two ago, to be entirely honest. It's the kind of thing that's obvious in hindsight and invisible until someone loses an afternoon to a context window full of dead ends. We all are learning the ropes of AI-augmented development and will continue to do so in this ever-changing landscape.

Skills, subagents, and knowing when not to bother

We have also documented where skills and subagents fit. Skills are reusable workflows we invoke on demand (to review PRs, to optimise a SQL query, etc.). Subagents are closer to independent instances of Claude Code, and they earn their keep on work that's well defined with a clear deliverable, not on anything where we're still figuring out what we're actually asking for.

That last part is worth saying plainly: spinning up a subagent for an ambiguous task usually just means debugging two things instead of one.

Guardrails that don't rely on anyone remembering them

The last section covers hooks, and this is the one we're proudest of, honestly. Shell scripts in .claude/hooks/ enforce a few hard rules automatically instead of relying on a developer to remember them under deadline pressure. Pre-read hooks block access to .env* files, .netrc, and directories like .ssh, .aws, .gnupg, .kube, and .docker. Post-write hooks run Prettier or ESLint without anyone having to ask.

The pattern behind all of it: anything that should never happen shouldn't depend on a human noticing in time.

Why bother writing any of this down

We could have kept this as tribal knowledge, and for a while, that's more or less what it was. Every Martian picked up the RPI habit from whoever onboarded them, with small variations depending on who was doing the explaining. Writing it into the Handbook wasn't really about external visibility, even though we're glad candidates and clients can now read it too. It was about noticing we'd converged on something real and worth making explicit, before it drifted any further.

Whether this is the final shape of how we'll be building software a year from now, we honestly don't know - and, quite possibly, won’t know. AI tooling is still moving fast enough that we expect to be back here revising this page sooner than we revised the rest of the Handbook. For now, though, this is what we actually do.