Old Code Rewards Patient Questions, Not Instant Answers

Code archaeology begins when the original explanation has disappeared but the software still carries its consequences. An old repository may contain working behavior, partial tests, obsolete comments, and decisions preserved only in naming patterns. AI can help reconstruct that history, but the strongest results come from disciplined investigation rather than instant summarization.

Begin With Repository Shape Before Reading Functions

Start by asking an AI assistant to describe the repository at a structural level. Give it the project’s visible documentation, directory organization, build metadata, test layout, and release notes when available. Ask for a map of major subsystems, likely entry points, external boundaries, and areas that appear abandoned. Do not request a rewrite or a broad quality judgement yet.

The first pass should produce hypotheses, not conclusions. Ask the assistant to separate direct observations from inferences and to identify evidence supporting each inference. This distinction prevents a plausible explanation from quietly becoming an accepted fact.

Build A Time-Aware Map Of The System

Next, examine the repository as a sequence of changing decisions. Feed the assistant small groups of historical records, such as commit messages, release notes, issue discussions, and meaningful diffs. Ask it to identify behavior that was added, removed, renamed, or deliberately preserved. Dates matter because a design that appears strange today may have responded to a constraint that no longer exists.

Have the assistant maintain a compact timeline with four fields: observed change, likely motivation, affected area, and confidence. Low-confidence entries deserve verification before they influence implementation work.

Trace Behavior Across Boundaries And Names

Choose one user-visible behavior and follow it through the repository. Begin at its public entry point, then trace validation, transformation, storage, messaging, and output. Ask the assistant to list every handoff and to note where data changes shape. Repeat the exercise for error paths, because legacy intent often survives more clearly in failure handling than in successful execution.

Names that no longer match behavior deserve special attention. An object called a cache may now act as a durable store, while a method described as temporary may be part of a long-standing contract. Ask the assistant to compare names, callers, tests, and side effects instead of trusting any single label.

Use Tests As Behavioral Evidence Rather Than Authority

Tests are valuable archaeological artifacts, but they are not automatically the complete specification. Ask AI to classify each test as a contract test, regression test, integration check, fixture exercise, or implementation detail. Then compare the tested behavior with production call sites and operational documentation.

Pay close attention to tests that look unusually specific. A strange assertion may encode a customer promise, a compatibility requirement, or a past incident. Before changing it, ask the assistant to propose plausible origins and list the evidence needed to confirm each one.

Make AI Argue Against Its First Explanation

Once the assistant proposes an architectural story, ask for competing explanations. Request the strongest evidence against its preferred interpretation, the missing evidence that would change its mind, and the smallest experiment that could distinguish between hypotheses. This adversarial pass is especially useful around duplicated logic, global state, permission checks, and unusual retry behavior.

Keep humans responsible for conclusions involving security, data loss, compliance, or irreversible migrations. AI can expose relationships quickly, but repository evidence and operational knowledge must settle high-impact decisions.

Record Findings In A Durable Archaeology Ledger

Write down findings while investigating instead of relying on the chat transcript. Each entry should include the behavior under study, supporting evidence, confidence, unresolved questions, and the proposed maintenance consequence. Link each conclusion to a precise repository artifact in the team’s normal documentation system, even though the AI conversation itself is not the source of truth.

A useful ledger gradually becomes a replacement for missing institutional memory. It also gives later reviewers a way to challenge assumptions without repeating the entire investigation.

Choose A Relay That Preserves Model Intent

For teams moving between coding assistants, the transport layer can affect the investigation as much as the prompt. BestRelay is positioned as a quality-first API relay that forwards each request to the official model named in it, without substitution. It covers Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, and additional providers, and it works with Claude Code, Codex, Gemini CLI, and any OpenAI SDK.

Its billing is pay-as-you-go from provider-reported token counts, with cache reads and cache writes priced separately. That accounting is useful for archaeology because repeated context can become the largest cost. Members can also earn a referral commission when invited users top up. A practical trial might use Claude Sonnet 5.5 for broad repository synthesis and reserve a stronger model for disputed architectural questions.

Finish With A Small Verified Maintenance Decision

End the investigation with a narrow action: clarify a misleading name, add a regression test, document a dependency, remove demonstrably dead code, or defer a risky change with evidence. Ask AI to review the proposed action against the archaeology ledger and to identify possible behavior changes.

Readers who want to evaluate this workflow in their own toolchain can create a BestRelay account. The important outcome is not a clever summary of an old repository. It is a defensible understanding that helps the next engineer change the system without erasing the reasons it became this way.