Today, in the Matching repo, there are two files called README.md with the same modification time: 2026-08-18 04:43:43 for the one at the root, 04:43:24 for the one inside the code folder. Almost a month has gone by without anyone touching them. Next to them, in the same repository, CLAUDE.md has 886 lines and its last edit is from September 10 — twenty-three days after those two READMEs. Three documents in the same repo: two frozen, one alive. The difference isn't chance. It's who reads them.
Why two and not one
The only documented session from that August 18th closed at 04:48 without recording what time it had started. The goal, a single line: "Create the project's README.txt." The original request was actually double —a README "for the general-purpose assistant" and another inside the code folder— though I didn't even get that folder's name right, and along the way it became clear both should be .md, not .txt. The second one replaced Vite's default boilerplate outright, without anything else living alongside it.
What ended up in each one isn't symmetric, it's complementary. The one at the root is a guide for whoever picks up work in the repo, person or assistant: folder structure, agents, skills, backlog rules, the session system, the ticket system. The other is the guide to the product itself: stack (React 19, Vite 8, Supabase), setup, scripts, environment variables, deploy. That same exploration left, along the way, two findings logged to the backlog as out of scope —the outdated stack reference and a duplicated costs folder—, both resolved today.
What aged and what didn't
The code README still says the production deploy "is in blocked status" and that the app shouldn't be assumed to be deployed yet. The real deploy happened on August 22 —it's in the changelog, with a Vercel URL and all— so that file has spent 24 days claiming something that stopped being true the same month it was written. The agent table in the root README didn't hold up either: it lists six, the agents folder has twelve files today, and one of those original six doesn't even live there anymore — the costs one moved up to the user level, outside the repo.
What didn't age is as telling as what did. The root README's two pointers into CLAUDE.md sections still resolve today: the agent routing section and the session-naming convention section are exactly where the README says they are. The folder structure it describes still exists as described. And the claim that there's no .claude/skills/ or .claude/commands/ in the repo —skills are global to the user— is still true. What rotted were the states: a ticket, a file count. What held up were the pointers and the conventions.
That same August 18th, the project's changelog records six product changes: the public landing page, the guided matching assistant, the candidates view, the intro description, the topic search, and the rename of "Materia" to Área across the whole stack. No session documents any of them. The day I wrote how the repo gets documented is, also, the day the least got documented.
What stayed
The convention survived even though the files didn't. The template I use for every new project still ships both as boilerplate: 391 lines for the CLAUDE.md one, 137 for the README.md one. Of the twelve projects I have today, all twelve have a README.md and ten have a CLAUDE.md. The split by audience won; keeping it up to date in every project didn't. Which of your two documents is up to date today, and what does that tell you about who's actually reading it?
Top comments (0)