Start with Your Coding Agents

Sam Coope, writing on 19 October 2026 in the first part of a series on building agents with agents, argues that coding agents perform better when developers write high-level context and motivation into prompts and docs rather than piling up prescriptive instructions. Coope says the engineer's instinct of patching bad behavior with negative prompt instructions leads to "death by a thousand instructions," and that guardrails belong in the environment as permissions, sandboxes and checks, a view he says Anthropic's own prompting guidance has since adopted. Coope, who helps early-stage startups build agent systems from scratch, ends the post with starter docs he copies into every new repo.

Building agents with agents · part one Start with your coding agents Sam Coope · 19 October 2026 I’ve been building agents with agents for a few years now<sup 1 user-content-fn-about </sup . Lately I’ve been helping early-stage startups build their agent systems from scratch, and the same questions keep coming up. This series is my attempt to write down what I’ve learned. This first part is about coding agents, the ones most people already use: how I think about them, how I write for them, and what a codebase needs so they need less supervision. It ends with the starter docs I copy into every new repo. How I think about agents There are two broad ways to think about agents, and they lead to different ways of building. The first is the mentor’s. You try to understand the agent’s position, almost as you would a person’s: what it knows, what it is missing, what would help it do well. You give it as much freedom as the environment safely allows, and when something goes wrong, you ask how you could have supported it better. The second is the engineer’s. Predictability comes first. You build for specific use cases, and when something goes wrong, you treat it as a behaviour bug and ask how to fix it, usually with another line in the prompt. The engineer’s way is easier to start with, and it gets good results while the agent only has a few things to do. When I started working with agents, it was my instinct too: as a software engineer, I patched bad behaviour the way I’d patch code, with a small change to the prompt, usually a negative instruction. That works until the agent needs to handle a lot of things on its own. Then the instructions pile up, start to contradict each other, and the agent gets worse at everything they don’t cover. It is death by a thousand instructions, and it can look a lot like the model getting less intelligent. Anthropic’s own prompting guidance has since come round to much the same view<sup 2 user-content-fn-labs </sup , which is lovely to see. I’m firmly on the mentor’s side. That doesn’t mean having no rules. What an agent may touch, read or send still matters, but those guardrails hold up better built into the environment, as permissions, sandboxes and checks, than written into the agent’s instructions. That leaves the prompt and the docs free to do what they’re best at, which is explaining. Writing for agents Most of the work of building with agents is writing, and most of good writing for agents is empathy. The question I keep asking is whether the agent knows everything it needs to do this well, which is a different question from how to tell it exactly what to do. Agents tend to get very general tasks with a huge number of edge cases, and no list of instructions covers them all. Explaining things at a high level is the only way I’ve found to write all of that down in a form that stays manageable, and that the agent can apply to cases I never thought of. I think about what I write as a pyramid. Traditional software lives at the instructions layer, where every step is spelled out, because that is what code is. Agents do their best work from the top, so that is where I put most of the words: context on what this is and why it matters, then guidance on what tends to work. Instructions and examples aren’t off limits, but they are the exception. When an agent underperforms, the common move is to add more examples. In my experience, improving the high-level explanation usually does more. A few habits have made the most difference for me. Motivation and consequences. Agents do better when they understand why things are the way they are, and what happens when they act. “Other teams import this package, so changing a function’s signature breaks their builds until they upgrade” tells an agent far more than “don’t change public APIs”. It also tells the agent that internal functions are fair game, and why a breaking change needs a note for the people upgrading. Advice, with what has worked. “Short replies have gone down better with this client” lets an agent weigh the advice against everything else going on in its task. Saying what has worked, alongside the motivation, gets an agent to follow guidance without burying it in a thousand instructions. Watch for advice written as fact. Models have a habit of writing documentation as statements of fact. “Tests are kept few” reads like a description of the codebase, so an agent can’t tell whether it is a rule or an opinion, and the knowledge base turns rigid. “A few tests at the boundary have caught most of our bugs” gives the same advice in a form the agent can weigh. Holistic rewrites. Adding or changing one piece of information usually changes a good part of a well-written doc, because high-level prose hangs together. Rewriting the whole thing, as you would write it today, keeps it clear and readable. Patching it a line at a time slowly turns it into a list of instructions. What a codebase needs Agents are good at starting projects. They struggle more once a project has been going for a while, because every session starts with no memory of it. A lot of what they need has never lived in a codebase at all. Why the architecture is the way it is, which options were tried and dropped, how the team likes to work: that has always lived in the heads of the engineers. Agents don’t have that luxury, so it has to live in the repo<sup 3 user-content-fn-notes </sup . An overview, with the motivation. What we are building, who it is for, why, how the parts fit together, and where we are. Decisions, with the why. A short log of the choices that constrain later work, each with the date, what was chosen, why, and what it rules out. Without it, every new session reopens questions that were settled weeks ago. Ways of working, including taste. How a piece of work runs, and what good looks like when making high-level decisions. Taste is the hard part to write down, and it is where I spend the fewest words on purpose. You can lean on what an agent already knows: “write in the style of the GOV.UK style guide” brings a whole body of good practice in one line, and “when unsure about a new piece of front end, build something that would look native in a Stripe dashboard” does the same for UI. For code, I’ve used “complexity has to be earned”, with a line on what that means, and “keep things small, modular and composable”. When the agents fall short of what I want, the trick is to resist adding more. I go back to those few sentences and work out the phrase that captures what I actually meant, taking care not to squeeze it so far that the meaning goes. Fresh agents, started often. I use a lead agent, a foreman of sorts who splits the work into pieces and reports back to me. The lead starts a fresh agent for each piece, with a short brief, and for anything bigger than a small change, another fresh agent to review it with only the repo to go on. Short, high-level briefs have worked much better for me than long, prescriptive kickoff docs that repeat the same instructions every time. Starting agents fresh is also what keeps the docs honest. Over a session the lead can pick up a lot from me that isn’t written down anywhere, and a fresh builder or reviewer has none of it. When my final review catches something the reviewer missed, it usually points to a gap in the docs, and the fix goes there as well as into the code. A habit of improving the process. Each piece of work ends with a short note on what slowed it down and where the docs were wrong or missing. Those notes are how the docs get better. The aim is a repo where a fresh agent, with no context from me, can do good work and review it. The closer you get to that, the less you need to look over its shoulder. The starter docs https://gist.github.com/coopie/c9ca8c4563b2e1e8506a707a508084b8 The docs I start every repo with are in a gist. They are a small base, meant to stretch to different styles of work. Projects naturally add their own docs alongside them, such as a process for end-to-end testing, or the regulations the work has to follow. | File | What it holds | |---|---| | 1-writing.md | How to write docs, prompts and briefs for agents | | 2-AGENTS.md | The entry point every session reads first | | 3-ways-of-working.md | How a piece of work runs, for whoever does it | | 4-leading.md | How the lead sets, reviews and improves the work | They are written for starting from scratch, and every line is meant to be true the day you copy them in. Add a CLAUDE.md that points at AGENTS.md , and let the agents grow the rest, such as the overview and the decisions, as the project needs them. What’s next Next, I’m planning to walk through building harnesses for knowledge-work agents, then supervising the environment they run in, such as how to make sure agents don’t leak data. Along the way there’ll be some of the side projects a few friends and I have been working on. If you’d like the next post in your inbox, leave your email below. Footnotes 1. First at CodeWords https://codewords.ai , then at Jack & Jill https://jackandjill.ai . There’s more on the about page https://grokking.agency/about/sam . ↩ user-content-fnref-about 2. Anthropic’s prompting best practices https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices add-context-to-improve-performance suggest giving the motivation behind an instruction, and telling Claude what to do instead of what not to do. ↩ user-content-fnref-labs 3. I even keep meeting notes in the codebase now. It saves having them somewhere separate, like Notion or Granola. ↩ user-content-fnref-notes