Code Archaeology with AI

Every company has a closet full of old code. Maybe it’s a Perl script that generates invoices and nobody knows how it works. Maybe it’s a Java monolith that was “temporary” in 2014. Maybe it’s a MATLAB folder from grad school that you swear you’ll get back to someday. I recently revived some of my own old MATLAB code and along the way learned a lot about how AI assistants handle the particular challenge of understanding code that nobody has touched in years.

Code archaeology is the practice of digging through old codebases to understand what they do, why they were written that way, and whether any of it is still useful. It’s a skill every developer needs but nobody teaches. And it turns out AI is surprisingly good at parts of it and hilariously bad at others.

What AI Is Good At

Reading Unfamiliar Languages

This is probably the single best use case. I had MATLAB code I hadn’t looked at in over a decade. I don’t have a MATLAB license anymore. I barely remember the syntax. But when I fed the files to Claude, it could read them fluently and explain what each function was doing in plain English.

This generalizes well. Got a codebase in a language you don’t know? An AI assistant can act as a translator, walking you through the logic without requiring you to learn the full language first. I’ve used this trick with old Fortran code, R scripts, and even some truly cursed Bash. The AI doesn’t care that the code is ugly or that the variable names are single letters. It just reads it.

Identifying Patterns and Architecture

When you’re staring at a folder full of files you’ve never seen before, one of the hardest things is figuring out how everything fits together. Which file is the entry point? What calls what? Where does data flow?

AI assistants are good at this. Give them a handful of files and they can usually sketch out the architecture, identify the main abstractions, and explain the relationships between components. They’re especially good at recognizing common patterns: “this looks like a factory pattern” or “this is implementing a pub/sub system.” That pattern recognition saves hours of manual tracing.

Generating Documentation

Old code is almost never documented. When it is, the documentation is wrong. AI can generate reasonable documentation from code that has none, and it does a better job than you’d expect. It picks up on implicit contracts, explains side effects, and can even flag things that look intentionally weird vs. accidentally weird.

I’ve started using this as a first pass whenever I inherit a codebase. Have the AI generate docs, then read the docs with the code open and correct whatever it got wrong. It’s faster than writing docs from scratch and it forces you to actually verify your understanding.

What AI Is Bad At

Understanding Why

AI can tell you what code does. It struggles to tell you why. This is the fundamental limitation of code archaeology with AI, and it matters more than you think.

When I was porting my MATLAB code, the AI could see that I was using a specific mutation rate schedule that decayed over generations. It could describe the schedule perfectly. What it couldn’t tell me was why I chose those particular values. Were they theoretically motivated? Did I tune them empirically? Was I just copying a paper? I honestly couldn’t remember either, but at least I knew that I didn’t know. The AI would cheerfully make up a plausible-sounding justification if I asked.

This is where hallucinations in code archaeology get dangerous. The AI will confidently explain the “reasoning” behind arbitrary implementation choices. If the original developer isn’t around to correct it, that fabricated context becomes the accepted truth. Always treat the AI’s explanations of intent as hypotheses, not facts.

Historical Context

Code doesn’t exist in a vacuum. That weird workaround in line 47 might exist because of a bug in Python 2.6 that was fixed in 2.7. That strange data format might match what a vendor’s API used to return before they updated it in 2019. The AI doesn’t know any of this. It sees the code as it is today and reasons about it in isolation.

I’ve seen AI assistants suggest “cleaning up” workarounds that were there for very good reasons. Without git history, issue trackers, or institutional knowledge, the AI is essentially making assumptions about constraints that may or may not still apply.

Knowing What’s Dead

One of the biggest challenges in old codebases is figuring out what’s actually used. Is this function called from somewhere? Is this configuration file still relevant? AI assistants will analyze code in isolation but they can’t reliably tell you whether a particular module is still reachable from any entry point. They’ll dutifully explain dead code as if it matters.

Static analysis tools are better at this. Use those first, then bring in the AI to understand the code that’s actually alive.

A Practical Workflow

After a few rounds of code archaeology with AI, I’ve settled on a workflow that seems to work well:

Get the lay of the land manually. Look at the directory structure, check git history if it exists, read any README files. Don’t start with AI.
Use static analysis first. Run whatever linters, type checkers, or dependency analyzers apply. This gives you ground truth about what’s connected to what.
Feed the AI individual files with specific questions. “What does this function do?” works better than “explain this codebase.” Focused questions get better answers.
Cross-reference AI explanations with the code. When the AI says “this function handles authentication,” verify it. When it says “this was probably done for performance reasons,” be skeptical.
Use the AI for translation and porting. This is where it really shines. Once you understand what the code does and why, the AI can help you rewrite it in a modern language or framework much faster than you could do it manually.
Write your own documentation as you go. Don’t just accept the AI-generated docs. The process of correcting them is where the real understanding happens.

The Bigger Picture

Code archaeology is going to become more important, not less. We’re generating code faster than ever, and the shelf life of that code isn’t getting any longer. The volume of legacy code in the world is growing, and the people who wrote it are retiring, changing jobs, or just forgetting what they did.

AI assistants are a genuine force multiplier for this work. They lower the barrier to understanding unfamiliar code, especially in unfamiliar languages. But they’re a tool, not a replacement for the hard work of actually understanding why code exists and whether it should continue to exist.

The code itself is just the artifact. The real archaeology is reconstructing the decisions, constraints, and context that produced it.