Stop Arguing With Your Coding Agent

How to get working software without explaining yourself for the rest of the afternoon (or week).

Typical coding session with an agent:

1. Ask for a change.

2. Read the code.

3. Calmly explain what you meant, with several examples and bullet points.

4. Read the code.

5. Convince yourself the code probably won’t explode in production.

Sometimes the code exploded in production.

Then comes stage six: argue with the agent for hours (we’ve all seen the Kai Lentit video). Make 5K LOC of changes. Discover that the agent misunderstood a key detail that existed in your head. Explain that thing with increasing, uh, colorfulness. Give up and ship because life is too short. Feel drained.

By stage six+, I was doing most of the reasoning myself, and I noticed that what I wanted was not a magical software engineering machine. I wanted a magical software building machine.

The Magical Software Building Machine

We already know how to do this. It’s a fairly ordinary SDLC, made explicit enough that an agent doesn’t have to guess the important parts. Write down what good looks like, settle the product decisions and system choices that matter, then let one Builder build. Before believing it’s done, get a fresh reviewer to read the spec and actual diff, and have QA open the actual product and try it. Real failures go back to the same Builder. You still decide whether to ship.

That’s the small software factory. You can run the first version yourself with your coding agent, a folder, and four files: the spec, decisions, work log, and verification evidence. Get that sequence working before automating the handoffs.

Lovingly define the destination

Start by describing what great looks like. For instance, say we are building Fireship’s Horsetube, the next billion-dollar company in the making. For our first version, answer four questions:

• What can people do? Upload a short horse video with a title, browse the latest clips, and watch them.

• Who can do what? Anyone can watch. You need an account to upload or delete your own videos.

• What must stay true? Only the uploader can delete a clip. Public viewing doesn’t give other people permission to change it.

• What would convince me? Upload a clip, find it in the feed, and play it from beginning to end. Share its link and watch it in a signed-out browser. The title and video should match what was uploaded.

Add the design, non-goals, and QA plan. Our first version has no live streams, subscriptions, recommendations, or comments.

Then stop. Lock down the product meaning, important system boundaries, expensive choices, and how you will check the result. Let the Builder inspect the repository, follow precedent, and choose reversible implementation details. If you prescribe every function, you have delegated typing.

Give it a Playbook

Start with a folder in your repository: .loops/<task-name>/. Put the desired result, constraints, non-goals, and acceptance scenarios in spec.md. As the run progresses, use decisions.md for settled choices and invariants, log.md for what changed, checks run, and what remains, and verification.md for scenarios and evidence. Skills stay with your reusable project instructions, not inside each task folder.

Give the Builder that spec and your repository rules, and have it implement one bounded change. Then run your coding agent’s own code-review command or skill, if it has one. Prefer a fresh context with the spec and actual diff, not just the Builder’s summary. Send real blocking findings back to the same Builder, then review the repair.

Next, have QA exercise the running feature and record the results in verification.md. Start by kicking off these jobs yourself. You’re assembling a sequence of bounded jobs, not relying on one prompt to organize the whole thing. Automate the handoffs once the sequence works.

Good Night, Have Fun (GNHF) is a great place to start. It runs agents through small changes, with validation and notes carried between iterations. Try a bounded cleanup with clear checks and an iteration budget. You’ll learn whether your instructions describe a result the agent can recognize, and whether its checks tell you anything useful. Its Companion mode lets a supervising agent steer and review the work.

For builder discipline, Matt Pocock’s Skills for Real Engineers offers small, reusable skills you can adapt. The community-built Karpathy-inspired CLAUDE.md guidelines cover thinking first, simplicity, surgical changes, and verifiable goals. The Ponytail rule adds the lazy-senior approach: understand the problem, reuse what exists, fix the root cause, and write the minimum code that works. Yes, it is called Ponytail. The advice is still good.

Keep the important decisions and a short note of where work stopped. The next session should know what’s agreed, what’s built, what was checked, and what to do next. Otherwise you spend the next session reconstructing the task from chat history.

Check the output

A thousand green unit tests can coexist with a missing upload page, a broken Play button, or a video that never loads. Give a QA agent that didn’t build the change your requirements, design, test URL, accounts, and a clip it can upload. Let it create and delete test data there.

You can start with this assignment:

Make a short QA plan from these requirements, then use the actual product in the supplied test environment. Don’t change code. Report each check as PASS, FAIL, or NOT RUN, with steps, expected and actual results, and evidence such as screenshots or request responses. If the browser, accounts, test data, or environment aren’t available, mark the check NOT RUN and say why.

For Horsetube, QA should upload a real clip, refresh the feed, play it through, and open its link signed out. Then try deleting it as another user and as the uploader, checking the feed afterward. For visual work, compare the important screens and states with the supplied design.

Suppose the other user can delete the clip. Send the exact steps and evidence back to the same Builder. After repair, have a Reviewer inspect the changed code and QA rerun the failed scenario plus a nearby happy path, using a fresh clip: the other user is denied, the uploader can delete their own video, and it disappears from the feed.

If a requirement is unclear, settle it before the Builder tries again. I’ll go deeper into review, revisions, and QA in a later article.

Failure Modes

The agent built exactly the wrong thing

The dangerous result isn’t gibberish. It’s clean code implementing a plausible product you didn’t ask for. The tests are green because they follow the same mistaken understanding. The review is confident because it checks the architecture the agent chose. Everything agrees. Everything is wrong.

“Add sharing” leaves a fairly important question unanswered: can anyone with the link open the document, or only invited coworkers? Before coding, ask the Builder to restate what it’s building and list its assumptions. Correct the wrong ones in the spec. It can’t read your mind (yet).

Decide what should block the PR

Before review starts, give comments a shared meaning. P0 covers a violation of the agreed spec, design, or architecture, or a critical security or data problem. P1 covers a real correctness, maintenance, or operational problem worth fixing in this change. P2 is optional advice, not a reason to keep rebuilding.

“Pragmatic” needs some judgment. A failed save reported as successful is a real problem. Fix it. Rewriting a simple CRUD feature as five services because traffic might grow someday is not the same thing. And “it’s just an MVP” isn’t a good reason to let users read each other’s private records.

Ask what breaks, when, why it matters, and whether the proposed fix fits the problem. Resolve every agreed blocker; challenge unsupported ones. If fixing it requires changing the product or architecture, bring that decision back to the human. Optional nits don’t prolong the loop.

Repeated failure needs a limit, too. After a few unsuccessful repairs, stop patching and have someone question the approach. If there’s no better explanation or useful next experiment, ask the human.

Isn’t this slow and expensive?

Yes, it can be. More agents mean more context to read, more coordination, and more time spent checking. You don’t need the full process for every change.

Choose the small loop for a reproducible bug or a clear improvement: a brief plan, one Builder, independent review, and relevant QA. If product or architecture decisions are still open, settle those first with a spec and design. Don’t choose by counting files.

Try lower-cost models such as GPT-5.6 Luna or DeepSeek-V4.1-Flash for mechanical edits, gathering information, and narrow assessments. Give them a bounded question or change, with a capable lead checking their work and integrating the result. The expensive judgment is deciding whether the whole thing makes sense. You don’t need your strongest model collecting filenames, and the cheapest answer isn’t a saving if someone has to redo the work.

Parallelism helps when jobs have clear boundaries and someone owns integration. Separate worktrees can keep concurrent edits apart; shared changes still need coordination. Four agents pointed at a fuzzy goal produce four simultaneous misunderstandings.

Once you’re maintaining these handoffs, preserving decisions across sessions, and recovering interrupted runs, your experiment has become infrastructure. That’s where the reusable version starts earning its keep.

Conclusion

Pick one small change you already understand. Write its end state and run it through one Builder, an independent Reviewer, and a QA agent. Allow at most one repair cycle before you inspect the result yourself. Note where you intervened before trying something bigger.

After rebuilding harnesses in my beloved Cursor and debugging dying Python orchestration scripts, I wanted a version I could keep using. I love designing systems and building things, but I don’t have the time these days to hand-code everything while also being personally offended by bad code. A real dichotomy.

Forge is open source, MIT-licensed, and still in beta. It packages this workflow as skills, role instructions, and a small CLI for the coding agent you already use. The Forge website has the walkthrough and getting-started docs. If you want a hosted version, there’s Bright. Try it and tell me what breaks.

This is the first article in a series about agent engineering and building a real staff of agents. I’ll cover memory, self-learning agents, knowledge bases, durable agent turns, orchestration, and more. For each layer, I’ll build the small version from first principles, then show where the operational burden begins.