Español

Verify Every Claim Against the Code

The README says one thing. The code does another. Trust the code. Every repo you'll ever onboard to comes with a story about itself — a README, an architecture diagram, a wiki page — and every one of those stories was true on the day it was written. The code kept moving; the story didn't. If your onboarding notes are built from the story, they inherit its drift.

Why READMEs drift

Documentation and code live in the same repo but change on different schedules. A refactor moves the business logic out of services/ and into a new module; the pull request touches 40 files and zero paragraphs of prose. Nobody lied — the doc just wasn't in the diff. That's the whole failure mode: docs go stale silently, because nothing breaks when they do. The docs-as-code movement exists precisely to fight this — put docs through the same version control and code review as the code — but even reviewed docs lag, because a reviewer checks the doc that changed, not the docs that should have changed.

So treat every written claim about a codebase — "auth lives in the gateway," "all writes go through the queue" — as a hypothesis, not a fact. Hypotheses are cheap to test when you can read the source.

Trace one real request end to end

Don't try to verify everything at once. Pick one real request — a login, a checkout, a search — and follow it from the entry point, through the business logic, to the data store and back:

1. Find the entry point. Route table, controller, handler registration, CLI arg parser — wherever the outside world first touches the code.
2. Follow the call chain down. Use your editor's Go to Definition and Find All References instead of guessing from file names; names drift just like docs do.
3. Stop at the data store. The query, the table, the write path. Now you've seen where the state actually lives.
4. Walk back up and note the response shape.

That single trace anchors everything else. Once you know one true path through the system, every other claim can be checked against it: does the diagram match the modules you just walked through? Does "the service layer owns validation" match what you saw at step 2? One verified path beats ten inferred ones.

Rules of thumb

The pattern in the table: the closer a claim is to something the machine executes or checks, the less it can drift.

Power-user moves

• Trace history, not just structure. git log -L :funcName:path/to/file shows the evolution of one function across commits — you see when the logic moved and where it went, which is usually the exact moment the README stopped being true.
• Use code navigation on the host, too. GitHub's built-in navigation supports jump-to-definition and find-all-references within a repo, so you can run a lightweight trace during code review without cloning.
• In distributed systems, trace literally. A distributed trace records the actual path of a request across services — it's the runtime version of this tip, and it verifies claims no static reading can (which service really calls which).
• Write notes as paths, not prose. "Login: routes.py:42 → auth/service.py:check() → users table" survives refactors better than paragraphs, because a broken path is visibly broken.

Resources

• Docs as Code — Write the Docs guide
• Code navigation in VS Code — Go to Definition, Find All References
• Navigating code on GitHub — jump to definition and references
• git log -L — trace a line range or function through history
• Traces — OpenTelemetry: the path of a request through your application