The Second Time Is a Bug

The first time an AI coding agent makes a mistake, it is the model’s. The second time, it is a bug in your harness.

You ask your coding agent for a change. It reports success, and the diff looks right. Then you find the one line that is wrong: a price rounded through a float, a test quietly loosened, a button that renders but cannot be seen. A week later, in a new session, the agent makes the same mistake, and you fix it by hand again.

In the Stack Overflow 2025 Developer Survey, the most common frustration with AI tools, named by 66% of respondents, was output that comes close but misses the mark. This book is about closing that gap for good, one mistake at a time.

What the book teaches

One method, applied chapter by chapter. When an agent makes a mistake:

• Log the incident and find the root cause in your harness, not in the model.
• Choose a control: a guide that steers the agent before it acts, or a sensor that checks its work afterwards.
• Choose where it runs: at edit time, at commit, in the build, at deploy, or against the live system.
• Prove it works by planting the mistake on purpose and watching the guard refuse it.
• Write down when you will delete it, because guards encode assumptions about models, and those assumptions expire.

The book is built from guards, not from tool features. A guard is a small, readable script with an exit code, so it works with whichever coding agent you use, with git hooks and with any CI system. The wiring for today’s tools sits in one dated appendix, so the rest of the book does not go stale when a settings file moves.

It is also measured. Chapter 12 reports 270 runs of three models on seven tasks, with and without a harness: where the harness made a difference, where it did not, and what it cost.

What is inside

• 14 chapters in six parts, 252 pages (6 x 9 inches) with 38 diagrams, as PDF and EPUB.
• 34 pattern cards. Each technique on one card with the same seven fields: symptom, drill, guard, proof, placement, kind of control, and when to retire it. The full cards come as a printable deck (A4 and US Letter, two cards per sheet) that you download as an extra with the book, and Appendix A in the book is a pattern card index, one line per card with its page.
• 26 runnable drills. Each drill replays one agent mistake (a deleted test, a float in money code, an rm -rf, a package that does not exist, a 900-line diff) in a scratch copy of the companion code and shows the guard catching it. The mistakes are recorded as patches and scripted turns, so every drill runs offline, with no API key and no model, and gives the same result every time.
• The companion code, free and public on GitHub (book-companion): Invoicer, a small invoicing app written for this book, a deliberately tangled legacy exporter, every guard, every drill, a toy agent loop of two dozen lines, an experiment kit for measuring whether your harness pays, and starter templates. TypeScript on Node.js, zero runtime dependencies, MIT licensed.
• Templates: an instruction file starter, an incident log, a plan and handoff file, a harness review checklist and hook examples, printed in Appendix B and included as files in the companion code.

Every chapter opens with a failure you can reproduce, shows the control that stops it, and is honest about what that control costs and where it falls short. Each one ends with a checklist you can apply to your own repository this week.

For one reader or a team

• The Book: the PDF, the EPUB and the printable card deck, for one reader.
• Team Edition (10 copies): ten copies for people at one organisation. After buying, you get ten download tokens and send each one to a colleague by email, so everyone has their own copy and card deck.

Who it is for

• Working engineers and tech leads who use a coding agent (Claude Code, Codex, Cursor, GitHub Copilot’s agent or similar) every day and lose time to output that is almost right.
• Solo builders shipping real products with an agent as their main pair.
• Anyone responsible for letting agents work in a shared codebase: tests, gates, permissions, dependencies, legacy code and unattended runs.

You need a terminal, Node.js 22.18 or later, git and some patience with small scripts.

Who it is not for

• Readers looking for an introduction to AI or to prompting. The book assumes you already use a coding agent.
• Readers who want a manual for one specific tool. The body is deliberately tool-agnostic.
• Anyone hoping for a productivity figure. The book does not promise a speed-up; it shows you how to measure your own loop.
• Builders of LLM applications. This is about engineering with agents, not building them.

Read a chapter first

Chapter 6, “Tests the Agent Cannot Game”, is free: download it from the book’s website, secondtimeisabug.com. It covers the seven ways an agent gets a green test run that proves nothing, and four guards that stop them: read-only tests, a test count ratchet, a mutation tester of about 100 lines and a hash-checked “done” file.

Sources

Every statistic and named incident in the book is cited to a published source, and the experiment in Chapter 12 is the author’s own.

Independent publication

This book is independent. It is not affiliated with, sponsored by or endorsed by Anthropic, OpenAI, Anysphere, GitHub, Microsoft, Google or any other AI vendor or tool maker. Product names are trademarks of their owners and are used only to identify those products.