Note: The views expressed in the post reflect the AI capabilities at the mentioned time period. The capabilities have advanced since then.
Not long ago (Q3 2025) I was dealing with a legacy code base where:
- code was not readable
- no context available in documents
- no automated tests
- no developer who had enough context to share with new folks
It was running in production for years and got into issues regularly which affected customers and business.
The domain was not super complex but managing the legacy applications was super challenging because of the missing context.
Without understanding the big picture it was hard to make changes with clarity and confidence.
Claude Code came in handy for me to explore and understand the legacy code base. In a short period I could generate:
- system diagrams with overview of the architecture
- tech stack
- message sequence charts to explain interaction between system components
- major workflows
- system dependencies
- API endpoints, schema
- error handling
- known issues and fixes …
NONE of this was 100% accurate but each of it provided a hypothesis to explore and understand the system. It was better to start with a plausible hypothesis than with nothing.
I was able to make more sense of the system with the help of the artifacts but it required manual scrutiny to complement the AI generated artifacts.
Despite this there were gaps in understanding for ex. why certain design decisions were made and if the factors which motivated those decisions were still valid.
Tools like Claude Code are cool and powerful but still it didn’t give me the confidence and clarity I have experienced (in the past projects) when I spoke to original owners of the code, had whiteboard sessions to understand the architecture, read thoughtfully written docs, stepped through a debugger or logs to understand the flow and data processing.
If using AI tools is going to stop engineers from writing good docs explaining the thought process (assuming there is one) which got translated to design and code, I’m afraid we will generate more implementations which will feel like orphaned legacy code sooner than later.
The leap from understanding to embodiment is natural, verifiable and easier.
Working back from embodiment to understanding is error prone, lossy and harder.