Context debt

one of the biggest emerging problems in agentic harnesses that i don’t see anyone really talking about is “stuckness”: the way semantic shape builds up in your markdown resources and drifts from the project you actually have.

(this is most visible with code, but it generalizes)

this is the flip side to the benefits of “markdown is code”, but it’s actually harder to review and fix.

everyone is talking about

“put this in your CLAUDE.md!” “save it as a memory!” “add all the skills!”

but everything recorded has a SHAPE that does not self evolve. and when your agent reads it, it becomes a directive.

that shape is sticky. your agent won’t vary from it. it trusts it implicitly.

that shape also rots. parts go stale, or stop being true. and it’s hard to notice and hard to fix.

this can happen on a silent and systemic level. your project grows: new surface area, new understanding, new ambitions. but the markdown still describes the smaller thing you started with. your brain retrains as you go. the markdown just sits there. the agent keeps referring to a snapshot of a project that no longer exists.

the obvious fix, adding dated memories like “March 22 - new update. We now think in terms of programs which are collections of tasks” feels magical for a day. but it encodes a misplaced authority when drift inevitably happens again.

also applies to:

• runbooks: written to avoid past mistakes, but give the agent confidence in patterns that may not work for long
• skills: “when all you have is a hammer every problem looks like a nail”. even with a few, the agent reaches only for familiar moves instead of reasoning through a new problem
• conflicts and tension: across lots of memories and markdown, contradictory statements arise, causing erratic agent behavior.

it’s hard to fight because:

• no tests — unlike code, you can’t assert prose, so inconsistencies go undetected
• no observability — you can’t directly see the effect they have, you have to sense it over time
• no provenance — even when you review it’s hard to know what’s true. no symbolic link to the source or history for why it got there
• natural language is inherently subjective
• agents don’t naturally “hedge” when they write instructions for you

instead:

• be ruthlessly judicious in what you encode — LESS IS MORE
• point to the source of truth — do NOT let the agent restate in prose what can be inferred from code
• encode the “why” not just the what
• intentionally separate core truths that rarely change, from softer hints that may need evolving

agents only see what exists, never what’s missing. negative space is useful. it’s what allows fresh thinking. too little context and we reinvent the wheel. too much and we never look over the next hill.

call it “context debt” — the agentic sibling to technical debt.

this problem needs better underlying solutions as agentic systems mature.

the “markdown as code” paradigm itself may need to evolve.

but for now, watch out for this pattern and be smart about what you commit to the record.