Rules to stop AI coding agents from breaking working code

The article presents a methodology for controlling AI coding assistants by shifting from hope-based prompting to constraint-based rules. The author begins by diagnosing the problem: in the first two weeks, the model feels magical, but as the codebase grows beyond what the model can hold in context, it starts "fixing A while breaking B." This is not a skill problem, the author argues, but a structure problem—one that harder prompting cannot solve.

The immediate action is to create a CLAUDE.md file in the project root containing the project description, current state, a "Do not touch" section, and explicit rules. Claude Code reads this file automatically at the start of every conversation; Cursor uses .cursorrules and Codex/Copilot use AGENTS.md with the same content. The core rule is: "Do not modify files I did not ask you to modify." The author contrasts this with vague positive instructions: "Please write clean code does nothing. There's no threshold for clean, so no behavior changes. Prohibitions have a clear edge. They land immediately."

The article then offers five prompts to prevent breakage. The first—"Don't write code yet. First tell me which files you'd touch and where the risky parts are"—forces planning before execution, which kills most collateral damage. The second—"Before changing this, tell me what else is affected by it"—makes the model articulate dependencies, often surfacing couplings it would otherwise miss. The third—"Don't tell me it works. Write a test and show me it passes"—addresses a core weakness: models review code using the same assumptions they built it with, so wrong assumptions survive both passes. A passing test is evidence; "looks good" is an opinion. The fourth prompt, run before closing a session, asks for a summary of what is done, what is next, and what was tried and abandoned—the last item being critical, because without it a fresh session will confidently propose the exact approach that just failed. The fifth is simply the highest-value line in the rules file: "Do not modify files I did not ask you to modify."

The author also addresses context decay: long sessions get worse because abandoned directions and corrected mistakes accumulate in context, burying the signal in its own history. The solution is to start a fresh session every 3–5 tasks, running the summary prompt before closing. If the same request has to be made a third time, the author advises changing the window rather than rewording—"That session can no longer produce the answer."

On reversibility, the author recommends making everything that can be undone easy, and gating only irreversible actions. A reversibility rule is offered: reading, searching, analyzing, local edits (if state is saved), drafting, and running tests are all low-stakes and should be free. Deleting, deploying, and payments or orders are irreversible and should require confirmation. The author also suggests adding a kill switch—a STOP.txt file that halts all work immediately—so developers can safely leave autonomous work running.

Finally, the article emphasizes that rules imagined in advance are mostly useless; rules extracted from actual breakage are the ones that hold. Each time the model fails, that specific failure should be appended to the rules file. A "Known traps" section is offered as an example: stock deduction in order_service.py sits outside the transaction (known, leaving it); test_payment.py hits the live API (don't run casually); the event-driven approach was tried and dropped (do not propose it again). The author claims that doing this for a week will stop the mistakes from repeating.

The article closes by noting that adopting the entire framework at once is unnecessary—writing CLAUDE.md tonight will change tomorrow. The author also mentions a 25-page field manual available for purchase ("Working With Claude Code — Field Manual · $19 · PDF") that covers approval gates, hooks, kill switches, skills, cost control, and a symptom-to-cause-to-fix table, but emphasizes that the README above is the useful half for most people.

The article addresses a real problem: as AI coding assistants become more capable within a single conversation, they also become more dangerous at scale. The author's observation—that after the first two weeks of apparent magic, the model begins fixing problem A while breaking problem B—reflects the gap between single-task performance and multi-file coherence. The proposed solution does not try to train the model better or prompt it harder; instead, it treats this as a structural problem that requires constraints.

The rules framework is grounded in a specific insight: vague instructions fail because they have no enforcement boundary. "Please be careful" or "write clean code" are aspirational but behaviorally empty. Prohibitions—"do not modify files I did not ask you to modify"—are actionable because they have a clear edge. The same logic extends to the five prompts: each one shifts the burden of verification away from the model's self-review (which inherits its own assumptions) onto external evidence. Requiring a test to pass, or a plan to be stated before execution, creates a checkpoint that the model cannot rationalize around using the same flawed logic that created the bug.

The author also identifies context decay as a practical failure mode. Long sessions accumulate abandoned directions and corrected mistakes, which stay in the context window and corrupt the signal. The solution—starting fresh every 3–5 tasks with a summary of what was tried and abandoned—is a form of state reset that prevents the model from re-proposing failed approaches. Finally, the reversibility principle (saving state before running agents, gating only irreversible actions) is a risk-management insight: it frees the model to iterate in low-stakes areas while maintaining human control over high-stakes decisions like deployment.

No comments yet. Be the first to share your thoughts!