Cleanup Fridays for AI-heavy repos with less drift

Why AI-heavy repos drift fast

AI-heavy repos get messy faster than most teams expect. The speed feels great at first. A prompt creates a helper, a script, or a one-off test in minutes, and nobody wants to slow down to clean it up.

That speed has a cost. Small experiments leave behind files that made sense for one afternoon and never got removed. A team tries three approaches, keeps the winner, and forgets the rest. Two weeks later, nobody knows which folder still matters.

Prompt-driven work also changes shape fast. A helper that looked useful on Tuesday can become dead weight on Thursday because the prompt changed, the model changed, or the workflow moved into another script. People rarely delete these leftovers right away. They keep them "just in case," and the repo gets heavier without getting better.

Duplication sneaks in the same way. Someone copies a parser, a formatter, or a retry wrapper into a new folder because it is faster than hunting for the old version. Then another person does the same thing in a different area of the repo. Soon the same logic lives in three places, each with tiny edits. That is how bugs start to feel random.

Names drift too. A file called temp_runner becomes part of the real workflow. A folder named new_pipeline stays around for six months. The label says one thing, the code does another, and every new teammate pays that confusion tax.

Teams that build with AI tools hit this problem even harder because they produce more code, more drafts, and more near-misses in less time. Oleg Sotnikov has written about AI-first development as a speed advantage, and that speed is real. Still, fast output needs regular pruning. Without it, the repo stops feeling like a system and starts feeling like a junk drawer where old ideas never quite leave.

Choose a small cleanup scope

A weekly cleanup works only when it stays small. Cleanup Fridays for AI-heavy repos fall apart when the team tries to fix everything at once.

Keep the pass under 30 minutes. That time limit stops the session from turning into a rewrite, and it makes the habit easier to repeat next week.

Start with files from active work. Fresh changes are still easy to read, and the people who touched them still remember why they exist. If your team spent the week editing agent prompts, API wrappers, or test helpers, clean those files first.

Small scope also means low risk. Friday is a bad time for deep refactors that touch shared logic or change behavior. If a fix needs new tests, careful review, or migration work, park it for later.

A short pass usually looks like this:

• rename two or three files with vague names
• delete one helper nobody calls anymore
• merge one duplicated pattern into the clearest version
• note one bigger issue for a proper task next week

That last step matters. Bigger cleanup jobs should not disappear into memory. Put them on a short list with a plain label, such as "split this module" or "remove old retry wrapper." Keep the list short enough that someone might actually do it.

One simple rule helps: only clean what you can explain in one sentence. "This file name hides what it does" is good. "We should rethink the whole architecture" is not.

Teams that use AI coding tools often create extra helpers, near-copy files, and quick patches faster than they notice. A narrow cleanup scope keeps that drift from piling up. You leave Friday with a repo that is a little easier to read, and you do not spend Monday undoing a rushed rewrite.

Run a 30-minute Cleanup Friday

Pick one short slot at the end of the week and treat it like repo hygiene, not a refactor sprint. Cleanup Fridays for AI-heavy repos work because they stay small. Thirty minutes is enough to reduce drift, but short enough that nobody turns it into a side project.

Start with the folders your team changed this week. Do not scan the whole repo. AI-assisted work creates lots of fast output, and most of the mess sits near recent changes. If three people touched agents/, prompts/, and utils/, open those first and ignore the rest.

A simple pass often looks like this:

• Rename the worst file names first, especially files like tmp_final_v2, new-flow, or helper-old.
• Check helper files that feel suspiciously quiet and remove ones with no live callers.
• Find one repeated pattern that showed up two or three times this week and fold it into one clear path.
• Leave a short note in your team chat or tracker about what changed.

Rename before you merge patterns. Clear names make duplication easier to spot. If a file name tells people its job in two seconds, they make fewer bad edits next week.

Dead helpers deserve less sentiment than most teams give them. If nothing calls the function, and no active branch needs it, delete it. Keeping old helper code

Rename files so people can guess their job

AI-heavy repos collect vague names fast. A model writes a helper, someone tweaks it by hand, then the file survives as temp2.ts, newFlow.py, or finalFinal.jsx. A month later, nobody knows what it does, what feature it belongs to, or whether it is safe to touch.

A good file name answers one plain question: what job does this file do? If it handles invoice export, call it invoice-export.ts. If it renders billing settings, call it billing-settings.tsx. People read the file tree before they read the code, so the name should do some of the work.

Use the feature as the anchor, not the moment when the file got created. The difference is easy to see:

• temp2.py -> lead-scoring.py
• finalFinal.ts -> customer-import.ts
• helper_new.go -> retry-policy.go
• test_copy.spec.ts -> customer-import.spec.ts

Keep the naming style boring and consistent. If your repo uses kebab-case, keep using kebab-case. If a language or framework has a strong convention, follow that convention everywhere in that part of the repo. Mixed styles make simple searches harder than they should be.

Match the file to the feature it supports, not a vague technical bucket. auth-token-refresh.ts is clearer than utils.ts. checkout-discounts.rb tells a better story than service_helper.rb. You do not need perfect names. You need names that help the next person guess right.

Rename related test files in the same pass. If customer-import.ts changes name, its spec or test file should change too. Otherwise the repo starts to split into two versions of the same idea: one in production code, one in tests. That confusion spreads into imports, search results, and failed cleanup later.

One small rule helps: if a teammate cannot guess the file's purpose from its name alone, rename it on Friday. Five careful renames can make a messy folder feel readable again.

Delete helpers that no longer earn space

AI-heavy repos collect little leftovers fast. A helper solves one prompt experiment, one migration, or one rushed bug fix, then nobody touches it again. Leave enough of those behind, and people stop trusting file names and function names.

Delete with care, not speed. Before you remove anything, check every caller you can find: imports, tests, scripts, scheduled jobs, and command line entry points. A helper can look dead in the app and still run in a nightly task.

A simple rule helps: if a wrapper only renames another function, it probably should go. When run_customer_summary() does nothing except call generate_summary(), the extra name adds one more place to read and one more place to forget. Keep the clearer function name, update the callers, and delete the wrapper.

Old prompt variants are another common pileup. Teams often keep files like prompt_v2.txt, prompt_v2_final.txt, and prompt_v2_final_really_final.txt long after the code stopped using them. If no script loads them, no test checks them, and no one plans to compare results again, take them out of the repo.

Scratch notes deserve the same treatment. Quick research notes, copied logs, one-off debugging snippets, and raw prompt experiments can help for a day or two. After that, they turn search results into noise. Move them to a private notes folder or a shared workspace outside the repo if the team still wants them.

Use a short test before you delete:

• Search for callers in code, tests, and scripts
• Check whether CI or scheduled jobs still use it
• Ask whether the helper adds real logic or just a new name
• See whether anyone opened or changed it in recent work
• Move reference notes out before you remove the file

One small team I worked with had six prompt files for the same support reply flow and three helper functions wrapped around the same API call. They kept the one prompt that production used, deleted the abandoned variants, and removed two wrappers. The next person spent less time guessing and about 15 minutes less per change.

Weekly repo cleanup works best when deletion feels normal. If a file no longer earns its place, remove it while everyone still remembers what it did.

Fold repeated patterns into one simple path

During Cleanup Fridays for AI-heavy repos, repeated patterns are often the easiest mess to fix. AI code tends to clone itself: one prompt runner for summaries, another for tags, a third for drafts, all with slightly different retries, logging, and output cleanup.

Put two similar flows side by side and compare them line by line. Ignore names for a minute and look at what they actually do. You will usually find the same steps hiding under different wrappers.

Check the same few things each time:

• how each flow shapes input before the model call
• where retries and timeouts live
• how each one parses model output
• what logging or error handling people copied and tweaked

Keep the version that a tired teammate can read fastest. Clear beats clever. If one file uses one helper and six tiny callbacks while the other does the same work in 25 direct lines, keep the direct one.

Then pull only the shared steps into one small file. That file might hold input cleanup, retry rules, or output parsing, but not every decision. The caller should still show what makes that flow different, or you just move the mess to a new address.

A small team often sees this with classifier scripts. One script trims text, calls a model, parses JSON, and retries once. Another script does the same job for a different label set, but with slightly different names. Merge the repeated steps, keep one calling style, and both files get easier to trust.

Stop after one pattern. If you try to merge prompt builders, background jobs, and test helpers in the same 30-minute pass, you will spend the rest of Friday chasing side effects. One pattern, one clean path, one small commit.

A simple example from a small team

A four-person product team keeps prompts, tests, and utility scripts in one repo. That setup is common in fast-moving AI work, and it gets messy fast. One person adds a prompt tweak, another adds a quick checker, and a third copies an old review script because it is faster than hunting for the right one.

By Friday, the repo still works, but nobody sees it clearly. During a short Cleanup Fridays for AI-heavy repos pass, the team notices something simple: two folders handle almost the same review flow. One folder scores model output for internal checks. The other does nearly the same thing for regression tests, with slightly different file names and one extra helper.

They stop adding to both paths and pick one. The team keeps the cleaner folder, moves the shared logic there, and renames files so the job is obvious at a glance. Instead of names like check_final.py and review_new.ts, they use names like review_runner.ts, review_prompt.md, and review_cases.json.

They also delete helpers that no longer earn their place. An old parser, a backup formatter, and one tiny script that only calls another script go away. None of that changes product behavior. It just removes choices nobody needed.

The cleanup takes about 30 minutes:

• compare both review paths side by side
• keep the version with fewer exceptions
• move shared files into one folder
• rename confusing files
• delete helpers nobody calls

Monday feels different. A failing review test shows up, and the first engineer who opens the repo knows where to look. No one asks which folder is current. No one opens three similar files to guess which one matters. The team saves maybe 20 minutes on the first task alone, and the repo gets a little easier to trust.

Mistakes that waste the cleanup pass

A short cleanup window works only when you keep it small. The fastest way to lose the benefit is to treat 30 minutes of cleanup like a chance to redesign half the repo. You start by renaming two files, then you rethink folder structure, then you touch tests, then you argue about architecture. Friday is gone, and the repo is only half changed.

Another common mess starts with file renames. A new name may look better, but the job is not done until every import, script, test, and doc line points to the new path. If one stale import slips through, the team spends Monday fixing a problem that should never have shipped.

Deleting old helpers causes the same kind of pain when people move too fast. A helper can look dead and still get called by a background job, a rarely used script, or one old test fixture. Before you remove it, search the repo, check recent commits, and run the smallest useful test pass. Five extra minutes beats an hour of rollback.

Merging repeated patterns can also go wrong. Two functions may look almost the same, but one might handle retries, odd input, or stricter validation. If you fold them into one path too early, you hide those differences and create fresh bugs.

A simple rule helps:

• stop when cleanup turns into redesign
• rename files only with import fixes in the same change
• check usage before you delete anything
• merge duplication only after you compare edge cases
• leave a short note on why the change happened

That last point matters more than people think. When you remove a helper or collapse two patterns into one, add a brief note in the commit message or team chat. A sentence like "merged two JSON parsers because both now use the same validation rules" saves the next person from guessing. Without that note, the repo may look cleaner, but the team still loses time.

Quick checks before you end Friday

A cleanup pass can save a repo from slow messes, but the last five minutes decide whether it helps or hurts. Small fixes feel safe, yet renames and deletions often break things in quiet ways.

Run the tests closest to the files you changed. You do not need the full test suite if that takes an hour, but you should run enough to catch a broken import, a missing helper, or a renamed function that left one call behind.

After that, search the repo for old names. File renames are easy to miss in one script, one test, or one config file. A fast text search for the previous file name, function name, or helper name usually finds the leftovers before your teammate does on Monday.

Then read the diff like someone who did not write it. Look for accidental edits, debug logs, formatting noise, or generated changes mixed in with real cleanup. If you meant to touch four files and the diff shows twenty, trim it now.

One person should understand the whole change in plain words. That can be you, or one teammate doing a quick read. If nobody can explain why a helper disappeared, why two patterns became one, or what a new file name means, the pass grew too wide.

Leave one short note for Monday. Keep it plain: what you renamed, what you removed, what tests you ran, and anything that still needs a second look. In Cleanup Fridays for AI-heavy repos, this tiny habit matters more than people expect. A note like "renamed prompt_utils to prompt_formatting, removed two unused helpers, ran parser tests, check admin import on Monday" saves real time and stops repeat work.

After four Fridays, set a few rules

By the fourth pass, Cleanup Fridays for AI-heavy repos should stop feeling like random tidying. You have enough evidence to see what keeps coming back. Maybe people keep adding vague file names like utils2, maybe old prompt helpers pile up, or maybe the same logic appears in three folders with small changes.

Do not write a long repo policy. Write the smallest rules that block the mess you actually saw.

A good start is usually this short:

• One naming rule: file names must say what the code does, not where it came from or who wrote it.
• One folder rule: each folder gets a single purpose, and mixed leftovers move out.
• One cleanup rule: if someone replaces a helper, they delete the old one in the same pull request.

These rules work because they are easy to remember. People follow simple rules. They ignore long documents.

Rotation helps too. If the same person runs the weekly repo cleanup every Friday, they become the janitor and everyone else stops noticing drift. Pass the job around. One developer can do the pass this week, another can do it next week, and a team lead can review the notes once a month. That keeps standards shared instead of hidden in one person's head.

Keep a tiny log for four more weeks. Just one line each Friday is enough: what repeated, what rule fixed it, and what still slips through. If a rule never changes behavior, drop it. If the same problem returns after two or three reminders, tighten the rule or make it part of code review.

Some teams still drift because the repo shape itself invites clutter. The folders may be wrong, generated code may mix with hand-written code, or AI output may land in too many places. If that keeps happening, an outside review can save time. Oleg Sotnikov can look at the setup as a Fractional CTO and help your team set a simple cleanup routine that fits how you build, not a generic process that nobody keeps.