Your old project knows more than its documentation does.
Engineering With AI Archaeology examines the code, tests, configuration, history and human context you already have. It drafts missing documentation and findings for you to review, so people and AI can continue with a clearer account of the system.
The dangerous part isn’t old code. It’s missing context.
A new engineer can ask why. A coding agent can only work from what it can see.
On an inherited project, the important knowledge is often scattered across code, half-finished documentation, tests, tickets, commit history and the people who kept it running. If you point AI at the repository without rebuilding that context, it can confidently preserve a workaround, miss a trust boundary or “fix” behaviour somebody still depends on.
Archaeology gives the project a proper introduction. It separates what the repository proves from what the owner says should be true, records the gaps between them, and prepares a reviewed foundation for AI-assisted engineering.
Find out what the previous team never wrote down.
Take an old customer export. The owner says it must exclude private support notes. The code and the tests need to tell the same story.
Illustrative investigation · not a finding from a customer project
- The owner’s account
- “Customers can download their own records. Internal notes must stay private.” This establishes the intended boundary, not proof that it works.
- The repository evidence
- The export uses an organisation-scoped query. Its test covers a successful administrator download, but doesn’t demonstrate what happens to private notes.
- The finding to review
- Organisation filtering has supporting evidence. Private-note exclusion remains unproven. Record the source locations and the missing scenario instead of describing the export as safe.
- The next piece of work
- Ask the owner to confirm the rule, inspect the serializer and add a separate intent for any change or test coverage needed. Discovery itself isn’t permission to rewrite the export.
The useful output is more than documentation: it’s a source-linked explanation of what you can rely on, what needs checking and why.
Keep the trail from code to conclusion.
This is Archaeology inside the current harness. The source map records the entry points and relationships the repository supports, while keeping the questions that still need a person to answer in plain sight.
From “be careful” to useful working context.
Before Archaeology
The repository is treated as the whole truth, even when it contains temporary fixes, abandoned experiments and behaviour nobody intended to preserve.
- Purpose lives in people’s heads.
- Architecture is inferred from whichever files were opened first.
- Constraints and non-goals are easy to miss.
- Every AI session rebuilds a different version of the project.
Ready for assisted engineering
People and AI can inspect the same reviewed account of the system, including where the evidence is incomplete or disagrees with intended behaviour.
- Purpose, users and important journeys are explicit.
- Repositories, components, data and integrations are mapped.
- Standards, risks and operating responsibilities have owners.
- Future work starts from durable project knowledge.
What Archaeology actually reconstructs.
It doesn’t generate a giant generic README and call the project understood. It builds a source-linked picture of the areas people and AI need in order to make responsible changes.
Purpose, users and real behaviour
Why the system exists, who relies on it, the journeys that matter, known exceptions, and the places where current behaviour conflicts with the owner’s intent.
Architecture and topology
Repositories, deployable units, entry points, dependencies, integrations, queues, data stores and recurring implementation patterns.
Data and domain language
Important entities, relationships, movement, ownership, classification questions and terms the team uses in practice.
Delivery and quality
Tests, release routes, evidence, standards, technical debt, analysis failures and the boundaries that make a safe change reviewable.
Security and operations
Trust boundaries, identity, failure paths, hosting, observability, recovery and the operational knowledge code alone can’t confirm.
Decisions, contradictions and honest unknowns
What’s supported by evidence, what remains partial or missing, where sources conflict, and which questions need a named person before the work can safely move on.
A route from inherited code to reviewed project knowledge.
Brief
The owner explains the purpose, users, important outcomes, known problems and what mustn’t be inferred.
Map
The Source Map inventories the repository and keeps unsupported, sensitive, oversized and failed analysis visible.
Investigate
Bounded passes examine product, architecture, data, security, delivery, governance and operations.
Review
A named person accepts, corrects, rejects or defers findings. An AI persona can challenge; it can’t approve.
Continue
Reviewed knowledge enters the project’s SPECS. Separate, bounded intents describe what should change next.
It won’t pretend every answer is in the code.
Repository behaviour is strong evidence of what exists. It isn’t automatic authority for what should continue.
Every material finding keeps its status visible, so the awkward questions aren’t polished out of the story before a human sees them.
Don’t start the next AI session from zero.
Give the project a reviewed memory first. Then use the same harness to turn what you’ve learned into clear intent, proportionate plans, human approval gates, evidence and delivery that can survive the next conversation.