Codebase Archaeology — Codex Native

Purpose

Build a practical mental model of an unfamiliar codebase without reading files randomly. Start with project guidance and documentation, then trace from entry points through domain logic, storage, integrations, configuration, and tests.

Use this skill for onboarding to a new repository, answering “what does this project do?”, understanding legacy or inherited code, mapping architecture before a migration/refactor/feature, tracing a bug or feature path, and creating a reusable technical architecture summary.

Core Rule

Documentation first, then data flow.

Before reading source, inspect the project-level context that Codex should already respect:

cat AGENTS.md README.md 2>/dev/null | head -200
find . -maxdepth 2 \( -name 'AGENTS.md' -o -name 'README*' -o -name 'CONTRIBUTING*' -o -name 'docs' \) -print