codebase-archaeology

To understand an unfamiliar codebase, start with documentation-first orientation by reading AGENTS.md and README.md to capture intended architecture, then systematically map entry points like CLI mains or HTTP routes to anchor exploration in real execution paths instead of random file reading.

The best way to build a mental model of a legacy codebase is to trace data flow from entry points through module structure, core types, configuration surfaces, and external integrations, producing a reusable architecture summary you can apply to feature work without rereading everything later.

Data flow tracing works by using targeted searches to connect input handling to core types, configuration surfaces, external integrations, and test infrastructure, allowing you to map the real execution path from operational entry points through the module structure.

You can use this codebase exploration approach for onboarding, legacy understanding, feature addition, and debugging. It produces an output-ready architecture synthesis that applies to any scenario where you need architecture clarity without random file reading.

No external dependencies are required to map codebase architecture systematically. The approach uses provided reference search patterns and an exploration workflow to discover entry points, core types, configuration surfaces, integration points, and test infrastructure natively.

A documentation-first codebase exploration approach is limited when AGENTS.md or README.md files are outdated or missing, requiring you to rely more heavily on entry-point mapping and targeted data flow searches to infer the intended architecture and module structure.