Book-Reader-Assist/library/Context Engineering/Chapter-15-Persistent-context-files/Chapter-15-source-text.md

Context Engineering — Chapter-15: Persistent context files

• Source: /library/Context Engineering/source-file.pdf
• PDF pages: 99–108
• Pages without text: none

---

Persistent context files The previous chapter ended on a promise: a file the tool loads into the window at the start of every session, with no search and no luck involved. The VilaSchedule team created theirs that same month, and for a few weeks it was exactly that, the shortcut that pointed to the living documentation, the architecture decision records (ADRs) and the conventions before the agent took its first step. Then six months went by. On a Wednesday, you ask the agent for an adjustment to the utilization calculation, half an hour of work, and the answer comes back splitting the day into 20-minute intervals and allowing each provider three work-ins, the patients the front desk squeezes into a schedule that is already full. You know those numbers: they are the wrong ones. The interval has been 30 minutes for as long as this phase of the system has existed, and the work-in limit is 2, a number the living documentation of chapter 9 checks in continuous integration (CI) on every push. Where did the agent get those numbers? From the first thing it read in the session. You open the project’s persistent file, a few hundred lines long by now, and right at the top you find:

About the system

VilaSchedule is the scheduling system of Vila Nova Clinic. Each provider's schedule is divided into 20-minute intervals, generated

from the weekly schedule. Regular appointments take one interval; work-ins take 15 minutes and the limit is 3 per provider per day (confirm with the coordinator). Nobody knows who wrote “20 minutes,” or when the limit became “3,” or whether the “(confirm with the coordinator)” was ever confirmed. The file grew by accumulation: every incident, every preference, every complaint raised in a review became a new line, and no line ever came out. The result is the worst case of chapter 9, made worse: a document that lies, except this one does not wait for the agent to dig it out of the repository. It is injected into the window in every session, in the position of highest attention, ahead of everything else. The shortcut became the best-placed source of poisoned context in the project. The shortcut and what it costs Name the artifact before you fix it. A persistent context file is a file versioned in the repository that the tool reads and injects into the window automatically at the start of every session. It takes on head on the weakness that closed chapter 11: the four artifacts of Part II exist, but finding them costs a search that can fail. The persistent file removes the search for a small set of information, the part you decided every session has to have before the first token of work. In 2026 the principle shows up under different file names depending on the tool. Claude Code, from Anthropic, reads a CLAUDE.md ; the guide “Claude Code: Best practices for agentic coding” (Anthropic, 2025, anthropic.com/engineering) describes

it as the place for frequent commands, core conventions and warnings the agent should always see, and recommends keeping it short. AGENTS.md was born in 2025 as an open format (agents.md), adopted by several tools precisely so the same file could serve different agents. Cursor started with a .cursorrules at the root and moved to project rules in files of their own, as the public documentation at docs.cursor.com records. Get the hierarchy of that information right: the file names are dated instances and will age, perhaps before this book goes out of print; the principle, a file in the repository loaded into every session, is what this chapter teaches, and it outlives the change of name. Everything that follows holds for any instance, and I write “persistent file” so as not to marry any of them. What the instances also share is the price, and the price explains why the Wednesday file does so much damage. Every other artifact of Part II is loaded when it is relevant: the spec enters the session of the feature, the ADR enters the architecture discussion. The persistent file enters always. Every line of it costs tokens in every session, for every developer on the team, the arithmetic of chapter 6 multiplied by the number of sessions in a month, and every line competes for attention in every session, which feeds the degradation chapter 5 measured. An outdated line in the living documentation waits for someone to read it; an outdated line in the persistent file acts in every session, with the authority of whoever speaks first. It is the highest-leverage artifact in the project in both directions: the one that helps most per token when it is right and the one that does most damage when it is wrong. Anatomy of a file that works The healthy version of the VilaSchedule file fits on one screen, and its first section does the most work:

Where the truth lives

• Business rules in force: docs/scheduling.md (living documentation, checked in CI); read it before touching the schedule.
• Why the system is the way it is: ADRs in docs/adr/; read ADR-001 before proposing a change to the scheduling model.
• How we do things here: docs/conventions.md; applies to all new code.
• What to build: the spec for the task, named in the request; with no spec in the window, ask before implementing. Notice the verb: point, not copy. The file does not repeat the rules table from the living documentation; it sends the agent there, to the document CI checks and therefore vouches for. It does not paraphrase ADR-001; it says when to read it. That choice fixes the opening problem at the root: the number “30 minutes” still exists in a single place, protected by a test, and the persistent file

keeps no copy of it to rot. A pointer does not go stale when the value changes; a copy always does. And a pointer costs one line, whereas the copy costs the whole artifact in every session. Not everything can be a pointer. Some rules have to act before any reading, because the mistake they prevent happens in the first file generated. The bar for entry is narrow: in comes the rule whose violation is frequent, expensive and earlier than any search. At VilaSchedule, three of them survived:

Rules for every session

• Domain terms match what the clinic says: Appointment, WorkIn, Provider, Block. No synonyms (Booking, Visit, Slot) and no generics (Item, Entity, Record).
• An error message shown at the front desk comes from the spec, copied word for word.
• A database migration is written by hand and has its rollback (down) tested. The three come from the conventions of chapter 11, and the duplication here is deliberate and minimal: these are the rules the agent broke before it decided to look for any document, each one

costing a round of review per session. The other twenty lines of the conventions stay in the conventions document, reachable through the pointer. The file closes with the identity of the system in two lines, at the top, and the test and lint commands, which the Anthropic guide puts at the center of its recommendation for a practical reason: a command the agent knows is a command it runs without trial and error. Identity, pointers, a few rules, commands: that is the whole anatomy, and it is my opinion, after keeping files like these in several projects, that any section beyond those four owes a justification from day one. Anti-patterns, and where each line goes instead Now go back to the bloated Wednesday file with a trained eye, because it is a catalog. The “About the system” section that opened the chapter is the first anti-pattern, the copy that rots: business values duplicated outside the reach of the test that checks them. The fix is not to update the numbers; it is to delete them and point to the living documentation, because updating a copy is signing up for the next divergence. Further down, the file carries the work-in spec pasted in full “to make things easier” and a from-memory summary of why the intervals are fixed: the same anti-pattern at a larger scale. The spec has an address, chapter 8; the why has an address, ADR-001 of chapter 10. Each of those paragraphs turns into one pointer line, and the file loses pages. The second anti-pattern is the announcement, and the file has a whole section of them:

• NEVER use the old date library (moment); we have been migrating

to the new one since March.

• HEADS UP: Friday deploys are suspended until we resolve the utilization report incident.
• In the March 12 session the agent deleted a migration; NEVER delete files from the migrations/ folder under any circumstances.
• The report endpoint is slow; avoid calling it in tests until Camila optimizes the query. Every line was born from a real scare and was written in the only place with a guaranteed reader. The problem is the tense: “we have been migrating,” “until we resolve,” “until Camila optimizes” describe transient states, and a transient state in a permanent file is a lie with a due date, like the dead document of chapter 9. The deploys came back, the query was optimized, and the lines go on charging tokens and attention in every session. The right destination depends on the content: the date library migration applies to every new file while it lasts, so it is a convention; the ban on deleting migrations is already in the migration conventions and becomes a pointer; the rest is a task or a note for the team channel, and the fix is to delete it. If the information dies in two weeks, it does not belong in a file loaded forever.

The third is the generic rule: “write clean, readable code, following best practices,” “always handle errors properly.” Lines like these look harmless and are pure cost. They decide nothing the model would not already do, they draw no line between the world’s default and the house’s, which chapter 11 showed to be what gives a rule its value, and they take up attention the three real rules needed. The fix is to delete, with nothing to relocate, because there is no content to relocate. The fourth is the internal contradiction, the terminal stage of accumulation: the Wednesday file orders the full suite run before any commit and, four lines later, forbids running the full suite because it is slow. Two people, two months, no merge of intentions. For the agent, it is the distractor scenario of chapter 5 served at the door: two versions of the rule in the window and no criterion to choose between them. And the fifth you already know from chapter 11: mechanical style rules, indentation, quotes, columns, which belong to the formatter and to CI, not to text a model is free to ignore. Notice the pattern in those fixes: almost none of them invented a new artifact. The quartet of chapters 8 to 11 already gave an address to nearly everything that bloated the file; the work was to send each piece of content back to its place and leave in the persistent file only what no other artifact can do, which is to be present before the first step. “It turns into a dump and nobody maintains it” The objection you will hear when you propose the lean file comes from someone who has seen this movie before before: “every file like that turns into a dump; nobody maintains it, and in six months we are back to 300 lines.” The Wednesday file proves the risk is real. But look at the mechanism of the dump before you accept the fatalism: the file bloats because it is the only place in

the project with a guaranteed reader, so every piece of information without an address runs to it. A team with no living documentation pastes values there; a team with no ADR summarizes whys there; a team with no conventions writes “we do not do it that way here” there, one complaint at a time. The dump is the symptom of a gap in the other artifacts, and that is why this chapter is the fifth of the part and not the first: with the quartet standing, every candidate line has a better address, and the persistent file can afford to be small. The rest of the answer is to make maintenance a subtraction with a trigger, instead of promised discipline, the same move as chapters 9 and 11 make. At VilaSchedule, three triggers are enough. A dated line does not get in: if the text needs “since March” or “until we resolve,” it expires, and it goes to the team channel or to a task. A rule broken with no damage comes out: if the agent ignored a line and nobody felt it, the line was dead weight. And the file gets reviewed in the pull request that changes what it cites: whoever renames docs/scheduling.md or retires a test command updates the pointer in the same commit, like any other reference in the code. With those three, the file has what the living documentation has in CI: a cheap, immediate failure mode instead of silent rot. And it has an advantage no other artifact in this part has, which is that the most frequent reader in the project goes through it in every session. A mistake there shows up fast, as Wednesday showed; what was missing was someone to treat the file as code, with an owner, review and pruning, instead of treating it as a message board. Look one last time at the lean version and notice what it admits: most of the useful lines are pointers. The persistent file does not carry the truth; it carries the map to it, and the agent still spends search and tokens getting to the artifacts it points to. There is a cheaper layer of context than that, one that needs no loading and no writing, because the agent sees it for free in every directory

listing: the structure of the project itself. A well-organized folder tree answers “what does this system do” before a single file is opened, and a badly organized one lies just as well as the Wednesday file does. That is the subject of the next chapter.