I kept explaining the same things to my coding agent. Where a new handler belonged. Which data-access library to use. Why it should leave one particularly annoying spelling mistake alone. I'd put those details in a project memory file, but I hadn't checked whether the file was helping.
So I tried the same task on two branches of one repository. One had the memory file; the other didn't. I asked the same model to add a delete-product endpoint following the existing patterns, and left it in plan mode. I wanted to see how it worked out what to do before it started changing files.
The same plan, with a lot less reading
Without the file, the agent read through commands, handlers, validators and events to trace an existing operation. It checked how validators were registered and discovered that the solution had no test projects. This was reasonable work. It's roughly what I'd expect someone new to the codebase to do.
The frustrating part was that I'd already done that work with it in a previous session. The memory file contained the details it was finding again.
The main agent opened 41 files without memory and four with it. Both reached a correct plan. Both also noticed an unrelated outbox synchronisation problem, which was reassuring: the agent with the notes still looked closely enough to find something I hadn't asked about.
I wouldn't use that ratio to promise anyone a saving. This was one task, in one repository, with one model. I didn't measure total token use or run enough trials to call it a benchmark. But it was enough to make me take the file seriously, and to look harder at what I'd put in it.
The lines I deleted
My first draft had a list of service ports and a map of projects to folders. Both were accurate. Neither seemed worth repeating.
If the task involves containers, the agent can read the compose file. If it needs to find a project, our directory names make that fairly obvious. Keeping another copy of those facts means remembering to update it when the real configuration changes.
I started asking a simple question as I read each line: could someone find this by opening one obvious file? If so, I usually cut it or left a pointer. That isn't an absolute rule. A build command used in every session can still deserve a place near the top. I just wanted each repeated fact to have a reason for being there.
The spelling mistake stayed
A namespace in this codebase has a typo. It's used consistently across the solution, and correcting it would mean a coordinated rename. Fixing a few occurrences while doing an unrelated task leaves two nearly identical names and a confusing build failure.
That earned a line in the file: the typo is known; leave it alone. The code can show the spelling, but it can't tell a reader that we've decided to keep it for now.
Other useful lines had a similar reason for existing. Queries use one data-access library and writes use another. A dependency is still in the manifest even though we no longer want new code to use it. A static analysis tool only runs against one project. These are easy details to get wrong if you're making a reasonable guess from what you can see.
Those notes save me from having to interrupt the same mistake again. They're also much more useful than a page describing the folder structure.
Editing the generated file
I used a generated draft to get started, then compared it with my edited version. The generator was good at finding commands and describing the repository. It couldn't know which decisions had a history behind them.
Most of my editing fell into three jobs: remove things that were easy to discover, correct statements that were almost right, and add the reasons for the odd-looking bits. The typo and the unused dependency came from that last pass.
I don't try to finish the file in one sitting now. When I have to correct the same thing twice, I consider adding a note. When a note stops matching the code, I change it. It's easier to keep a short file useful when I'm willing to delete from it as often as I add to it.
Some rules need more than a note
Writing a rule down doesn't guarantee that an agent will follow it. I've had to remind myself of that when a carefully worded instruction gets ignored. The file helps, but it's still something the reader has to notice and apply.
For example, 'run the linter' is useful guidance. Having CI run the linter gives me evidence that it actually happened. A local hook can help too, though it can be skipped. For a rule that would make me reject a change, I want a check in the review or merge process rather than relying on the instruction alone.
Notes that only exist on my machine
There's also a difference between our committed project instructions and notes the agent keeps locally. A local note might remember a debugging detail or a command that worked in my environment. That's useful, but my teammate won't necessarily have it.
I try to notice when one of those discoveries belongs in the repository. If the documented build command doesn't work and we find the correct one, that should help the next person too. Leaving it in my private session history means they'll have to repeat the same debugging.
The file also has a cost. In the setup I tested, project instructions were part of the context before I asked for anything. Along with other instructions and tools, they used space the task itself might need. I'd seen a project's starting context grow to tens of thousands of tokens through lots of individually reasonable additions. Nobody had gone back to see what could come out.
That experiment changed how I maintain my notes. I keep the commands I reach for, the decisions the code can't explain, and the mistakes I've already had to correct. Then I try a real task and watch what the agent still has to work out. That's a more useful editing guide for me than aiming for a particular file length.
Based on an internal engineering session in August 2026. The two planning runs used a private repository. Examples are generalised; the original measurement was 41 versus four main-agent file reads.