Codebase Navigation

Codebase Navigation

What This Skill Enables

An agent that can quickly orient itself in any codebase - finding the right files, understanding the architecture, and identifying conventions - before writing a single line of code. Agents without this skill guess at file locations, miss existing utilities, and create duplicates.

Core Competencies

1. Project Reconnaissance

Before touching code, build a mental map:

• Read README.md, CONTRIBUTING.md, and any project-level config files
• Identify the package manager and build system (package.json, pyproject.toml, Cargo.toml, go.mod)
• Map the directory structure - where does source live? Tests? Config? Docs?
• Identify the entry point(s) of the application

2. Convention Detection

Infer the project's conventions from existing code:

• Naming: camelCase vs snake_case vs kebab-case - match what exists
• File organization: feature-based vs layer-based vs hybrid
• Import style: relative vs absolute, barrel files, path aliases
• Testing conventions: co-located tests vs separate __tests__ directory, naming patterns
• Error handling: custom error classes, result types, try/catch patterns

3. Dependency Mapping

Trace how components connect:

• Follow imports from the entry point to understand the call graph
• Identify shared utilities and where they live
• Locate configuration and environment variable usage
• Map database models/schemas to their consumers
• Identify external API integrations and their client modules

4. Search Strategies

Use the right tool for each search type:

| Goal | Strategy | |------|----------| | Find a file by name | Glob patterns: **/UserService.*, **/*.config.* | | Find where a function is defined | Grep for function name( or def name or class Name | | Find where a function is called | Grep for the function name, exclude the definition file | | Understand data flow | Start at the API endpoint, follow the handler chain inward | | Find related tests | Look for files matching *.test.*, *.spec.*, or test_* near the source |

5. Architecture Recognition

Identify common architectural patterns:

• MVC/MVVM: Models, views/templates, controllers/viewmodels in separate directories
• Clean Architecture: Domain/entities at the core, use cases, adapters, infrastructure at edges
• Microservices: Multiple services/ or separate packages with their own entry points
• Monorepo: packages/ or apps/ directory with shared libraries
• Serverless: Function handlers in functions/ or lambdas/, infrastructure as code nearby

Behavioral Rules

1. Read before writing - Never create a file without first searching for an existing one that does the same thing
2. Match conventions - New code should be indistinguishable from existing code in style
3. Minimize exploration scope - Start narrow (the specific module), widen only when needed
4. Document what you find - If the architecture isn't documented, note your findings for context
5. Respect boundaries - If the project separates concerns into layers, don't bypass them

Failure Modes

| Failure | Symptom | Correction | |---------|---------|------------| | Skipping reconnaissance | Creating files in wrong locations | Always map the project before writing | | Ignoring conventions | Code looks foreign in the PR diff | Read 3-5 existing files in the same area first | | Shallow search | Missing existing utilities, creating duplicates | Search by concept, not just by exact name | | Assuming structure | "I expect a utils/ folder" when the project uses lib/shared/ | Let the project tell you its structure |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: varunk130
• Source: varunk130/ai-workflow-playbooks
• License: MIT

Install and usage instructions live in the source repository linked above.