Orbit

How I keep a big codebase from rotting while agents work on it

Chris Rupp

Does this sound familiar at all? Bug A would appear… the agent would say let’s fix it with B! B then caused a new bug…lets fix it with C! C then rebroke A in a new way…you get the idea. Next thing you know, the whole alphabet is stacked onto the original bug, all fighting each other.

The core of Orbit is about 850,000 lines of code, about 99% of it written by AI, so you can imagine this started happening a LOT. The agents would always take the shortest, easiest way out and would constantly repeat the same steps a previous agent had done a week earlier, and we were caught in a loop. What finally broke it was looking back over past attempts in my logs and seeing… oh, we already tried three different times to fix this the same way. Instead, we need to RIP OUT all of these extra layers and simplify.

That moment kind of changed how I work with agents on anything big, so I started writing down rules for myself and for them… and these are the six that have held up so far. I’m definitely still figuring this out, but if you’ve got a project that’s gotten big enough that no single chat can hold the whole thing in its head anymore, maybe some of these save you a few of the loops I got stuck in.

The rules

1. Look for work that already exists before you fix anything

Before an agent writes a single line to fix something, have it check whether that problem has already been worked on… the project’s history of save points (your Git commits), any side copies of the project where work is still sitting unfinished (Git calls those branches), and whatever log you keep of past prompts. If somebody already started a fix and never finished it, thats existing work, and the job is to finish or replace it, not write a second one next to it.

This is the one that would have saved me the most pain. An agent shows up fresh every time with no memory of last week, so it has no idea the same fix is already half done somewhere else, and it happily writes another one… and now you have two fixes for the same thing, quietly fighting with each other. If youre running a bunch of projects at once, you know that “wait, where did I leave this” feeling, and the agents have it way worse than we do cuz they dont even know there was a “this” to leave. So I make them look first, every time, and it’s honestly the single biggest change I’ve made.

2. Delete as much as you add

Every time an agent wants to add something new to fix a problem, like a new check, a new timer, a new cleanup job that runs in the background, it has to say what that new thing replaces. If it cant name something to take out, that’s my call to make, not something the agent just assumes is fine.

This comes straight out of the opener. The agents’ favorite move is to stack one more layer on top, cuz adding is always the quickest way to make an error go away right now… and then I’d tear the layers out and a few weeks later they’d be stacked right back up. In my case I had a background job whose whole purpose was to clean up stuck sessions, and it ended up killing sessions that were still working just fine. The fix wasn’t a smarter cleanup job on top of the first one, it was taking it out. I’m still doing this teardown over and over, so I wont pretend this rule is solved, but at least now it’s a rule.

3. When something breaks, find out what changed first

If something used to work and now it doesnt, something changed, and the first job is to find exactly which save point (commit) touched that part of the code since it last worked… before anyone proposes a fix. And the first suspects are always the most recent changes, including the ones I queued up myself that same night.

If you cant point at the change that broke it, you dont actually know what youre fixing, you’re guessing, and the agent will happily guess with you. It’s tempting to blame the old messy code, but most of the time the culprit is something from the last day or two. Your agent can do this digging for you if you ask it to “find the commit that changed this since it last worked,” and Git keeps every save point so the answer is in there somewhere.

4. Dont let an agent just pick a number

When something is slow or getting stuck, the easiest “fix” for an agent is to add a timer… like “if this takes longer than 30 seconds, give up and try again.” It makes the error go away, so it feels fixed, but nobody actually checked how long the thing normally takes. The agent just picked a number that sounded reasonable.

I had a few of these. The 45 minute one went in for a real reason… if a prompt got stuck it would just run forever and youd never know, so an agent added a rule that killed any session that ran past 45 minutes. Problem solved, right? Except now good jobs that were still doing real work were getting cut off right in the middle. Fixing one problem caused another, and the number itself was never based on how long a real job takes. The 5 second one didnt even have a reason like that… as far as I can tell an agent just decided 5 seconds sounded reasonable for things to start up, which was so tight that normal startups were failing and the “fix” was causing the very problem it was supposed to catch. So now if an agent puts a number in a fix, I ask where it came from, and if the answer is basically “it seemed about right,” it doesnt go in until we measure how long things actually take.

5. Fix the cause, not the complaint

Trace the symptom back to whatever is actually causing it and fix that, instead of patching the thing you can see.

The best example I’ve got is my dashboard freezing up. It felt like a dozen different bugs, it froze here, it froze there, it locked up when I clicked this… and it turned out to be one root cause, too much heavy work happening in the same place that draws the screen. The complaint was “it freezes.” The cause was one thing. If I’d let the agents patch each freeze one at a time, which is exactly what they wanted to do, I’d have ended up with another pile of layers from rule 2.

6. Don’t let an agent grade its own homework

An agent saying “done” just means it thinks it’s finished. So for me something only counts as shipped when the save point is actually in the main version of the project (not just sitting on the agent’s machine or a side branch), and when someone other than the agent that wrote it has seen it working for real. Until then it’s “the code is in, nobody has checked it yet,” and the handoff has to say which one it is.

Basically, “done” means somebody actually saw it work. The agent that wrote the fix should say exactly what would prove it worked, like a specific line showing up in the logs, and then somebody else goes and looks. Half done stays half done too… if part of the job is missing, it doesnt get rounded up to finished just cuz most of it landed.

Where I keep these

Rules only help if the agents actually see them, and that’s the part I built into Orbit, the AI orchestration program I’ve been building since back in March. My rules live in the project’s own rule files (ORBIT.md alongside the usual AGENTS.md and CLAUDE.md), and Orbit keeps those files in sync so every agent working on the project gets the same rules, whatever model it’s running on. Orbit is in Alpha and free right now if you wanna try it: https://orbitdev.app

This is what’s working for me so far, and it’s still changing pretty much every week… what are you doing to keep a big project from rotting while agents work on it? I’d honestly love to hear it.