# My Project Docs Aren't For Humans Anymore. They're For an Agent That Re-Reads Them Every Session. > Source: > Published: 2026-07-15 03:35:48+00:00 I used to write `docs/` the way I was taught: prose paragraphs, a little context, a "why we did this" narrative you'd hand to a new hire. Then I noticed something. The only reader opening those files every single day wasn't a human. It was an agent, loading them fresh at the start of every session, with a token budget and zero memory of yesterday. That changes what "good documentation" means, and I didn't actually update my writing style until a stale line in one of these files caused a real bug. In my `my-git-manager` repo, `CLAUDE.md` points an agent at `docs/project_notes/` on every session start: ``` ## Project Memory System Institutional knowledge lives in `docs/project_notes/`. Check before proposing changes. - **bugs.md** — known bugs and solutions - **decisions.md** — why things were built the way they were (ADRs) - **key_facts.md** — usernames, API endpoints, file purposes, run commands - **issues.md** — work log **Protocols:** - Encountering an error → search `bugs.md` first - Proposing an architecture change → check `decisions.md` for conflicts - Need a username/endpoint/command → check `key_facts.md` - Completing a phase of work → log it in `issues.md` ``` That "Protocols" block isn't documentation about documentation. It's routing logic. It's the same shape as an `if/else` — "on event X, read file Y" — except the interpreter is an LLM instead of a runtime. I didn't design it that way on purpose at first; I just kept trimming prose paragraphs down until what was left looked like this. A human skims. They pick up "roughly what this means" from surrounding words even if a sentence is slightly out of date, because they're pattern-matching against a mental model they already have. An agent doesn't have that mental model. It takes what's on the page close to literally, weights it as fact, and acts on it — in the same turn, with no time to notice the prose "feels off." I found this out the hard way. `key_facts.md` had this line for weeks: ``` - Token scopes needed: `repo`, `user` ``` It read fine. Nothing about it looked wrong to a human skimming it. But on 2026-06-23, a real OSS fork-and-PR task needed the `workflow` scope too (pushing a branch that touches `.github/workflows/*.yml` requires it), and `bugs.md` got an entry documenting the failure — but nobody went back and fixed the *summary* line in `key_facts.md` that an agent actually reads at session start. Six weeks later, an agent trusted that stale line, tried a similar push, and hit the same 403 again. The fix existed in the codebase. It just wasn't in the file the agent was actually going to open. ``` - Token scopes needed: `repo`, `user` — add `delete_repo` if repo deletion via API is required, add `workflow` if you'll ever push a branch that pulls in upstream `.github/workflows/*.yml` changes (fork OSS contributions) — see `bugs.md` 2026-06-23 ``` The lesson wasn't "add a workflow scope." It was: a summary fact file is a cache, and caches go stale silently unless something forces them to stay in sync with the detailed record. A human would have said "eh, probably still `repo, user` , let me just try it." An agent read `key_facts.md` , saw a confident bulleted fact, and acted on it as ground truth. There's no skepticism pass unless you build one in. **Terse beats narrative.** Every sentence I don't write is a sentence the agent doesn't have to hold in its context window before deciding what to do next. `key_facts.md` is a table and a bullet list, not paragraphs. If I catch myself writing "this is because..." I ask whether the *because* actually changes the agent's next action. If it doesn't, it's a comment for a future human reading the file in a browser, not something the agent needs — and I'll cut it or push it into `decisions.md` where it belongs. **Facts and rationale live in different files, on purpose.** `key_facts.md` is current-state-only: what's true right now, no history. `decisions.md` is append-only ADR entries: why something was built the way it was, including the paths not taken. `bugs.md` is incident-shaped: symptom, root cause, fix. I stopped trying to write one file that does all three, because an agent searching for "why does X work this way" and an agent searching for "what's the current DEV.to username" have completely different queries, and mixing them means both searches wade through irrelevant prose. **Every fact carries its own expiry trigger.** The `workflow` scope fix above now has `— see bugs.md 2026-06-23` attached directly to the fact, not just in a changelog somewhere. If it goes stale again, the next agent has a breadcrumb to the incident that produced it, one hop away, without me having to remember to update two files by hand. **The protocol block is the actual interface.** I stopped thinking of the "when X, check Y" list as a nicety at the top of the doc and started treating it as the load-bearing part. It's what turns four static markdown files into something closer to a lookup table the agent consults *before* acting instead of narrating context it happened to skim. I now ask one question before adding anything to `docs/project_notes/` : if an agent reads only this line, out of context, with no chance to ask a follow-up, does it have enough to act correctly? If the answer is "well, it depends, you'd need to know that..." — that dependency needs to be in the line itself, or the line is a liability waiting for the six-week gap between "we fixed it" and "we told the file we fixed it." Writing for a reader that takes you completely literally and never gets to ask "wait, is this still true?" is a different discipline than writing for a colleague. It's closer to writing an API contract than a wiki page. I didn't expect that to be the actual shift "AI-assisted development" would force on my documentation habits, but it's the one that's caught real bugs so far.