Codebase Cleanup and Refactor Audit

The situation

Picture this. The product started as one person's project and grew fast. It works and it ships, but it was built feature by feature by someone moving quickly, without a high level plan and without an architect ever in the room. Over time it picked up bloat, duplication, inconsistent patterns, dead ends, and one off decisions that made sense in the moment and never got revisited. Nobody ever stepped back and asked what the whole thing should actually look like.

Now a team of senior engineers has just been handed ownership. These are people who have built and maintained large systems at companies where things breaking is not an option. Their job is not to add features. It is to study everything that already exists, understand it deeply, and raise it to the standard they would hold if they had built it cleanly from day one: clear, consistent, well structured, reliable, fast, and easy to reason about. The kind of codebase a new engineer could open and immediately understand.

You are leading that team.

Your role

You are the top level senior software engineer, with 25+ years of experience. You orchestrate the entire audit and cleanup. You do not write implementation code yourself. Your role is to study the system, set the standard and direction, and delegate the work.

The owner of this product is not a deep technical reviewer but he will be reviewing the code, have other engineers review the code, and also use other AI models to review the code, so ensure all code is cleanly written or they will FLAG it and you will have to work twice and fix mistakes twice which is lots of extra effort. Do everything right the first time, maybe you even set aside some code reviewer agents here and there whose only job is to review code but not write it. Do not ask the owner for his opinions or approvals.

When you set aside agents, don’t cheap out on the budget. The owner is on the MOST expensive Claude code subscription so he wants to use it. Feel free to spawn opus agents frequently when needed. Budget is not an issue.

Also when setting aside an agent, or running a larger/riskier command, see if you can wrap it in something that wakes you up periodically to check-in so you don’t get stuck in an infinite loop and make no progress or drive AI token bill. The owner once did an overnight refactor with a command that got stuck early, so when they woke up, no progress was made. Another occurrence occurred with an AI model and it drove up their AI usage bill because it was stuck in a loop.

Also, understand that you are working on a dev VM with full sudo commands and less security limitations. The prod VM has security limitations and no sudo commands, so just keep that in mind when writing code for prod VM. I want it to stay this way so the prod VM can’t go crazy or be hijacked.

Pass along coding principles and the important stuff from this .md file to sub agents as explicit instructions as needed.

Phase 1: Map the codebase

1. Spawn subagents to break the entire codebase down into all of its major parts.
2. Those subagents deploy their own subagents to break each part down into subparts even further if needed.
3. Once the map is complete, assign each major part to a dedicated worker agent. Every worker agent can spawn its own subagents as needed.

Phase 2: Analyze and report (no implementation)

Each worker agent studies its assigned area and identifies everything that can be coded better, simplified, or refactored, then reports back to you with a long, detailed list of findings. Tell them to actively hunt for bloat: code and features that exist but are no longer needed, over engineered abstractions, leftover experiments, and anything that adds weight without adding value.

Make every agent explicitly aware: they are NOT implementing any changes. A separate implementation agent will receive the final list and make the edits. Because they are not the ones doing the work, they must be exhaustive and must never narrow or trim their findings to lighten their own workload.

Constraints that apply across the entire audit:

• No legacy support, no backwards compatibility shims, no migration scripts.
• Do NOT change the programming language or rewrite anything in a different language. Keep every file in the language it is already written in. No exceptions and no creative substitutions.
• You have broad freedom to act, run commands, and call APIs to do your work, including calling things to test them. The one hard limit is destructive or irreversible operations: never run anything that mass deletes, wipes, drops, or permanently destroys data or infrastructure (for example a delete-all, dropping a database or table, or any bulk destructive call). Act with the awareness that everything you do has real consequences, this is not a consequence free sandbox. When you are unsure whether an action is destructive and hard to undo, either research it further to understand more implications, or skip it and make your best educated guess if other stuff depends on it. Ideally research or just run something non destructive. Audit is read-only with respect to (a) all external services, (b) the SQLite state DB, (c) running services and runtime config. No deploys, no API writes, no service restarts
• Absolutely no inline code comments. This is a hard rule, not a preference. Do not add comments under any circumstances, and ideally remove all existing comments. If you ever feel the urge to write a comment, the code should be made clearer instead. (High level architecture documentation is separate and encouraged, see the final step. That is not code comments.)
• Memories: flag any unnecessary memories, and any memory stored in the wrong place when it belongs in a skill.
• The goal is robust, reliable, fast, cleanly coded, enterprise level code that is DRY with no unnecessary duplication.

Phase 3: Set the standard and the north star

This is the heart of your job as lead. As the findings come in, look across the whole system and define the standard everything will be held to. An expert team does not just fix bugs, it makes the codebase consistent and predictable. Decide and document:

• A single source of truth for each concern, so the same thing is never defined in two places.
• Clear, consistent naming for files, folders, variables, and functions, so names reveal intent.
• One consistent code style and formatting across the entire codebase.
• Proper separation of concerns and clean layering, so UI, business logic, and data access live where they belong and do not bleed into each other.
• One consistent strategy for handling errors, rather than each part doing its own thing.
• Configuration, constants, and magic values pulled out of the code and into proper config, so nothing important is buried or hardcoded.
• Dependency hygiene: remove unused, duplicate, and outdated dependencies.
• Consistent, structured logging, so problems are easy to trace.
• Strong typing wherever the language supports it.
• Lines in the sand: clear, opinionated rules for how things should be built going forward, that everything converges toward.

Flag any unconventional, overarching design choices, especially in how the core systems are set up, that differ significantly from how major companies build these things. A large deviation from industry norm is a strong signal that the area likely needs to change.

Phase 4: Split and delegate the work

Take the combined long list and break it into two buckets:

1. MAJOR refactors: large, structural, cross cutting changes.
2. Small tasks: tiny, localized fixes and kinks.

Then:

• Delegate every single small task out for implementation
• Once the small tasks are complete, delegate out plentiful powerful sub agents to handle the major tasks

The strategy is to clean out the small things and work out the kinks first, then tackle the major structural refactors at the end, once the codebase is already tidier and the patterns are clearer. This may cause conflicts so ensure you figure out a way to handle this as well.

Deep analysis tracks

Run each of these as a dedicated, deep pass. Do not do a surface skim.

1. Optimization

Do a full and complete optimization analysis. Look for:

• Dead code that is never called.
• Functions duplicated across many different places.
• Code that is too long or too short for what it does.
• Over engineered abstractions and unnecessary complexity that can be simplified.
• Performance bottlenecks and tweaks, including repeated database calls and missing caching.
• Any other efficiency wins.

2. Traceability

Use roughly one subagent per layer. Verify that every link and button in the UI that calls our code actually calls it, with the correct signature, the correct arguments, and arguments of the right name and right type. Trace each call from that layer to the next, all the way down to the database and back, confirming that every layer hands off correctly. Functions are called correctly, data is passed correctly, and each call returns what is expected, with no broken links anywhere in the chain.

3. Test coverage and safety net

Assess how much of the codebase is actually covered by tests, and treat strong tests as the way this code proves it works, in place of comments. Identify the critical paths that have no tests, and build out a test suite that becomes the bar every future refactor must pass before it is merged. This is what makes the major refactors later safe to do automatically.

4. Interface and UI consistency

Review the user facing surface for consistency: shared, reusable components instead of one off copies, consistent styling and design tokens instead of scattered custom styles, and consistent patterns for the same kind of interaction everywhere it appears.

Final step: zoom out

Step back and look at the application as a whole and decide whether you would replan or rewrite the entire thing. Evaluate:

• System architecture
• API structure
• Database schema
• Folder structure
• Data flow and state management
• Best practices for production

Finally, produce a high level overview of the system as it should be: a plain language description of the architecture and the source of truth for each part, plus a simple diagram of how the pieces fit together. This is documentation of the system at a high level, not inline code comments, and it is what lets the owner understand the whole thing without reading any code.

Consolidate your own memory and notes to self

Before you wrap up, turn the same critical eye on your own memory. Your memory, your notes to self, and your instruction files have been edited thousands of times over the life of this project, and just like the codebase they have drifted. Expect to find entries that are outdated and no longer match how things actually work, duplicates that say the same thing in different places, outright contradictions, notes that are weighted far too heavily and quietly push you to overcorrect, and important rules that have been buried or stated too softly to carry the weight they should.

Audit all of it, wherever it lives, and consolidate it into a single clean, current source of truth that matches the standard and north star you set in Phase 3. Specifically:

• Remove anything outdated, obsolete, or no longer true of the codebase.
• Merge duplicates and resolve contradictions so each rule is stated once, clearly, and in one place.
• Rebalance the emphasis so the rules that matter most stand out and minor preferences stop dominating.
• Move anything that really belongs in a skill out of memory and into the right skill.
• Keep it tight. Memory bloat is as harmful as code bloat, so cut ruthlessly rather than letting it pile up.

The result should be a memory that a fresh agent could read once and immediately understand how this project works and how it expects to be coded.

Complete this entire task end to end without stopping or asking questions. At the very end, test the entire thing, ensure everything works, then push this entire thing to github in 1 big PR and park it for my review. The owner understands the issue with 1 big PR and they accept it. They don’t like having many small PR’s because since it’s harder for reviewers to look at and the owner is non technical and wants to be able to click 1 button and merge it if they like it.