Read the docs before the code

T3 Code has about 32,000 tracked files and about 129,000 words of Markdown across its README, its agent guide, and its docs/ folder. You cannot read the code to learn the shape of a repo that size. You read the guidance the maintainers wrote for newcomers, and you use it as a map to the code.

This chapter shows you what T3 Code’s guidance contains, in what order to read it, and how to tell when a doc has gone stale. On a solo project the map lives in your head. On a team project, and on any project you hand to an agent, the map has to live in files.

Start with the file written for the newcomer

Most repos have a README.md aimed at users. T3 Code also has AGENTS.md, a 213-line guide aimed at whoever is about to change the code. The file names its reader directly. In its glossary, “you” means “the agent reading this file and changing T3 Code”. The maintainers expect most changes to come from agents, so they write the onboarding doc for an agent. A human newcomer gets the same benefit.

The file opens with four product pillars, under the heading “What makes T3 Code special?” They are open at the core, performance without compromise, remote ready, and multi-surface. Each pillar is a constraint you will meet in the code. “Multi-surface” says a feature has to work on web, desktop, and mobile. “Remote ready” says it has to work when the client and the server are on different machines. When you later wonder why a small change touches six packages, the pillars are the reason.

Next comes a note signed by Theo Browne, one of the two maintainers the file names:

I like ambitious ideas, simple systems, and software that feels obvious. Do not preserve complexity just because it already exists. Do not introduce machinery because it looks architecturally impressive. Understand the real constraint, then fight for the smallest model that makes the correct behavior unsurprising.

Channel both "measure twice, cut once" and "yagni". Fight scope creep. Try to honor the dev's intent in both a minimal and realistic fashion.

This is taste, not a rule. It tells you how a reviewer will judge your change. A pull request that adds a new abstraction “for later” will meet this paragraph.

A glossary that fixes the words

The file then defines eleven words: you, we, user, agent, provider, client, environment, project, thread, turn, and T3 home. Some look obvious. They are not. “Environment” means one running T3 server plus the machine, files, and credentials it owns. A “client” is the UI. When the code says environmentId, it means a server, not a deployment stage like “staging”. Learn these eleven words before you read a type name, because the type names use them. This book’s own glossary carries the same terms.

A second, longer glossary lives in docs/internals/glossary.md. It adds orchestration words such as command, event, projection, and outbox effect. Its opening sentence keeps it narrow. It says “Architecture and lifecycle constraints belong in the overview, not in these definitions.”

Three ways to hurt yourself

The section most worth copying is a short numbered list:

1. **Killing by pattern.** Never `pkill -f`, `pgrep | kill`, or `kill` a PID you found by matching a name, path, or worktree string. Your own agent process has this worktree's path in its argv, and this machine runs several other dev servers at once. Kill only a PID you captured at spawn, or the owner of your port from `ss -H -ltnp` after confirming `/proc/<pid>/cwd` is your worktree.
2. **Writing to the live install.** `~/.t3/userdata` is the developer's real T3 Code database, in use while you work. Reading it and copying from it are fine, and a good way to get real test data (see Test data). Never start a server against it, never open it read-write, never clean it up.
3. **Baking in origins.** Never set `VITE_HTTP_URL` or `VITE_WS_URL` for dev. Dev is single-origin and Vite proxies `/api`, `/ws`, `/oauth`, and `/.well-known`. Setting them bakes localhost into the bundle and silently breaks every remote browser.

Each item names the action, says why it hurts, and gives the safe alternative. None of them is about code style. They are about the developer’s machine. T3 Code is developed from inside T3 Code, so an agent that runs pkill -f node can kill the very app that is running it. A new contributor would not guess that. That is why it sits near the top of the file and not in a wiki.

CLAUDE.md is one line

CLAUDE.md contains a single import:

@AGENTS.md

Claude Code reads CLAUDE.md, and most other agents read AGENTS.md. One import keeps a single source. The history shows they tried a symlink first. Theo’s first commit of the guide added a symlink, and several later PRs fixed it. PR #7171 replaced it with the @AGENTS.md import.

Read the docs tree by audience

docs/README.md is the index. It has two halves, “Using T3 Code” and “Working on T3 Code”. The folders follow the same split:

The split is recent and deliberate. In PR #4807, Theo restructured the docs “by audience” after an audit found “109 stale, wrong, or broken claims”. One of them was a release step labeled “dry-run” that really published to npm.

What each folder is for

AGENTS.md states what belongs in each folder:

Most code changes do not need an internal documentation change. Agents can read the code.

- `docs/internals/` is for architectural decisions and their reasons, constraints that span components, and implementation traps that are hard to discover from the source. Before adding a paragraph, ask what a maintainer would get wrong without it. If reading the relevant code answers the question, leave it out.
- Do not document every feature, enumerate fields or methods, narrate control flow, maintain file catalogs, or append PR summaries. Types, tests, and code already record the implementation. The glossary defines shared vocabulary; it is not a feature index.
- A local reason the code can't show goes in a short nearby code comment. Use an internal doc when the reasoning crosses boundaries or needs context the code cannot carry well. Link to the relevant source instead of copying it.
- When a documented decision or constraint changes, rewrite or remove the affected text. Do not append another account of the new behavior. A new internal page needs a distinct, durable reason to exist.

This changes how you read internals/. A page there does not describe how the code works. It describes what you would get wrong. overview.md is a good example. It says a command acknowledgement “means the intent committed, not that the provider, checkpoint, or other follow-up work finished”. You could read the orchestrator for an hour and still miss that. With one sentence in your head, the code makes sense.

Julius Marminge’s PR #9755 applied these rules and shrank internal Markdown “from 24,160 to 7,842 words”. At the pinned commit, internals/ is back to about 29,000 words over 32 files. The rule held, but the folder grew again as features landed. Treat the size of a docs folder as something that drifts, like code.

The design folder is different

docs/orchestration-v2/README.md says what it is in its first line:

This document set describes the target architecture for the next orchestration model. It is not a patch plan for the current implementation and it intentionally ignores migration/backward compatibility. Those concerns should be handled after the target model is coherent.

So these nine files describe a target, not the code as it is. They are still updated. The latest edit at the pinned commit is from 11 November 2026. Read them when you work on orchestration. When one of them disagrees with the code, the code wins, and the doc tells you where the code is heading.

A reading order for a repo this size

All the Markdown in the repo comes to about 129,000 words. You do not need most of it on day one. This order gets you oriented with about 6% of it:

1. README.md, 650 words. It says what the product is, which providers it supports, and that you need the vp command to build it.
2. AGENTS.md, about 3,900 words. Read every section. The “How it works” and “Where code lives” sections near the end are a one-paragraph architecture and a folder map.
3. CONTRIBUTING.md, about 860 words. It tells you the team accepts bug fixes from outside contributors and closes new features. It also caps each person at 3 open PRs. Read it before you plan any work.
4. docs/internals/overview.md, about 1,200 words. It names who owns what and links to the main source files.
5. docs/internals/glossary.md, about 760 words. Keep it open in a tab.
6. The “First checkout” and “Checks” sections of docs/operations/development.md. Run what they say.
7. One internals page for the area you will change. For server code, that is effect-services.md, which AGENTS.md tells you to read “before adding server code”. For a provider, it is providers.md and adding-a-provider.md.
8. Now open code, and start from a link in a doc. overview.md links straight to Orchestrator.ts, EventSink.ts, and EffectWorker.ts. Read those three files with the “Durable intent and side effects” section beside them.

Steps 1 to 5 come to about 7,400 words, or about 30 minutes at a typical reading pace. Steps 6 to 8 depend on your task.

Use the one-paragraph architecture as a map

The “How it works” paragraph in AGENTS.md is the densest thing in the repo:

Clients send typed WebSocket requests. The server turns them into _commands_. The _orchestrator_ (`apps/server/src/orchestration-v2/Orchestrator.ts`) serializes commands and decides _events_ without doing any I/O. The _event sink_ commits those events, the _projections_ the UI reads, the _command receipt_, and _outbox_ effects in one transaction. The _effect worker_ then runs the effects, such as starting a provider turn or capturing a checkpoint, and feeds results back as commands. Provider CLIs run as subprocesses; per-provider _adapters_ translate their native protocols into orchestration events. Each turn ends with a _checkpoint_, a hidden git ref, so the app can diff and restore.

Every italic word is a glossary term and a folder or file name. Draw it as boxes and arrows on paper before you open the code. When you get lost in a 1,000-line file, find your place on the drawing.

Read a skill to learn how they test

T3 Code also keeps agent skills in .agents/skills. .claude/skills is a symlink to the same folder. There are three skills: test-t3-app, test-t3-mobile, and contribution-triage. A skill is a how-to written for an agent, and it is the most exact description in the repo of how the maintainers check their own work. Read test-t3-app/SKILL.md before your first UI change.

Check the docs against the code

Docs are a map, and maps go out of date. T3 Code’s first AGENTS.md, from 9 February 2026, called the product “CodeThing”. It described an apps/renderer folder and “Shared Zod schemas” in packages/contracts. None of that is true at the pinned commit. The renderer became apps/web, and the contracts use Effect’s Schema. The maintainers rewrote the file instead of patching it, which is what their own rule says to do.

You can run three quick checks on any doc before you trust it:

# When was this doc last changed, and by what?
git log -3 --format='%h %ad %s' --date=short -- docs/internals/overview.md

# When was the code it describes last changed?
git log -3 --format='%h %ad %s' --date=short -- apps/server/src/orchestration-v2/

# Do the paths it links still exist?
git ls-files apps/server/src/orchestration-v2/EventSink.ts

If the code changed a lot since the doc did, read the doc for the why and the code for the what. T3 Code makes the third check easy, because its internals pages link to source files by relative path. A link that no longer resolves shows you which paragraph to doubt.

How your projects compare

fud

fud has the closest setup to T3 Code. Its AGENTS.md lists the commands, the security rules, and the voice. Its CLAUDE.md is the same one-line @AGENTS.md import. Git stores it as the same blob as T3 Code’s.

CONTEXT.md is fud’s glossary, and in one way it is stricter than T3 Code’s:

**Owner**:
The signed-in person who owns one private fud record, identified by the subject of a verified WorkOS token. The web app uses a session token; MCP uses a Connect user access token with the MCP resource audience. Neither token is accepted at the other's entry point. Each Owner's records, Payees, Gmail connection and Alerts are separate. A request never chooses its Owner through parameters.
_Avoid_: customer, tenant, account holder, member

Seven terms carry an _Avoid_ line that lists the synonyms you must not use. T3 Code’s glossary says which word to use but not which words to drop. If you have ever found user, account, and owner all meaning one thing in your code, you know why the avoid list helps.

fud also has a drift problem that T3 Code’s rules are meant to catch. PRODUCT.md still says “Data arrives live through Convex. A new payment appears without a reload.” Line 42 says real Owner data “lives only in Convex”. But fud now stores data in Cloudflare D1. package.json has a migrate:convex import script and a db:local D1 migration script. CONTEXT.md says “Live UI updates are deferred; Refresh reads new results.” The git log shows PRODUCT.md last changed on 13 October 2026, and the D1 snapshot commit landed on 28 October. An agent that reads PRODUCT.md first will reach for Convex.

antre

antre’s README is good orientation. It names each route, says which service owns what, and warns about a real trap:

Use the same Convex deployment for the web server's `CONVEX_URL` and `CONVEX_DEPLOYMENT`. The old local setup pointed the web server at production while the Convex CLI used development. Check both before testing writes.

That is a “way to hurt yourself” in T3 Code’s sense. It names an action, says why it hurts, and says what to check. It is buried in a setup paragraph, though, and antre has no AGENTS.md. An agent will read the README only if something tells it to.

antre also keeps plans in the repo. docs/plans/implementation-contract.md is a precise contract for the public-workspace release. T3 Code’s AGENTS.md says “Do not commit implementation plans” and treats the merged PR as the record. For a solo repo with no PR review, a committed plan is a fair choice. Mark it as dated, though, or delete it once the work lands, so nobody reads it as current.

monosodiums

monosodiums’ README has a “Layout” section that does what T3 Code’s “How it works” paragraph does. It explains the createX(world) and animateX(frame) pattern in four sentences. That is the right size for a single-app project. PRODUCT.md and DESIGN.md cover audience and visual rules. What is missing is any “ways to hurt yourself” list. For example, the README says a push to master deploys automatically, which an agent should know before it pushes.

When the T3 Code approach is overkill

T3 Code needs four doc folders because its history has 985 commit authors, and its users read different docs from its maintainers. A solo project with one app needs one README, one AGENTS.md, and a term list. Copy the habits, not the folder count: a glossary, a short hazard list, and a rule that you rewrite a doc when the decision changes.

Try it

1. Fix the drift in fud. Open fud/PRODUCT.md and rewrite lines 24 and 42 to match how data flows now. Use CONTEXT.md and wrangler.jsonc as the source of truth. Rewrite the lines, as T3 Code’s rule says, instead of adding a note below them. To check it worked, run grep -rn Convex PRODUCT.md DESIGN.md CONTEXT.md AGENTS.md. The only hits left should describe the migration, if any.
2. Give antre an agent guide. Create antre/AGENTS.md with four short sections: what antre is (two sentences), the commands from the README, a glossary of five to ten terms (workspace, channel, post, agent grant, and so on, taken from docs/plans/implementation-contract.md), and a “ways to hurt yourself” list. Move the CONVEX_URL warning there as item one. Add CLAUDE.md with the single line @AGENTS.md. To check it, start a fresh agent session in antre, ask “How do I run antre locally, and what must I check before testing writes?”, and see whether it answers from the new file.
3. Add a hazard list to monosodiums. Add a section to monosodiums/README.md titled “Before you push” with each action that has side effects. Start with the automatic deploy from master and the npm run deploy command. For each item, name the action, the effect, and the safe alternative. To check it, ask a fresh agent to “make a small copy change and ship it” and see whether it stops to ask before pushing to master.