Every bug becomes a rule

This is the fourth of five posts in the behind-the-scenes series about Olha o Bichim!. In the previous one, I showed how the spec becomes code. Now, the rules that guide the agents.

An AI agent has no memory from one session to the next. Every time I open Claude Code, it starts from scratch, like a new developer on their first day at work. So everything it needs to know about the project has to be written somewhere it reads every time, and that place is the CLAUDE.md files.

House rules

At first it was a single file, at the repository root. Over time it bloated and, in August, it was split by context: the root one holds the project, the stack, the build commands and the release checklist; the one in lib/ holds the Dart, database and sync rules; the one in lib/presentation/ holds the UI rules; and those in ios/ and android/, each platform's quirks. The agent loads the file for the folder it is working in, so it only reads what matters.

The AGENTS.md and GEMINI.md files just point to CLAUDE.md, so there is a single source of truth for any AI tool. And there is a meta-rule: never bloat the root file; a new rule goes in the right folder. Oh, and they are all written in English in "caveman" style, telegraphic sentences with no filler, which saves tokens and keeps each rule direct.

On top of that, there is an agent behavior protocol, loaded in every session, no exceptions. Its rules are: no code change without a skill; think before coding; simplicity first; surgical changes; define success criteria; a pure game engine built with TDD; parallel review; and verify after every implementer. The think-before, simplicity, surgical-changes and success-criteria rules came almost word for word from the guidelines derived from Andrej Karpathy's observations about LLMs' typical coding mistakes, packaged in the andrej-karpathy-skills plugin.

Every bug becomes a rule

What I find most beautiful in this process is that almost every rule in lib/, ios/ and android/ was born from a real bug. Some examples:

• The app froze forever on the splash screen, but only on iPhones 14 to 17 and only the day after playing. The cause? A WebP image attached to a local notification, which iOS rejects, throwing an exception before the app even starts. Rule: notification attachments on iOS must be JPEG, GIF or PNG.
• Apple rejected the app three times, under Guideline 2.1, because of the same "Confirm" button, which looked frozen. It waited for the server write before leaving the screen. Rule: a primary button never waits for the server before navigating.
• Tied players disappeared from the leaderboard podium, because position was indexed by rank, which repeats on ties. Rule: position comes from the ordering, never from rank.
• A confirmed purchase was never credited if the player left the shop mid-process. Rule: purchase delivery lives in a permanent listener, with a record that prevents delivering twice.

Basically, the CLAUDE.md files are the project's institutional memory. The next agent, or me six months from now, won't make the same mistake, because it is written down there. And the rules are treated as code: versioned, reviewed, refactored and pruned when they get in the way. For example, there was a rule forcing a specific model for subagents, and it was removed once it became clear the skill itself chose better.

Ponytail, the lazy senior

The other piece of the puzzle is a skill called Ponytail, by Dietrich Gebert, also open source. Its description is great: "You know him. Long ponytail. Oval glasses. Has been at the company longer than version control. You show him fifty lines; he looks, says nothing, and replaces them with one." And the motto: the best code is the code that was never written.

In practice, it gives the agent a ladder, and it stops at the first rung that fully solves the problem: does this need to exist? Does it already exist in the code? Does the standard library solve it? Does a native platform feature solve it? Does an already installed dependency solve it? Does it fit in one readable line? Only then, the minimum that works, with a test if there is logic.

The author's own example is very instructive: "add a date picker". Without the skill, the agent wrote 335 lines, a hand-made calendar. With the skill, 10 lines, reusing the project's text field with type="date", because the browser already ships the calendar.

But the part that matters most is what it never cuts: validation at trust boundaries, error handling that prevents data loss, security, accessibility, and anything the user asked for. And every answer ends by saying what was skipped or not verified and what the risk is. The code ends up small because it only has what is necessary, not because someone tried to save characters.

According to the author's benchmark, with Opus 5.5 on 39 tasks, there were 53% fewer lines, 41% less time and 26% lower cost, and risky logic delivered with a test rose from 68% to 98%. These are the author's own numbers, so take them as an indication, not an independent study, but they match what I saw day to day.

The law and the habit

The funny thing is that the repository's protocol already had practically the same ideas before I installed Ponytail.

"Does this need to exist?" is "simplicity first". "Keep the structure the code already has" is surgical changes. "Lazy code without verification is unfinished" is success criteria with TDD. "Find every caller and fix the root cause" is the systematic debugging rule.

So why have both? Because CLAUDE.md says what good development is in this project, and Ponytail gives the agent a procedure to get there. One is the law, the other is the habit. And they fit together with Superpowers like this: brainstorming decides what to build, Ponytail and the rules decide how much code to write for it, and the reviewers check that what was written is what the spec asked for, no more, no less.

In the last post of the series, I step away from the technical side a bit and talk about the product: listening to the players, kids included, the marathon with Apple, and why knowing what to remove is design too.