Codebase Recon Before Coding
A skill for orienting an agent inside an unfamiliar repository — finding the right files, conventions, and contracts before making any change.
Agents fail fast when they edit the wrong file or ignore an existing contract. This skill front-loads the cheap research that prevents expensive mistakes.
Goal
Build an accurate mental model of where things live and how this team writes code before changing anything.
Procedure
-
Map the structure. List the source tree. Identify entry points, config, and where the relevant feature probably lives.
-
Find the contracts. Look for shared types, interfaces, and config that your change must conform to. Read these first and treat them as read-only.
-
Search broadly, then narrow. Use multiple search strategies and naming conventions before concluding something doesn't exist.
# try several spellings rg -i "fetchContent|getContent|loadContent" -
Read the conventions. Check for a CLAUDE.md / AGENTS.md / CONTRIBUTING — they often override your defaults.
-
Confirm the target file(s) before editing.
What to report back
- The exact file paths involved (absolute).
- Any contract the change must satisfy.
- Conventions that differ from your training defaults.
Success criteria
- You can name the files you'll touch and why.
- You've read every contract your change depends on.