Fighting AI Code Rot: A Practical Approach with Specs, Outcome Notes, and File Manifests

A developer spent eight months building a desktop application almost entirely through coding agents — first Claude Code, then Codex. The project has now accumulated roughly 650 commits and 43,000 lines of JavaScript. He personally reviewed and approved every change, but the code was written almost entirely by agents.

The workflow he shared on Reddit is worth paying attention to — not because the agents wrote bad code. Quite the opposite: the code quality was solid. What actually broke down was continuity. This problem surfaced as the project grew, and it looked nothing like what most people would expect.

What Actually Breaks in Agent-Based Development

As the codebase expanded, several failure patterns repeated themselves:

• Fresh sessions would confidently re-propose solutions that had been tried and rejected weeks earlier;
• A so-called "small fix" would quietly touch five files, two of which had nothing to do with the task;
• Rule files contained the correct conventions, but agents ignored them at exactly the moments those rules were supposed to apply;
• When running two agents in parallel, they would stomp on each other's edits.

What these failures have in common: none of them are "coding ability" problems. They're "memory and discipline" problems. Agents have no reliable cross-session memory, and no internal mechanism for honoring conventions.

Shifting Attention from the End to the Beginning

The core shift the author describes is moving review weight from the end of work to the beginning. No substantial task starts without a brief spec. That spec contains three things: what the problem is, what the constraints are, and what "done" means.

The division of labor matters: the agent can draft the spec, but the author personally rewrites the scope and acceptance criteria. His reasoning is pointed — "criteria written before work begins are used to judge the result; criteria written after work begins just describe the result." This cuts right through a common form of self-deception: acceptance criteria written after the fact always pass.

After the spec comes a plan. The plan has one hard requirement: it must verify each of its assertions against the actual code, not against the agent's memory of the code. The plan records the chosen approach, rejected alternatives and their reasoning, and a manifest of files expected to be touched.

Outcome Notes: Bridging the Gap Between Intent and Result

The real work is broken into small tasks, each producing a commit that "a colleague could review independently." The most valuable habit in the entire workflow, the author argues, is having the agent write two or three sentences after each task: what was shipped, where it deviated from the plan, and what remains undone.

His insight: the plan describes intent, the code describes the result, but neither explains the gap between them — and that's exactly where the suspicious changes hide. So when reviewing, he reads the outcome notes first, then compares the diff against the file manifest in the plan. Any change touching files outside the manifest either gets an explanation or gets rolled back.

Managing Stale Historical Decisions

The most time-consuming part to get right was history. Git tells you what changed, never why — and no agent reads git log before editing a file.

His solution: every past spec is indexed by the files it touched. When an agent is about to edit a file, a hook surfaces the relevant historical decisions, labeled by status — current, stale (because the file changed again since), or in progress elsewhere. One file in his project accumulated 26 entries from 19 separate specs.

The "stale" label turned out to matter more than he expected. In his words: "A decision that was correct in July and wrong in September is more dangerous than no record at all, because it reads like authority." This holds for any team maintaining a long-running project — outdated "best practices" are often more destructive than a blank slate.

---

Git worktree is a built-in Git feature that allows the same repository to have multiple working directories checked out simultaneously on the filesystem, each corresponding to an independent branch. Compared to cloning the repository multiple times, worktrees share the same .git object database (saving disk space) while keeping branches fully isolated from each other. This property is especially important when running multiple AI agents in parallel: if two agents share the same working directory, they'll simultaneously modify the same files, causing conflicts or silent overwrites. By assigning each agent its own worktree and branch, file-level race conditions are eliminated at the root — each agent can only "see" and operate on its own branch's copy of the files, and merge conflicts are deferred to the human review stage rather than erupting randomly during generation.

Parallel Work and What Didn't Work

For parallel work, the author's rules are concise:

• Every agent gets its own git worktree and branch;
• Specs with overlapping file manifests are never run simultaneously;
• Nothing enters the main branch without his approval.

He also honestly lists what didn't work for him — equally useful as a reference:

• A single massive context file;
• Feeding the complete session history into the next session;
• Letting the agent decide its own task scope;
• Trusting tests written in the same session as the code — because they may share the same flawed assumptions.

That last point deserves attention: tests generated from the same source are poor independent correctness checks. It's an easy-to-miss trap in AI-assisted development.

---

The "same-source tests" trap is a systemic risk in AI-assisted development that hasn't yet been widely discussed. When test code and the code under test are generated consecutively in the same session by the same agent, both may share the same incorrect premises — the agent's misunderstanding of an edge case will manifest simultaneously in the implementation and the test, causing the test to "pass" while the logic remains wrong. This is essentially automated confirmation bias: the agent uses its own understanding to validate its own understanding. Traditional software engineering counters this through test-first development (TDD) or having different people write the tests — the underlying assumption being that tester and implementer have independent mental models. Reproducing this independence in an AI coding pipeline requires deliberate isolation: generating tests in a separate session, using a dedicated testing agent, or locking down test cases before writing the implementation, rather than allowing the agent to generate both within the same context.

The Biggest Lesson: Instructions Are Advice, Mechanisms Survive

That hook also taught the author the most important lesson in the entire system. His rule file instructed agents to consult a module index before searching code. But when he reviewed his session logs, he found that out of 937 searches, agents followed the instruction only 18 times.

The instruction wasn't wrong — it just never arrived at the right moment. Once he converted that same rule into a hook that automatically triggered on search, it actually worked. From this, he distilled a principle worth posting on the wall:

"Instructions are advice, and mechanisms are what survive a long session."

This is a wake-up call for everyone using rule files (like CLAUDE.md or rules files) to constrain agents: rules written into a prompt are closer to "prayers." Only when converted into mechanisms that forcibly trigger at the right moment do they become reliable.

---

Hooks here refer to Git Hooks or, more broadly, "event-triggered scripts" — programs that execute automatically when specific actions occur. Git natively supports hooks like pre-commit, post-commit, and pre-push, letting developers insert custom logic at these points. In AI coding workflows, "hooks" are extended into a wider class of automatic interception mechanisms: when an agent is about to perform a certain type of action (like searching code or editing a specific file), the system automatically injects relevant context or constraints into its input stream — without relying on the agent actively "remembering" to look things up. The essential difference from CLAUDE.md or rules files: rule files depend on the agent reading them at the start of a task and retaining them throughout the session, while hooks forcibly intervene at the moment of action, requiring no form of memory persistence. The data point of only 18 compliances out of 937 opportunities reveals the fundamental fragility of pure instruction-reliance: attention distribution across the context window and the "forgetting" that accumulates as sessions grow longer both cause rule files to gradually lose their grip.

An Open Question for the Community

The author closes with a question: when an old constraint no longer holds, how does your workflow prompt the agent to revisit it rather than treating it as a permanent rule?

This touches on a deep challenge in AI programming — how to give agent systems historical memory without letting them be held hostage by outdated history. His "stale labels + triggered hooks" approach is one answer, but there's clearly much more to explore. For any developer using agents to maintain a long-running codebase, this system built around specs, outcome notes, and file manifests offers a practical starting point.