An AI agent can land in a codebase it has never seen and find the right file in seconds. It has no map and no memory of the project. It reads almost nothing.
I asked mine how, and the answer was grep, git, and a method of stopping the moment your question is answered.
grepis a search program that has shipped with every Mac and Linux machine for decades. You give it a word, and it prints every line of every file that contains that word. That is the whole tool.git grepis the same idea built into git, searching only the files your project tracks.
These notes are based on Sundae Service, our codebase of a made-up ice cream van business.
The short version
Search the noun, not the verb. Build a map before you read anything. Find the entry point and read top-down. Read the types before the logic. Trace one field from where it's written to where it's read. When the code won't explain itself, ask the history. Stop when your question is answered.
Each line of that gets its own module later in the series, but the
commands are useful from day one, so here they are. Most use git grep,
ordinary grep that only searches the files your project tracks, which is
exactly what keeps node_modules and build output out of your results.
If any look unfamiliar, that's what the modules are for.
| You want to know | Run |
|---|---|
| Where does this feature actually live? | git grep -ci 'loyalty' (high counts mark the centre of gravity) |
| Which files mention it at all? | git grep -li 'loyalty' |
| What renders this exact text on screen? | git grep -F '99 Flake (+ £0.50)' |
| Which files are named after it? | git ls-files | grep -i menu |
| Matches for the word, not every substring | git grep -w 'van' (stops vanilla matching) |
| Enough context to skip opening the file | git grep -n -C 3 'jingle' |
| Who sets this value? | git grep 'soldOutAt =' (write sites are rare and load-bearing) |
| What changed in this area? | git log --oneline -- services/stock/ |
| When did this string appear, and why? | git log -S 'meltAlert' --oneline (then read that commit's PR) |
Seven flags do most of the work, and they mean the same thing in grep,
git grep, and ripgrep: -i ignore case, -l filenames only, -c
count per file, -w whole word, -n line numbers, -F literal string
(regex off), -C 3 three lines of context around each match. Two more
from git log: --oneline for one commit per line, and -S 'x' for
commits that add or remove x.
Learn these once. They'll outlive every editor you ever install.
Each module is sized for a commute, meaning you can read one on the train in the morning and try it at your desk the same day. The full series is below.