I kept running into the same two problems with coding agents. First, a long conversation gets expensive: most agent tools resend the whole conversation on every turn, so cost grows with length, not with how much new work is happening. Second, it gets lossy: past a certain length the agent starts summarizing or forgetting earlier detail. Neither problem is really about the agent being bad. It’s about treating the conversation as the place where work state lives.
The fix I landed on borrows from Getting Things Done: capture things as they happen, give every item exactly one home, and review on a schedule. Applied to agent projects, that turns into a small set of docs that the agent reads at the start of a session instead of scrolling back through chat history.
The conversation is disposable, the docs are not
The rule I try to hold myself to: a new session, or one right after clearing the conversation, should know everything it needs from the docs alone. If it doesn’t, something didn’t get written down.
That means every project gets a docs/status.md, read first in any session, plus docs/decisions.md and, once something gets deferred, docs/backlog.md. When a task or milestone wraps up, the move is to save state into those docs and start a fresh conversation rather than keep piling onto the old one. A short session that starts by reading status.md ends up sharper and cheaper than a long one that’s dragging five finished tasks behind it.
CLAUDE.md is a router, not a library
Every project has a CLAUDE.md that gets loaded automatically into every session touching that folder. That’s exactly why it has to stay small, something under about a thousand words. It should hold only:
- a two-line summary of what the project is
- the hard rules that must never get skipped
- the workflow as numbered steps, starting with “read
docs/status.md“ - a table pointing to the other docs: file, what it holds, when to read it
Everything else moves out into the files that table points to. The key trick is pointers instead of imports: “read docs/deploy.md before deploying” instead of a mechanism that pastes the whole file into context whether or not the current task needs it. One fact lives in exactly one doc. If two docs say the same thing, they’ll eventually say it differently, and now the agent has to guess which one is current.
Size limits keep this honest: a paragraph that’s grown past about a hundred words gets tightened or turned into a list, a section past about four hundred words gets its own file with a one-line pointer left behind, and a doc over its limit gets split by topic. None of this is precious. When you move text out, you copy it, then compare word counts before and after so nothing quietly goes missing.
When several agents share one project
The same structure holds up once a project has more than one agent working in it, say two agents each owning a different part of the codebase, each in its own subfolder. All the docs still live in one place, the project’s docs/ folder, just with one subfolder per agent, named after that agent’s work folder:
project/
├── CLAUDE.md project router; its table lists every agent's docs folder
├── docs/
│ ├── status.md cross-agent work: who waits on whom
│ ├── decisions.md decisions for the whole project
│ └── partA/ the partA agent's status.md, decisions.md, backlog.md, topic docs
└── partA/
├── CLAUDE.md small router for partA; the project one loads too
└── docs -> ../docs/partAPlaintextThe agent’s own folder links back to its slice with a relative symlink, docs -> ../docs/partA. From inside its own folder the agent still just reads and writes docs/status.md like normal, so /wrap and /docs-review need no changes at all.
That gives two levels instead of one. Anything that spans agents, who’s waiting on whom across parts, or a decision that affects the whole project, goes in the project-level docs/status.md or docs/decisions.md. Anything that’s purely one agent’s own business goes in that agent’s own subfolder. An agent only ever writes inside its own docs folder; if it needs to tell another agent something, that goes through an append file in the other agent’s folder, or a direct message, never a write into someone else’s part.
A few things worth knowing before setting this up:
- The symlink has to be relative, never absolute. An absolute path breaks the moment the project moves, or gets restored from a backup to a different location.
- Writing through a symlink that points outside the agent’s own folder can trip a permission prompt, since the actual target directory sits elsewhere. The fix is adding that target path to the agent’s own
additionalDirectoriespermission setting. - If the project folder sits inside a cloud-synced drive, check that the symlink actually survives the sync. Some sync providers don’t handle symlinks cleanly.
- Search tools sometimes skip symlinked folders entirely, so if a search inside an agent’s own folder seems to be missing results, try searching the real path on the other side of the link directly.
Capture, one home per item, and a weekly review
This is the part that maps onto GTD most directly.
Capture. Whatever happens during a session that matters later, an instruction to follow going forward, a decision that got settled, a bug’s actual root cause, gets written down as a short dated line, not pasted in as raw conversation. If a doc fix takes a minute, it happens right then. If a note isn’t ready to merge yet, maybe the finding is still half-confirmed, or another part of the project owns that doc, it goes into an inbox file named after the doc with today’s date, and gets listed under Waiting for in status.md until someone merges it.
One home for each item. Every captured thing has exactly one place it belongs:
| What you captured | Where it goes |
|---|---|
| A fact, lesson, or how-to | the topic doc it belongs to |
| A decision that got settled | decisions.md |
| The next concrete action | Now, in status.md |
| Something waiting on another person or agent | Waiting for, in status.md |
| A question only a person can answer | Questions, in status.md |
| An idea with no date attached | backlog.md |
| Something no longer useful | deleted |
status.md gets fully overwritten at each milestone, not appended to, and stays under roughly three hundred words: today’s date, then Now, Done this session, Waiting for (who, what, and since when), and Questions. decisions.md is one dated line per decision with the reason attached, so nobody reopens a settled argument without noticing it was already settled. backlog.md never gets overwritten, only added to, promoted from, or trimmed when something’s genuinely dead.
Review. Closing out a session has its own short routine: go through what happened, give each item its one home, add any decisions and backlog items, and overwrite status.md. That’s the GTD-style capture step, just run at the end of a work session instead of at the end of a day.
The weekly-review equivalent is a separate pass across a whole project: merge or flag any inbox files that are still sitting there, chase anything in Waiting for that’s gone stale, walk the backlog with the user and decide what to promote or drop, check that nothing contradicts a decision that was already made, and check doc sizes and broken pointers. Docs nobody reviews go stale quietly, agents stop trusting them, and all the state drifts back into the conversation, which is exactly the expensive, lossy place this whole setup is trying to get away from.
What I left out on purpose
Full GTD has more moving parts: contexts, horizons of focus, tickler files for things to resurface on a date. I skipped all of that here. Every extra section in a doc is something that gets read, and paid for, on every single session that touches the project, whether or not it’s relevant that day. The pieces that are present (capture, one-home-per-item, next action, waiting-for, someday-maybe, weekly review) carry most of the benefit; the rest wasn’t worth the standing token cost.
Does it actually save money
A little digging into my own setup suggested the docs structure matters a lot more than I expected, and some other things I assumed would help barely moved the needle.
One project had grown a fifty-plus-kilobyte CLAUDE.md over time, half rulebook and half reference material that belonged in topic docs instead. Turning it into a seven-kilobyte router and moving everything else out dropped the cost of running the same small test prompt against that project from around forty cents to around twenty-five cents. That’s not a rounding error.
By contrast, I also went and disabled a few plugins I wasn’t using, expecting a similar win. That saved around seven hundred tokens, basically nothing by comparison. The lesson: the big cost sitting in a project isn’t the tool list, it’s whatever gets auto-loaded into every session regardless of relevance. A bloated CLAUDE.md is exactly that. A plugin you never invoke mostly isn’t.
The other cleanup worth mentioning: a few skills had ended up duplicated between a user-level install and the ones already built in, so I removed the redundant copies. Not a token story so much as a “don’t make the agent choose between two copies of the same thing” story.
The short version
Treat the conversation as scratch space and the docs as the actual state. Keep the always-loaded file tiny and route everything else through pointers. Capture findings and decisions as they happen instead of letting them live only in chat history. Give every captured thing exactly one home. Run a quick wrap-up at the end of a session and a fuller review on a schedule. None of this is novel if you’ve used GTD before, it’s just GTD’s capture-clarify-review loop pointed at a coding agent’s project memory instead of a person’s inbox.
Leave a Reply