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, 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.