Imported from ShailiBoddula/ai-platform (
src/cli-ink/skills/onboarding-to-a-codebase/SKILL.md). Install upstream withnpx skills add ShailiBoddula/ai-platform --skill onboarding-to-a-codebase. Copyright stays with the author.
Onboarding to a codebase
Makes the agent read what the codebase already says about itself before it reads a single line of what it does.
When this fires
- First contact with a repository, component or service.
- A change is wanted in a directory nobody in this thread has opened yet.
- An estimate is being asked for on code that has not been read.
- A fix keeps breaking something in a file that looked unrelated — that is a boundary nobody mapped.
Workflow
Copy this checklist and check items off as you go.
- Step 1: Read the root and component CLAUDE.md files
- Step 2: Read the decision records before the source
- Step 3: Read the tests, then the code they cover
- Step 4: Draw the dependency map and name the boundaries
- Step 5: Write the orientation note and get one claim corrected
Step 1: Read the root and component CLAUDE.md files
Start at the root CLAUDE.md, then the nearest one to the component in hand —
src/cli-ink/CLAUDE.md, src/platform-api/CLAUDE.md and their siblings. Also
read the rules under .claude/rules/. These files say what the maintainers
decided and what they refuse; source code says only what happened. Reading
source first produces a model built from accidents, and the agent then defends
that model against the file that would have corrected it.
Step 2: Read the decision records before the source
Read docs/05-architecture/decisions/ in number order, and the notes in
.dev/decisions/. An ADR carries the alternatives that were rejected, which
is the one thing no amount of source reading recovers. Code that looks
gratuitous usually has an ADR explaining the constraint it satisfies, and
without it the first instinct is to "clean up" the constraint.
Step 3: Read the tests, then the code they cover
Tests are the executable half of the documentation: they name the behaviours someone was willing to defend. Read the test file for a module before the module. Where a behaviour has no test, record that — an untested behaviour is one that can change without anything objecting, and that is exactly where the next surprise comes from.
Step 4: Draw the dependency map and name the boundaries
Produce a map of the components in scope, the direction of every dependency
between them, and — explicitly — the boundaries a change must not cross. Name
them as rules, each with the file that establishes it: which layer may not
import which, which surface an operation belongs to under
.claude/rules/cli-surface.md, which module owns writes to a given table.
Direction matters more than the list. A map with edges and no arrows cannot
tell anyone which side of a boundary they are standing on.
Step 5: Write the orientation note and get one claim corrected
Write the model down: what the component does, what it depends on, the boundaries from Step 4, and the parts still unread. Then state the riskiest claim in it to someone who knows the code and let them correct it. A model that has never been contradicted has not been tested, only rehearsed.
Do not rationalize
| Thought | Reality |
|---|---|
| "Reading the code is faster than reading the docs" | It is faster to the first edit and slower to the first correct edit. The ADR carries the rejected alternatives; nothing in the source does. |
| "The component CLAUDE.md is probably stale" | It is the standing instruction for that directory whether or not it drifted. If it is genuinely wrong, that is a finding to report, not a reason to skip it. |
| "I only need the one file I'm changing" | The file that breaks is the one on the other side of a boundary nobody mapped. That is what Step 4 exists to surface. |
| "I've seen this framework before, so I know the layout" | Framework familiarity predicts file locations, not this repo's boundaries. Rules like .claude/rules/cli-surface.md are local and are not inferable from convention. |
| "The tests are too slow to read through" | Reading them is not running them. The test file is the shortest statement of what the module guarantees. |
| "I can map the dependencies once I start making changes" | By then the map is written by whatever broke, and every wrong turn has already been committed to the working tree. |
Evidence required
A written dependency map naming every boundary that must not be crossed, each
boundary traced to the file that establishes it — a CLAUDE.md, a rule under
.claude/rules/, or a numbered ADR. A boundary asserted without that pointer
is a guess about the architecture.
Alongside it, the list of documents actually read and the list of behaviours found with no test. Both lists are part of the evidence: an orientation that cannot say what it skipped is indistinguishable from one that skipped nothing. Finally, the record of the claim that was put to a maintainer and what came back. "It looks like a standard layout" is not an observation about this repo.
Governance
Enforces the documentation-currency expectation in .claude/rules/documentation.md
and the decision-recording rule in .claude/rules/decisions.md, which is why an
ADR is read as a source of constraints rather than as history. Charter Article
A-4 (Human and Machine, First-Class) is the reason the map is WRITTEN: a model
of the system held only in the current thread is unreadable to the next agent
and to the next reviewer, and it disappears with the context window. Zone is
open: this skill reads and writes nothing but its own note, has no gate, and
blocks nothing. What it produces is the input every other sustain skill assumes
someone already has, so a missing map surfaces later as a change that crossed a
boundary nobody had named.
