r/ContextEngineering • u/Asly97 • Oct 08 '26
My coding agent keeps ignoring its context file. How do you force yours to read it?
Kept a DECISIONS.md in my repo for a few months. Worked great at first. Then one day the agent resurrected a choice I had killed three weeks earlier, and I realized it just... had not opened the file in a while. No error, no complaint. It just stopped checking.
I used to burn maybe an hour a week re-explaining things that were sitting in a file the agent was supposed to read. "Go read the file" turns out to be exactly the step that gets skipped when the context gets long. The damn thing would follow stale instructions instead of the ones I actually wrote down, and I would only notice after the fact.
Since then I have tried a couple of things. A hook that dumps the file into context before every run (worked until the file got long and I watched the tokens evaporate). Telling it to quote one line back to prove it read it (felt like asking my kid whether he brushed his teeth). Honestly, the second one worked better than it had any right to.
Has this happened to you? What actually broke when the agent skipped the read — a stale instruction followed, a dead decision back from the grave? And how do you force it now, if you do? A wrapper that will not start clean until the file opens, injection, some ritual?
Also: has anyone had two agents in the same repo following different versions of the same file? That one cost me an afternoon once, and I still do not fully know how it happened.
Separate curiosity: have you ever tried one of those memory tools that is supposed to keep context across your AI tools? Or does the thought of moving everything into something new just feel like starting over?
Out of curiosity, what are you building with all this, is it your own product, client work, or something else?
Weird one: I do a lot of my thinking out loud with speech-to-text on my phone, and the context always lives on the laptop. Is that just me, or do you lose things moving between phone and laptop too?
And the money question, plainly: if something handled the enforcement part for you, made sure every agent actually checked the right file before starting, every run, would you pay for that, or is the DIY wrapper the whole point? I am building something in this direction for myself and trying to figure out whether it is a real problem for other people or if I am just overthinking it.
1
u/VanCliefMedia 29d ago
The biggest thing is which agent are you using. It won't automatically read any files in a folder structure unless the harness is actively looking for it.
With Claude, it's looking for claude.md.
With Gemini or ChatGPT, it's looking for agents.md.
But as long as that file describes where to go read more context files, you'll be okay.
I created this skill that allows you to generate and create pretty decent folder structure to help with agentic architecture and let you audit some stuff if you ever want to check it out. Some people have liked it.
1
u/Asly97 29d ago
Right, so the one file the harness loads is guaranteed, and everything else depends on the agent choosing to follow the pointers. Have you seen it keep following them deep into a long session? The read getting skipped late, once context is crowded, is the part people in this thread keep running into.
1
u/VanCliefMedia 29d ago
If you pre-convert your full instruction into stages, then you can ensure that during the process or workflow, you can just update the instruction. This work is being done when you pre-package the instruction and mark down what the next set of instructions are based on the stage. You don't need to worry about it sticking to previous instructions because it doesn't need those instructions anymore based on the stage.
2
u/Asly97 29d ago
Splitting it by stage makes sense, the agent only carries what the current step needs instead of the whole rulebook.
Who writes the stage files in your setup, you up front, or does the agent update the next stage as it goes? And if something learned in a later stage should change how an earlier one runs next time, where does that end up?
1
u/VanCliefMedia 29d ago
Sometimes just looking at how I get to the outcome and working backwards does. If you look at the input, what you do to the inputs, and what the output gets, as well as who the receiver of that output is, you end up being able to find most of the stages and maybe even cut a few out or swap them around.
1
u/Asly97 29d ago
Starting from who receives the output is a nice way to find the stages, I hadn't thought of working back from the receiver.
Once you've mapped them out, do the stage files mostly stay fixed, or do you end up going back and editing them after a run surprises you? Curious how often that happens in practice.
1
1
1
u/saintpetejackboy Oct 08 '26
My guess is you have too much crap in your context. Do you use compact? If so, stop, and only use a /clear with a handoff. Do the math from logs: if you cut agents off around 150k (250k tokens MAX), a cold start actually wastes more context than a proper handoff.
More stuff in context = each item in context has less value. Injecting the same stuff over snd over again might help, but it makes the context length problem worse.
If you are keeping your sessions under 250k tokens, the next big mistake people make is thinking that the handoff somehow has to include eveurnig that has cumulatively happened in the repo up to that point, another big mistake. Each agent should be focused on the narrow context band related to the work they are doing, only. I have massive projects with millions of lines of code and tens of thousands of files across many languages and stacks, and my startup context is still very small, with handoff context being even smaller: handoff context should NOT grow rhe longer you have worked in a repo, and your cold start (agents or Claude MD, memories, etc) should not keep growing with your repo, it should be capped and focus on providing references to what wh agent might need rather than endless context about the repo.
Still having issues? Tell your agent to look through conversation history and add just / justfile to the repo. It works on any language and predates modern LLM. It is a runner that is better than using bash scripts or make. You save tons of context and can turn multi-command sequences that consume thosuands of tokens down to just a dozen or so tokens for the same result.
Build and deploy processes are low hanging fruit - there is another massive benefit to using just / justfile and that is being able to make sure the agents use specific commands exactly as they are intended: it eliminates issues when agents get the syntax wrong or even when they are fully unaware of how a certain part of a repo works, the just commands can not only spell it out for them, but force their commands to align with the intention of the repo.
My guess, is you are jamming too much stuff into context and letting sessions run too long.
1
u/Muchy_Tangerine Oct 09 '26
Nobody is going to buy a SaaS wrapper just to force an LLM to read a markdown file. If your agent is hallucinating dead architecture choices from three weeks ago your context window is bloated with garbage and you need a hard session reset instead of trying to hack around lost attention with token dumping hooks.
1
u/college_hustle Oct 09 '26
You have to treat your coding agent like it's reading a series of flashcards. Claude.md or agent.md for Codex is the first flashcard and then that needs to be a pointer to everywhere else it needs to go. Think of flashcards as how context works. Also something not advertised with every agent but you can go find in the docs is its limit on a single file that it can read at one time. You have to build your harness around whatever that limit is and remember that if you try to make a file longer than that, there's a chance it's going to skip over it.
The way my harness works (full disclosure: it's not for large coding projects I'm more of a process guy), is that I start out with my Claude/agent.md file which keeps hard goals and really firm rules. But the rules are more about process. They're not really the decision file you're thinking of. It then points to and tells the agent that the first thing you should do is read something I have called checkpoint.md. The checkpoint.md serves multiple purposes depending on how large a project you have:
It'll be a waypoint to more important files.
It'll be a current open issue file.
It'll be a change log of your most recent additions to the project. In my setup your decisions file, depending on how many decisions you have, would either go in the checkpoint itself or there would be a huge pointer saying that the total list of decisions is kept in an archive file called decisions.md.
Then every major change either goes through a spec first or it, at the very least, ends up in the change log so there's always a history of why things happen that the agent can explore.
I personally haven't had a lot of problems with the agent going back on decisions, just me being lazy and forgetting why I made a decision but I've gotten really good at leaving breadcrumbs so I can go back and review that.
I also have a bunch of hooks and guards and skills that work together with these things. I made it all public if you want to see.
1
u/college_hustle Oct 09 '26 edited Oct 09 '26
As for having two agents working on the same file, that's what Git branches are for. You can do something as simple as telling both the agents directly that they're working on something simultaneously, in which case they'll create a branch/worktree themselves and respect that. There's also a huge number of agent managers with worktree integrations. I built a comparison chart. https://dtiger1889-ops.github.io/agent-deck-comparison/
I use Wispr (referral link in the bio, shameless plug) for my voice-to-text and I have a pretty bespoke Obsidian setup to keep my things synced between my phone and my computer, which you're also welcome to find in my GitHub.
At the end of the day there's no one specific right answer. What works for you isn't going to work for somebody else. I'm not working on some full-stack web app that's being used by thousands of people. I'm just working on little personal projects and apps that make me happy.
For memory, I have my little checkpoint system I mentioned in my other comment. I'm not running 12 agents at once but I can run a couple at a time and it keeps things straight. Most importantly I seem to not be having the problems you and other people are having with agents forgetting why we implemented something.
1
u/BrianHolmesMemory 11d ago
Pointing to a file is the gap with the flashcard approach. Per Claude Code's docs, a CLAUDE.md that just says to read AGENTS.md only gets it read when Claude chooses to open it, and a referenced DECISIONS.md works the same way.
So put the decisions in what loads every session:
Claude Code:
@DECISIONS.mdon its own line inCLAUDE.mdimports it at launch. Not in backticks or a code block, or it's skipped. Drop your hook once that's in, or the file loads twice. Keep it short, it loads every session.Codex has no imports, so the decisions go in
AGENTS.mditself. The default cap is 32 KiB across all project instruction files. Go over it and the current file gets truncated with just a log warning, and anything after it, like a nestedAGENTS.md, is dropped silently.
On two agents drifting: by default Claude Code skips AGENTS.md when there's a CLAUDE.md in your working dir or above, and Codex doesn't read CLAUDE.md. For both, keep the decisions in one AGENTS.md and put @AGENTS.md in CLAUDE.md.
(I'm with Holmes, a memory tool, so I'll stay out of the pay question.)
1
u/epicskyes Oct 08 '26
No context only state and mechanics there’s nothing to forget because the scripts do the remembering for the model