Yeda AI Tips · #065

Don't Dump A File Tree And Call It Onboarding

A file tree is not documentation. Dumping folder names teaches your coding agent nothing useful. src/, utils/, services/, handlers/ — every repo on earth has those directories, and none of them says where a request enters, which module owns the money, or which "utils" file is actually the beating heart of the system. A newcomer, human or AI, needs to know what to act on, not just what exists.

Why the raw dump fails

A directory listing is an inventory, not a map. It carries zero information about importance (the 40-line file that everything imports looks identical to the 40-line file nobody has touched since 2023), zero information about flow (nothing says router → middleware → service → repo), and zero information about danger (the one module you must never edit by hand looks like all the others). An agent given only names falls back on statistics: it guesses the most common meaning of each folder name, and every place your repo deviates from that guess becomes a wrong edit. Tools that build serious codebase context agree on this — aider's repo map, for example, deliberately includes "the most important classes and functions along with their types and call signatures," ranked by how often other code references them, precisely because bare filenames aren't enough.

The five moves that are onboarding

Replace the tree dump with five narrated moves. Each one answers a question the tree can't.

#	Move	Answers	Budget
1	Orientation	What is this system, for whom, in one screen?	~10 lines
2	Module map	Which 5–10 modules matter, and what does each own?	1 line per module
3	Core execution path	How does one real request flow, entry to response?	10–20 lines, end to end
4	Gotchas	What will bite an editor who doesn't know the history?	3–5 bullets
5	One next step	Where should the first change usually start?	1–2 lines

The execution path is the move most teams skip and the one worth the most: it turns a pile of names into terrain. "A POST hits routes/orders.py, auth middleware attaches the user, OrderService.create validates and opens a transaction, repo/orders.py writes, the serializer in api/schemas.py shapes the response" — twenty lines like that teach an agent your layering, error handling, and naming in one pass. Now the agent can follow a real request instead of guessing from directory names. That is onboarding.

Where to put it

Write the five moves into the file your agent already loads:

AGENTS.md — the open, tool-agnostic "README for agents"; its own guidance is to include a project overview and anything you'd tell a new teammate, in plain Markdown with no required fields.
CLAUDE.md — loaded at the start of every Claude Code session. The docs' size target is under ~200 lines per file; five disciplined moves fit in well under half of that.

The two compose: a one-line @AGENTS.md import (or a symlink) lets both formats share one source of truth.

Power-user: keep it alive, keep it small

Delete the tree section if you have one. Agents can run ls themselves; the Claude Code docs explicitly say to keep memory files to what the agent can't derive by reading code. Directory layouts are derivable; gotchas and flow are not.
One traced path beats three summarized ones. Depth transfers conventions; breadth just adds names. Add a second trace only if the system genuinely has two disjoint paths (e.g., HTTP and a job queue).
Refresh on lies, not on schedule. The moment a move's description contradicts the code, an agent trusts the doc and edits wrong. Treat a stale gotcha as a P1 doc bug.
Borrow the Diátaxis lens. The five moves are mostly explanation and how-to — the two documentation forms a tree dump contains none of. If your onboarding doc reads like reference (lists of things), you've rebuilt the tree in prose.

Resources

Building an AI feature? Yeda AI designs, audits, and ships production LLM systems.

Talk to us · Read the blog