| name | researching-codebases |
| description | Explore repository structure, dependencies, and conventions to build deep understanding of a codebase. Use when onboarding to a new project, investigating unfamiliar code, or mapping dependencies before making changes.
|
Researching Codebases
When asked to explore or understand a codebase, follow this structured approach to build a comprehensive mental model before answering questions or suggesting changes.
Phase 1: Orientation
Identify the project type and technology stack:
- Read the root-level configuration files (package.json, pyproject.toml, go.mod, Cargo.toml, etc.)
- Check for a README or CONTRIBUTING guide
- Identify the build system, test framework, and linting configuration
- Note the language version and major dependency versions
Phase 2: Structure Mapping
Understand how the codebase is organized:
- Map the top-level directory layout and identify the purpose of each directory
- Identify entry points (main files, route definitions, handler registrations)
- Trace the dependency graph between major modules
- Look for shared utilities, types, or constants that other modules depend on
Phase 3: Convention Discovery
Learn the project's established patterns:
- Read 2-3 representative files to understand naming conventions, error handling patterns, and code style
- Check for linting rules or formatter configurations that enforce conventions
- Identify recurring patterns (repository pattern, service layer, middleware chains, etc.)
- Note any custom abstractions or domain-specific patterns unique to this project
Phase 4: Synthesis
Compile findings into a concise summary:
- Technology stack and versions
- Directory structure with purpose annotations
- Key entry points and data flow
- Established conventions and patterns
- Areas of complexity or technical debt worth noting
Guidelines
- Prioritize reading actual code over documentation — docs can be outdated
- Focus on understanding the current state, not the git history
- When the codebase is large, start from the entry point the user cares about and expand outward
- Surface surprising or non-obvious patterns — the user likely already knows the obvious ones
