Instructions That Persist, and Instructions That Rot

Some instructions outlive the session: the project instructions file, your personal instructions file, and notes that some tools save on their own. They are the agent's only memory between sessions, and like any memory they go stale.

A stale instruction is a bug on a delay. It keeps steering the agent long after the code it described has changed, in every session, for everyone on the team, and nothing in the agent's output says which line sent it the wrong way.

Three Layers

The project instructions file from Chapter 3 lives in the repository, is shared by the team and is reviewed like code. A personal instructions file lives in your home directory and applies to you in every repository you open; it is the place for how you like to work, such as how long you want explanations to be or how a summary should be laid out. As of 2026 several tools read one, under their own file names, which Chapter 15 lists.

The third layer is newer. As of 2026, some tools let the agent write notes of its own that load into later sessions, and at least two do it without being asked: the agent decides, during a session, that something is worth remembering, and saves it. The agent loads all three layers at the start of a session, and nothing in them tells it which lines anyone reviewed. A line in a note nobody has read can steer it as firmly as a line Ines reviewed.

At Cragmoor the three layers are small. The project file is about 50 lines: the commands from Chapter 3, the money and time-zone conventions, the files out of bounds. Your personal file is six lines, all about how you like the agent to report: summaries short, changed files listed first, questions before guesses. The saved notes are whatever the tool has collected since your first week, and until you open them you do not know how many there are or what they say.

How Instructions Rot

The code moves and the line does not. Ines moves the tests out of the unit directory; the instructions file still says "tests live in the unit directory". The team retires an old date helper in booking in favour of the time-zone helper in schedule; the file still says to use the one in booking. The refund change of Chapters 5 to 9 ships the 12-hour window; the file still says the window is 24 hours.

- Tests live in the unit directory, one file per module.
- For class times, use the date helper in booking.
- The full-refund window is 24 hours before the class.

The agent follows each line confidently. Asked for a new test, it creates the unit directory again and puts the test where the test runner does not look, so the test never runs. Asked for a class-time calculation, it reaches for the retired helper. Asked about refunds, it explains a rule that no longer exists. Each result is a diff that recreates the past, and a reviewer who does not know the instructions file sees only a strange choice.

Some rot can be caught by a machine. Every path the instructions file names can be checked for existence in the test suite or in a short script the continuous integration runs: if the file says tests live in the unit directory and the unit directory is gone, the check fails on the pull request that moved it. Chapter 3 recommended turning checkable rules into lint rules or tests; checking the instructions file itself is the same idea pointed at the file. Lines about intent, such as which helper to use for class times, still need a person to read them.

Contradictions Between Layers

Your personal file says "add a comment above every function". The project file says "match the surrounding style". The module you are working in has no function comments at all. The agent has two instructions that disagree. Some tools let the project file win, as the later of the two to load; in others neither outranks the other, and the agent picks one per session: on Monday the diff adds comments to every function it touches, on Tuesday it adds none. Reviewers see inconsistent diffs from you with no visible reason.

A project rule beats a personal preference, because the project rule is what the team agreed and reviews. Say so in your personal file, or keep the personal file silent on code style and use it only for how the agent talks to you.

Notes You Did Not Write

Automatically saved notes record whatever seemed worth remembering in a session, and the agent's judgement of that is not yours. A note can record a workaround you later rejected, a wrong conclusion about why a test was flaky, or "the refund window is 24 hours" written the week before it changed. Once saved, the note loads into every session that follows and is repeated as faithfully as a correct one.

Some tools now try to age notes out when nothing confirms them, and others keep them until someone deletes them. Either way, read the notes on a schedule, as you would any configuration that changes behaviour, and delete what is no longer true.

At Cragmoor the first wrong note appeared in your second week. A session spent an hour on a flaky test in schedule and saved a note that the test "depends on the order the suite runs in". The real cause, found by Ines a week later, was a test fixture that read the system clock. For the next month every session that touched schedule started by suggesting the suite be run in a fixed order, and nobody connected the suggestion to a note until you opened the notes and read them.

Keeping Them True

Change the project file in the same pull request as the code it describes: when Ines moves the tests, the line moves in the same diff, and the reviewer reads it. Prefer deleting a wrong line to adding a correction below it, because a correction leaves two contradicting lines in context and hands the choice back to the agent.

Every few weeks, read the whole set, all three layers, and ask of each line whether it is still true and still needed. And when the agent does something odd and does it consistently, check the instructions before the code. Consistent wrongness usually has a written source.