Context engineering for coding agents: making project docs resumable in 7K tokens

TL;DR: A coding agent has no memory between sessions except what you write down, so project docs are its long-term memory, and the thing to optimize is how much it has to read before it knows what to read next. I measured it: resuming a real work thread from a one-line prompt cost about 6,700 tokens with a structured docs tree, against 39,500 tokens for reading the same three files whole, an 83% cut. The rules that got me there are small: a hub file under 200 lines, an entry block under 100 lines at the top of every thread file, files split by how they are read instead of by size, and instructions written as "what to do plus one sentence of why" with the long rationale archived elsewhere. Line count turned out to be the wrong metric for docs.

The problem: a docs tree no session can read

One of the products I run, an AI-visibility tool, has accumulated a large documentation tree over the months I have been building it with coding agents: 189 markdown files, about 64,000 lines, roughly 1.5 million tokens. It holds plans, research, measurements, decisions, runbooks and the running state of a dozen parallel work threads. No session can load that, and none should try.

Yet every new session has to pick up where the last one stopped. When I end a long session, I leave a pointer like "continue from this file, thread state section" and start fresh, because long sessions are where the tokens go. That only works if the fresh session can orient itself cheaply. So the question I needed answered was concrete: how much does it cost the agent to get back into a thread, and what in the docs structure drives that cost?

This is context engineering: deciding what information enters the model's context window, in what form and at what moment. Writing a prompt is a small part of it. Most of it is structuring the material the agent pulls in on its own. For a coding agent, the project's docs are its agent memory, the only state that survives from one session to the next, so their shape is a context engineering decision whether you treat it as one or not.

How many lines can a markdown file have before an agent gets lost?

That was the question as first asked. For application code I already work with a soft ceiling of 800 lines per file, and the obvious move was to apply the same number to docs. The measurement said that was the wrong frame.

I gave a fresh session a one-line prompt pointing at a thread in a marketing workstream and counted what it read before it started real work:

The same three files read in full would have been about 39,500 tokens. Structure cut the cost of entering the thread by 83%. And the thread file itself is 864 lines long, over my code threshold, which did not matter at all, because nobody reads it whole. The binding cost of a docs file is the amount you must read before you know what to read next. Total length only matters in the rare case where you genuinely have to read everything.

The options I considered

Before settling on the structure, I weighed three approaches.

Load everything relevant up front. Point the session at the full plan or the full thread file and let it read. The pro is that nothing gets missed. The con is cost and dilution: one plan file alone was around 35,000 tokens, most of it history the current step did not need, and a context full of stale detail makes the model worse at the part that matters.

Cap files by line count. Split anything over a fixed size. The pro is that it is easy to enforce mechanically. The con is that it cuts in arbitrary places, so a session often needs both halves in the same turn and pays for two files instead of one.

Structure for retrieval. Keep identifiers in context (a file path plus a section anchor) and pull the content only when it is needed. Anthropic's own guidance on context engineering calls this just-in-time retrieval, as opposed to preloading. The pro is that the cost scales with the task, not the archive. The con is discipline: every file needs an honest entry block and headings you can choose from, and that has to be maintained.

I chose the third, with a few hard limits so that it stays maintained.

The thresholds that came out of the measurement

I measure four things instead of one:

Append-only journals, such as a worklog or an experiment log, get cut at about 1,000 lines. They have no entry block; their value is the newest entries, and the old ones become an archive.

The entry block itself has a fixed shape so a session can trust it: the goal of the thread, what is done, what is left, open decisions, the exact next step, and the files to open. The same shape doubles as the handoff note I write at the end of a long session, which means ending a session and resuming it use one format.

Split by how a file is read, not by how long it is

When a file does need splitting, one question decides where: would any session need both halves in the same turn? If not, they are two files. The cut lines that have worked for me are canon versus journal (how something works, versus what happened and when), live versus closed (active threads, versus an archive of finished ones), and measurements versus decisions (raw numbers get recomputed, verdicts get read).

The failure mode to watch for is also about the entry block, not the length. Across the tree the ratio varies tenfold. One thread file has an 82-line entry block on 864 lines: healthy. Another had let its "current state" block grow to 2,464 lines inside a 3,383-line file, which means the entry block had eaten the file, and it was cheaper to read the whole thing than to work out what was current. That is the symptom that actually hurts. The second one is headings you cannot choose from. A heading like "Result 7" is useless to an agent listing the sections of a file; "Result 7: narrow questions matter more than long ones" lets it skip the rest.

What does a coding agent load before you type anything?

Resume cost is one half. The other half is the floor every session pays before the first word about the task. I covered which mechanisms load eagerly and which lazily in my earlier post on Claude Code context architecture, so here only the measured budget for that same product:

About 14% of a 200K window before any work happens. Two lines in that table were worth acting on. The skill index was not one of them: 21 skills for 2,700 tokens is cheap.

The memory index is silently truncated. Claude Code loads the project memory index at startup up to 200 lines or 25KB, whichever comes first, and drops the rest without a warning. Mine was at 78% of that limit. Past it, the tail of the index would simply stop loading, and the agent would not know those memories exist. So the index is one line per entry, a hook of one sentence pointing at a detail file, never a paragraph with dates and exceptions.

The global instruction file was over the recommended 200 lines. This one has a history. Earlier this month it weighed 41KB, around 12-13K tokens, five times more than all my subagent descriptions combined, because every rule carried a long explanation with the story of the incident that produced it. That is useful to a human and a tax on every single session.

How should you write instructions for a coding agent?

The fix for that file became my format for every rule: what to do, plus one sentence of why. The full rationale, with the incident history and examples, moves to a separate archive document that the rule links to. The agent gets the behavior and enough reasoning to apply it to cases the rule did not anticipate; the archive keeps the history for the day a rule needs revisiting.

<!-- illustrative shape of one rule -->
## Tests must not fail after a date
Freeze the clock when fixtures pin dates, or compute dates from "now".
Why: a literal date in a fixture plus a real clock in the code breaks weeks later, silently.
Full history: see the rationale archive, section "Tests".

The one sentence of why earns its place. A bare rule gets applied literally and misapplied at the edges; a rule with a reason gets generalized correctly. The incident narrative does not earn its place in the always-loaded file, because the model does not need the story to follow the rule. That rewrite took the global file from about 12-13K tokens down to about 5.6K. It is still 38 lines over the recommended limit, which is the honest state of it: the format works, and the file still needs another pass.

Limits, and what I would tell someone starting tomorrow

This approach has costs. The entry blocks rot if nobody updates them, and a stale entry block is worse than none because the agent trusts it. I rely on the agent to update the block at the end of each piece of work and on myself to notice when a block starts to swell. The token figures are estimates from byte counts, good to within a margin that does not change any decision here. And the whole thing assumes the agent reads the entry block first instead of opening the entire file on reflex; pointing it at the section explicitly in the resume prompt is what makes that reliable.

• Measure resume cost, not file length. Hand a fresh session a one-line pointer and count what it reads before working. That number is the one to drive down.
• Give every thread file an entry block under 100 lines with a fixed shape: goal, done, left, decisions, next step, files.
• Keep hubs under 200 lines. They load every time; they route, they do not explain.
• Split by access pattern. If no session needs both halves at once, it is two files.
• Write headings an agent can choose from. A section list should work as a table of contents on its own.
• Watch the silent limits. A memory index past its cap does not error; it just forgets.
• Write rules as what to do plus one sentence of why, and archive the long rationale where a human can find it.