Old Repositories Hide Decisions AI Can Recover

Old Repositories Preserve Decisions the Docs Never Recorded

Software archaeology means reading old code to understand the people and pressures behind it. A repository that has survived several years is more than a collection of functions. It holds abandoned experiments, rewritten modules, defensive checks added after a painful failure, and comments written late at night. Documentation rarely keeps pace with that churn, so the history itself becomes the record. For a newcomer the task can feel impossible, because the code is dense, the names are cryptic, and the original authors have long since moved on.

Artificial intelligence changes the economics of that reading. A language model can absorb far more of a repository at once than a person can hold in working memory, and it can describe patterns across thousands of changes without growing tired. That does not make it an oracle. It makes it a patient reading companion, one that can summarize, suggest connections, and surface questions worth asking. Used with care, it compresses weeks of puzzling into days of guided investigation.

Beginners often assume this practice is only for emergency work, yet the habit helps even on healthy projects. Understanding the reason a boundary sits where it does prevents accidental breakage, and understanding which parts are fragile tells you where to add tests first. AI lowers the entry cost of that understanding, because you can ask plain questions and receive plain answers while you learn the vocabulary of the codebase.

AI Turns Commit History Into a Readable Narrative

The richest source of context in an old project is usually its change history. Every accepted change carries a small story: a problem appeared, someone investigated it, and a particular shape of code won the argument. Models are good at weaving those fragments into a narrative. Give one a batch of change descriptions and it can group them by theme, identify periods of heavy activity, and point out where a module was rewritten three times in a single quarter.

That narrative matters because it explains intent. A function with an awkward signature may look like poor craftsmanship until you learn it exists to support a client integration that disappeared two years ago. A block of defensive logic may look paranoid until you discover it guards against a failure that once took the service offline. The role of the model is to raise those possibilities so that you can confirm them against the record.

Ask the model to answer in layers, and the output becomes far easier to trust:

• a plain summary of the area you are studying
• a list of hypotheses about the shape of the code
• the specific changes or comments that support each hypothesis
• open questions that only a maintainer could settle

The first layer helps you orient, the second gives you theories, the third keeps those theories tied to evidence, and the fourth admits the limits of what code alone can tell you. Repeating this shape for every area you study creates a consistent body of notes that other engineers can skim without redoing the work.

Grounded Prompts Keep Model Answers Close to Evidence

The largest risk in AI-assisted archaeology is confident invention. A model can describe a rationale that never existed, credit a teammate who never worked on the project, or invent an incident that left no trace. Treat every claim as a lead rather than a fact. Ask for the supporting changes, read them yourself, and discard anything that cannot be traced back to the repository.

Useful prompts for this work share a few traits. They name the scope, they ask for uncertainty to be marked, they prefer small chunks over whole-project sweeps, and they request counter-explanations. If a model claims a module was added for performance reasons, ask it to argue the opposite case as well. The disagreement is often more informative than the first answer, because it reveals the parts of the story that rest on thin evidence.

Small chunks also keep long explorations stable. Extended conversations drift, and later answers start carrying assumptions from earlier turns that may no longer hold. Reset often, feed the model only the material relevant to the current question, and keep your own notes outside the conversation so the reasoning survives independently of the tool.

Experienced Readers Still Decide What Counts as Truth

No model can replace the engineer who signs off on a change. Verification is where archaeology earns its value, and it follows a simple discipline: read the cited changes, run the relevant tests, and compare the explanation against the surrounding context. Code that is no longer exercised deserves special suspicion, because it often hides assumptions from an earlier era of the system.

Real systems are also messier than neat explanations suggest. Sometimes a module exists because two teams negotiated an awkward compromise, and no elegant rationale will ever fit. AI answers tend to smooth that texture away, so resist the urge to accept the cleanest story. The honest finding is often that the reason is lost, and admitting that is more useful than a polished guess.

The work pays off in practical ways. Teams use these readings to plan safe refactors, to explain old behavior before a migration, to review incidents with better context, and to help new engineers become productive without months of wandering. Each verified finding becomes a small piece of institutional memory that the next person will not have to rediscover.

Pairing makes the process faster. One engineer drives the reading while another challenges every claim, and the model sits between them as a reference that never grows impatient. The habit tends to reduce surprises during refactors, mainly because unknown risks surface earlier, while the cost is simply a little skepticism and a little time.

Small Early Experiments Build Confidence Before Large Sweeps

Start with one confusing module rather than the whole repository. Ask for a summary of its responsibilities, request a list of hypotheses about its shape, and verify each one against the history. Within an hour you will know whether the model is helping or merely sounding helpful, and you can adjust your prompts accordingly.

As confidence grows, build a small glossary of internal terms, keep a short record of settled findings, and widen the scope gradually to neighboring modules and shared services. Over a few sessions the repository stops feeling hostile and starts feeling legible, which is the real goal of code archaeology.

This article is published by BestRelay, a quality-first API relay that forwards each request to the official model named in it, with no substitution. The service covers Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok and more, and it works with Claude Code, Codex, Gemini CLI and any OpenAI SDK. Billing is pay-as-you-go from the token counts the provider reports, with cache reads and writes priced separately, and members earn a referral commission when people they invite top up. A capable general model such as Claude Opus 5.5 can carry the heavier summarization passes while a smaller model handles routine questions.

Create a BestRelay account when you are ready to try this workflow on your oldest repository.