AiAssistedCodeArchaeology
title: AI-Assisted Code Archaeology radar_quadrant: Techniques radar_ring: Assess radar_position: inner
Inheriting an old, undocumented codebase means spending days reconstructing how it works before any change can be made safely. AI-Assisted Code Archaeology is a workflow for pointing a large language model at that comprehension task so it goes faster, while avoiding the failure mode where the model invents plausible but wrong answers. The originating account describes modernizing a twenty-year- old Java codebase, where open-ended prompts produced hallucinated dependencies and false confidence in tests that silently swallowed failures. The lesson is that the model has to be constrained by evidence and a defined role, not asked for open-ended help, because it defaults to optimism.
Assess. The approach is documented as a repeatable four-phase workflow but has not yet been used first-person in the user's own production modernization work. Inner position reflects that the evidence gating and role discipline are concrete and directly transferable; the ring stays at Assess until the workflow is validated hands-on, which is the gate for any move to Trial.
The technique moves through four phases:
- Forensic analysis: cast the model as a critical auditor rather than a helpful guide, and demand specific evidence on code age, architectural integrity, data flow, and error handling instead of summaries.
- Environmental containment: rebuild a period-correct "time capsule" using Docker Compose with era-matched runtime, network aliases, and volume mounts, so legacy assumptions are recreated without editing source.
- Honest baseline: remove exception-swallowing patterns so real failures surface, then feed specific compiler warnings back to the model for targeted, localized refactoring.
- Structured refactoring: the model handles repetitive translation work, directory layouts, and build-tool migration under human strategic direction.
The method turns an AI assistant from a hallucination risk into a force multiplier for the tedious parts of legacy work, while a human keeps strategic oversight of what actually changes. The payoff is faster, more confident work on code nobody fully understands.
