exploring-a-codebase
Skill0 starsChanged 50 days agoMITView on GitHub
Use when starting work in an unfamiliar repository, when locating code across many files, or when a project's code map or architecture notes look stale.
In this repository20 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- templates/CLAUDE.mdCLAUDE.md
- capturing-decisionsSkill
- choosing-subagent-modelsSkill
- committing-changesSkill
- debugging-systematicallySkill
- delegating-workSkill
- designing-changesSkill
- injecting-dependenciesSkill
- planning-changesSkill
- pruning-testsSkill
- reflecting-on-changesSkill
- resolving-conflictsSkill
- reviewing-codeSkill
- verifying-changesSkill
- writing-commentsSkill
- writing-logsSkill
- writing-project-instructionsSkill
- writing-skillsSkill
- writing-testsSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 71
Before writing a convention into a document others will trust:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Exploring a codebase
Live search is the primary tool. Grep and glob read the code as it is now; every map is a snapshot decaying since it was written. The evidence for repo maps is thin; the well-attested failure is a stale map pointing confidently at code that moved. A map is a hint, never the truth.
Two artifacts, one hard line
Paths are what /vvkit:onboard scaffolds; elsewhere look for an ARCHITECTURE.md, docs/, or a
generated map.
| Artifact | Written by | Trust it for |
A code map — .agents/state/map.xml after onboarding | a generator, never a human | Which types matter and roughly where they are |
Architecture notes — .claude/context/architecture.md after onboarding | a human | Constraints and gotchas no amount of reading reveals |
A hand-written description of the directory tree is a liability: derivable, so duplicated, so it drifts.
Order
- The generated map, if any — cheap, ranked by what is referenced.
- The architecture constraints, if any — layering rules, frozen names, generated files. They are invisible in the file you edit.
- Then search — the map says what matters; grep says where it is used today.
Match the tool to the question
| Situation | Approach |
| One to three lookups, target known | Search directly. A subagent's startup exceeds the task |
| Open-ended sweep across many files or naming conventions | A read-only subagent — see vvkit:delegating-work |
| "Where is X?" and unsure what X is called | A subagent. A missed file costs more than the tokens saved |
| You already know the file | Read it. Do not search first |
| How the codebase already solves this kind of problem | vvkit:architecture-surveyor |
On anything large, locate the section before reading it whole.
History answers "why is this here"
| Question | Command |
| When did this string, flag or symbol appear or disappear? | git log -S'<text>' --oneline |
| How did this function change over time? | git log -L :<function>:<file> |
| Who last touched this line, in what change? | git blame -w -C <file> |
| Which change first broke this? | git bisect run <predicate> |
- Blame names the last toucher, not the author of the logic. A reformat resets it;
-wignores whitespace,-Cfollows code moved between files. - Bisect names the commit that exposed a defect, not always the one that introduced it —
vvkit:debugging-systematically. - A commit message explaining a constraint beats the note that paraphrased it: it is dated and attached to the change that made it true.
When a map or doc contradicts the code
The code wins. Fix the artifact in the same change:
- A wrong generated map: regenerate it, never edit it.
- A wrong architecture note: correct it, and say so in the summary.
Working around a wrong doc silently leaves it wrong for the next reader.
Verify before you assert
Before writing a convention into a document others will trust:
| Claim | Check |
| A library is banned or required | Grep for its import |
| A component has shape X | Compare against the project's scaffold, or the newest examples |
| A marker or prefix convention holds | Grep for it; count occurrences |
| A command builds or tests the project | Run it |
| A target contains a directory | Ask the build system. Never infer target membership from folder layout |
A claim that fails its check gets reported, not written.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.