There is a genre of blog post — dozens of them now — with a title like How to Build a Coding Agent and a payoff that lands in a few hundred lines. Thorsten Ball's widely-copied version is the cleanest: an LLM with tool-calling, a loop that feeds tool results back into the conversation, and four tools — read a file, list files, edit a file, run a shell command. People have ported it to Go, TypeScript, Python, and JavaScript. It genuinely works. You can point it at a repo and watch it fix a bug.
And that is the trap. Because the loop — the thing every tutorial teaches — is the one part of a coding agent that is completely solved. It's a weekend. Every framework hands it to you. Once it runs, no amount of loop-polishing moves the needle. So the interesting question isn't how do I build a coding agent; it's why is my weekend agent so much worse than Claude Code when they share the same loop and the same model?
The answer is that everything separating a toy from a real coding agent lives outside the loop, in three places nobody puts in the title.
1. The edit tool is a product decision, not plumbing#
Your agent has to express a change somehow. It can rewrite the whole file, emit a search-and-replace block, or produce a unified diff. This feels like an implementation detail. It is not.
Aider — which has measured this more rigorously than anyone — found that the edit format changes two things at once: how often the edit applies cleanly, and how good the code the model writes actually is. Same model, different edit contract, different score. Whole-file rewriting is the easiest format for a model to produce correctly, but it burns tokens and caps how large a file you can touch. Diff formats are far more efficient and let you edit big files — but a weaker model will botch the format and strand its own work. Aider's Polyglot benchmark exists precisely because it scores the model inside the real edit loop, across 225 exercises in six languages, rather than pretending the format is free.
The edit format is not plumbing. It sets the floor on both your apply-success rate and your code quality — and you own that decision, not the framework.
The corollary: your agent needs a plan for when the edit doesn't apply. Fuzzy matching, a retry with the surrounding context re-shown, a fallback to whole-file. Most weekend agents just crash or, worse, silently corrupt the file. That failure-handling is the hard part, and it's the same discipline that separates robust agents everywhere — see tool-call error handling for the general shape. (It's also why code agents that emit executable code sidestep some edit-format pain and inherit different failure modes instead.)
2. What you keep out of context beats what you put in#
The second gap is context, and the instinct is exactly backwards. People tune the wording of their system prompt for hours while stuffing the entire directory tree, ten tool schemas, and a 9,000-token instruction manual into every single turn.
The minimalist harness Pi is the counter-example worth studying. A 2026 comparison of coding harnesses clocked Pi shipping a system prompt under 1,000 tokens, where mainstream harnesses carry 7,000–10,000. It pulls this off with "lazy skills": every capability keeps a one-line description in context, and the full instructions load only when the skill is actually invoked. The model isn't smarter; its working memory is just less polluted.
This is the lesson that doesn't fit in a quickstart. A coding agent's context window is a scarce, actively-managed resource — the whole discipline of context engineering — and the move is subtraction — retrieve the two files that matter instead of grepping thirty into the prompt, summarize the last twenty turns instead of replaying them, and keep tool schemas terse. What you leave out determines whether the model can still think on turn forty.
3. If it doesn't run the tests, it isn't an engineer#
The third gap is the one that most cleanly separates a demo from a tool: the verification loop. A coding agent that writes a change and stops is a code generator with extra ceremony. The agents that win — OpenHands, Claude Code — close the loop: they execute, read the traceback, and try again. The retry against real test output is where correctness actually comes from, because the model gets to be wrong cheaply and recover.
Anthropic's own guidance in Building Effective Agents points the same direction: the value isn't in elaborate orchestration, it's in giving the model a clear tool surface and a feedback signal, then keeping the design simple. A tight loop around real test output beats a baroque multi-agent graph around none.
So here is the honest version of the tutorial. The loop: a weekend, and then never think about it again. The four tools: a day. The edit contract, the context discipline, and the test-running feedback loop: the actual product, ongoing, and yours to build — because no framework builds them for you. Ship the weekend agent first. It's real, and it will teach you, within an hour, exactly which of these three you got wrong.
