Agents move into my repos every day and work like locals. It takes less than 200 lines of markdown to do it.
Codex. OpenCode. Kilo. Claude Code. Each parachutes into repositories like a Doctors Without Borders team into warzones. They’ll put it more diplomatically:
I build my repo shape from syntax and conventions first, architecture second. ls, rg over likely feature nouns, framework entrypoints, repeated local file reads until a mental map emerges. That gives me a usable skeleton — build surface, runtime entrypoints, transport files, feature files. But it’s syntactic before it’s architectural. I know where code seems to live, but not yet what is authoritative, what is display-only, what mutates what, where true state lives, or which neighboring components are real blast radius.
The numbers on this are ugly, but I’ll add one: 97k tokens on context for a weekend project repo when handled the standard way.
Code isn’t a repo list. It’s a community of functions, components, and libraries. Treat it like one.
Start a set of small markdown files, one per architectural neighborhood, with structured frontmatter called SAMOPS. Each file is about 40 lines. Each one maps a node in the graph: state, authority, mutation, observability, persistence, staleness. Linked neighbors collapse the working surface from repository-wide to task-sized without losing scale or scope.
Agents already know where your files are. They don’t know that power_menu observes the IPC bus, that module-host owns widget placement but not module data, that the config writeback path triggers a file watcher that triggers a rebuild. That’s locality.
No retrieval engine. No embeddings. No daemon. The agent reads these before it opens source, and arrives knowing the graph — not just the directory.
Here’s the agent’s own evaluation of what that changed, from its first session on a codebase it had never seen:
| What | Why It Mattered |
|---|---|
| SAMOPS frontmatter gave me a dependency graph before reading any source | I knew power_menu observed ipc-bus and mutated bar visibility — the exact pattern I needed, before opening a single .rs file |
| Staleness_risks as a first-class field | A known reload gap in module-host was documented. I designed around it instead of discovering it |
| Scope of Touch (safe/risky) | Knew GTK thread handoff was a risky edit zone. Stayed on the safe side by reusing the existing pattern exactly as-is |
| Each doc is ~40 lines | I read all 13 in two parallel tool calls. A 500-line architecture doc would have burned the same context but been harder to navigate |
| Authority notes separated “owns” from “displays” | Told me toggle_menu should manipulate config (the authority), not widgets directly |
| Links between docs are bidirectional | When I was in ipc-bus.md, I could see every node that consumes IPC. Didn’t have to grep for subscribers |
Zero to two compiling features in one session. Zero wrong architectural turns.
I used to keep graph-ruled index cards by component — UI on front, state contract on back, binder-clipped by route group. Spread them on the table and you’re looking at the whole app. Traverse notes are the same shape: small, self-contained, replaceable, readable in parallel.
There’s no server. No vector index. No package. It’s markdown files in your repo that any agent can read. Most teams should try 200 lines of structured locality before they reach for infrastructure.
The agent that wrote that table had never seen the codebase. It didn’t need a memory product, just a map of what touches what.