How i documented a Broken codebase without losing my mind.

If you want to use it straight away | Link here

I believe we achieved a point in tech where having a broken codebase that started as an MVP and evolved into a landmine is not something rare or a red flag anymore.
At the rate of how Frontier Models evolve, its normal for a codebase that was built through AI-Powered development 2 years ago to be composed by a combination of poor system design and bad practices, there is no shame in that.
Maybe you are thinking ‘In a serious startup, you fix that, or you wouldnt have gotten to that point’, my response is that you would be surprised and that in 99% of cases you dont have time to refactor or patch everything up.
You can ( and should ) do it slowly, every time you touch a piece of your software, try to fix something and get rid of that Tech Debt, but there is a problem bigger than that, the situation where a legacy, or one that carries deep tech debt, codebase does not have documentation, and trust me, that happens often.

So we have a broken codebase that started as a poorly-built MVP and without documentation, now lets try Ai-Driven Development on top of that, what will happen? Of course that depends on what type of tech debt you carry, in our scenario it was:

Duplicated business logic → no single source of truth / poor separation of concerns.
Zombie tables and columns → accumulated schema/structural debt and unclear ownership.
Manually tracking downstream effects → implicit dependencies and high change coupling.

I consider these the worst type of Tech Debt, having core business logic as duplicated functions instead of defined once and reused, columns and databases that look right, are populated, but dropped at some point and replaced are the exact types of problems that push bugs to the maximum even when working with the best frontier models.

So now we have a broken codebase, no documentation, the Ai agent is more confused than i am and the cherry on top, i could spend a lifetime documenting ( or repairing ) the code and it still would not be enough time, what the hell can i do?

Well, i found a pretty strong solution through this Meta article here.

The premise is simple, we build a ‘documentation’ using a parallel-agents workflow with pre-defined agents, that will thoroughly analyze the codebase using a strict set of rules so it wont generate garbage files with 500 lines of AI slop, it instead follows what they call a ‘compass’ approach, where for every context it extracts:

1. Quick Commands (copy-paste operations).
2. Key Files (the 3–5 files you actually need).
3. Non-Obvious patterns.
4. See Also (cross-references).

And the Analyst agent answers the next five questions:

1. What does this module configure?
2. What are the common modification patterns?
3. What are the non-obvious patterns that cause build failures?
4. What are the cross-module dependencies?
5. What tribal knowledge is buried in code comments?

There is more to explain from the article, but you can read it yourself, here i will document how i implemented it for our codebase, what was my experience and how you can replicate it.

The premise is simple, build a documentation that takes the infrastructure/architecture from implicit to explicit, this way future dev agents have a direction and are aware of the constraints and tech debt, instead of blindly assuming that everything is right, they are asked to research properly and told what to research before implementing.

The approach

It starts with a skill called /map-domain, it defines a pipeline with 4 phases, spawning N agents in parallel per phase where N is the number of domains ( defined below ).

Domain | In my specific scenario, for this workflow, i defined domain as the smallest thing someone would name when they say what they are working on, ex. Orders, product, payments, billing, subscriptions etc etc.

The domains must be defined by you or carefully seeded by talking with your agent, and they will contain ( besides name ) about and hints.

The pipeline phases are the next:

• Analyse: Reads the skill’s context, the CLAUDE.md, then takes his domain ( as i said, one agent per domain ) and does research to answer to the five questions in a compass file with its domain name. This agent returns { domain, wrote, lines, duplicatedLogic, zombies, contradictions, couldNotVerify, belongsElsewhere } to the pipeline, the belongsElsewhere is useful since an Analyst writes only his own compass and he might ( and will ) find useful information on other domains, so they dont get lost, they get passed to its owner.
• Critique: Gets the compass file the Analyst generated and the domain data, it skips the reasoning of the Analyst so the context is fresh, his task is to go through each factual claim written by the Analyst and grades them:
  • CONFIRMED — the cited code says exactly this
  • WRONG — the code contradicts it
  • OVERSTATED — true in the branch cited but written as a general rule
  • UNCITED — asserted with nothing a reader could check He is not allowed to actually edit the compass, his objective is to report back.
• Fix: This agent takes the report of the critic and verifies each flagged claim and he returns { applied, rejected, validatorClean, lines }, here rejected is really important, the rejected claims are reported
• Sweep check: One agent, at the very end of the flow, he checks the next:
  • Files that are thin, vague, or padded to look substantial
  • Contradictions between compass files — two describing the same table or formula differently
  • Domains that still have no compass file
  • Facts stated in several files that one should own
  • See also links pointing nowhere useful
• Route facts: One extra step between Fix and Sweep Check for analysts that returned belongsElsewhere, it verifies the claim and files it with its owning compass file

In a nutshell: Analyse writes. Critique checks without being able to write. Fix repairs only what was found. Sweep check sees the whole and catches what no single domain could.

A couple of days has passed since i implemented this, clearly not enough to calculate its real value, but i was able to fix and implement several changes into our database, one shot, without me having to mention constraints and gotchas straight out of my overwhelmed mind that i used to mention.

Now i dont want you to take this article as the perfect recipe for fixing your AI-generated codebase, through this article i wanted to raise a real recurring problem i noticed and document what i implemented on my side to fix it, its not a silver bullet but its the best shovel i found to dig out of the AI tech debt trench.