How i documented a Broken codebase without losing my mind.

A developer built Compass, an open-source parallel-agents workflow that documents legacy and high-tech-debt codebases by mapping implicit architecture and infrastructure into explicit documentation. The tool spawns multiple agents per phase across user-defined domains to surface duplicated business logic, zombie tables and columns, and unverified dependencies, aiming to give future AI coding agents the constraints and context they need before implementing changes.

If you want to use it straight away | Link here https://github.com/crusadev/compass 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 https://engineering.fb.com/2026/04/06/developer-tools/how-meta-used-ai-to-map-tribal-knowledge-in-large-scale-data-pipelines/?utm source=chatgpt.com . 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: And the Analyst agent answers the next five questions: 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: { 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. { applied, rejected, validatorClean, lines } , here rejected is really important, the rejected claims are reported 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.