specs are not agent memory

I have a mildly unfashionable opinion about repository documentation: most of it should not live next to the code forever.

Not because documentation is bad. Quite the opposite. Good documentation is one of the few things that lets a team move quickly without repeatedly rediscovering how its own system works.

But a repository is not a museum for every product spec, exploratory prompt, abandoned plan, workshop transcript, and argument from six quarters ago. In an AI-assisted codebase, that pile has stopped being inert.

It is now part of the prompt.

That is a meaningful change. A human engineer can see a dusty docs/old/ directory and decide, correctly, to ignore it. An agent may retrieve it, summarize it, or follow it with the cheerful confidence only a machine can bring to obsolete instructions.

So this is not an argument for deleting history. It is an argument against prompt landfill.

the repository became part of the runtime

We used to describe a code repository as source, tests, configuration, and some documentation. That was already incomplete, but it was close enough for daily work.

Now repository text actively shapes implementation. Codex reads AGENTS.md. Claude Code reads CLAUDE.md. Gemini uses GEMINI.md. GitHub Copilot supports repository-wide instructions, path-specific instruction files, and AGENTS.md files for agents. If a matching path has both repository-wide and path-specific Copilot instructions, GitHub says both are used. That is documented behaviour, not a metaphor.

This is useful. It means a repository can teach an agent how to install dependencies, run a focused test, respect a security boundary, or avoid the one legacy subsystem that turns a two-line change into an incident.

It also means every extra document has a potential operational cost.

The cost is not just the literal token bill. It is attention. A model has to decide what matters among the current task, the code under edit, test output, tool results, instructions, and whatever historical debris retrieval added to the pile. Anthropic describes context engineering as curating the information available during inference; Sourcegraph makes the same point more bluntly: context includes far more than the prompt, including retrieved content and tool output. Anthropic and Sourcegraph are describing a runtime budget, not a filing cabinet.

The expensive failure mode is not an agent spending a few more cents. It is an agent reading a 2024 rollout plan and “helpfully” restoring a decision the team reversed in 2025.

a spec is a plan, not a constitution

Specs are useful. I write them. Teams should write them before significant work, especially when the work crosses product, operations, security, and architecture boundaries.

But a spec has a job with an expiry date: help people decide what to build and coordinate the change. Once the change ships, the spec is no longer the best description of reality.

The running system is reality. The code is evidence. Tests state the behaviour we are prepared to defend. Runbooks say how we operate it. A short record can explain why an otherwise strange trade-off exists.

Keeping the full spec at the centre of repository context after delivery creates a subtle contradiction. It describes a possible future; the code represents an actual present. Human readers are good at spotting the difference, particularly when they were in the meeting. Agents cannot reliably infer it from filename vibes.

This does not mean every completed spec must be destroyed. It means it should leave the operational path. Archive it, attach it to the issue that led to the work, or compress its durable lessons into a smaller artifact. The raw material remains discoverable when someone has a real historical question. It is simply no longer competing with current instructions every time an agent starts work.

That is the right default: history should be searchable evidence, not always-on guidance.

four kinds of text, four different jobs

The easiest way to stop accumulating prompt landfill is to admit that not all Markdown is the same thing.

guidelines are the house rules

Guidelines answer questions that will still matter next month: what commands verify a change, where a boundary sits, what security rules are non-negotiable, how modules are organized, and what a pull request must include.

This is the territory of a concise AGENTS.md, CLAUDE.md, or path-scoped instructions. It should be specific, actionable, and boring in the best way. GitHub’s own advice for custom instructions focuses on project context, architecture, coding standards, and workflows—not a complete transcript of the team’s intellectual history. Good custom instructions are meant to improve the next task.

If a guideline is not stable enough to survive a quarter, it is probably not a guideline yet.

skills and playbooks are repeatable work

A skill is different from a rule. It answers: “when doing this recurring job, what is the safe and effective procedure?”

Release a package. Rotate a credential. Debug a flaky integration test. Create a migration. Investigate an incident. Those workflows have steps, preconditions, checks, and sometimes escape hatches. Putting them in a focused playbook means an agent can load the procedure only when it is relevant.

That is better than pasting release instructions into a root instruction file and hoping the agent remembers which eight paragraphs apply to the task in front of it.

There is a useful context-engineering pattern here: write, select, compress, isolate. LangChain uses those four verbs to describe ways to manage agent context. A skill is an excellent example of isolate: keep the detailed procedure available, but do not make it background radiation for unrelated work.

decision records are compressed history

Some historical context absolutely belongs in the repository. A future engineer needs to know why we selected one database, accepted a consistency trade-off, split a service, or declined a seemingly obvious dependency.

That is what an ADR is for: one significant decision, its context, the alternatives considered, the outcome, and the consequences. Short is a feature. Martin Fowler describes ADRs as short documents that record a decision and its important ramifications; when a decision changes, the original should point to the superseding record rather than being rewritten into fiction. Microsoft’s ADR guidance similarly recommends an append-only log with clear status and supersession.

An ADR is not a design document with a better filename. It is a compression algorithm for organizational memory.

specs and raw history are evidence

Specs, proposal threads, meeting notes, generated planning dumps, and prompt experiments can all be valuable. They are evidence: useful when someone needs to reconstruct the decision, challenge an assumption, or understand the constraints at the time.

Evidence should be retained deliberately, with an owner and a link from the decision record when it matters. It should not quietly masquerade as a current operating manual.

token waste is really attention waste

I do care about context cost and latency. If an agent has to read 30,000 irrelevant tokens before it can locate the module and run the test, that is a bad experience and a bad use of money.

But the more important issue is quality.

Long context is not automatically better context. It can dilute the task, increase conflicts between instructions, and make it harder to recognize which details describe the system today. The model might see a current test, a current instruction, and an old implementation plan that says the opposite. If it chooses wrongly, “but the repository said so” is not a particularly comforting incident review finding.

This is why I would treat AI-facing repository text like a dependency: it needs ownership, review, and occasional garbage collection. Ask a simple question during a docs review: would we want an agent to follow this today, without a human in the room to explain the caveats?

If the answer is no, move it out of the live path or label it so clearly that retrieval can filter it.

a practical retention policy

You do not need a documentation council and a three-stage approval process to fix this. A small policy gets most teams most of the benefit.

Keep near the code:

• a README that explains what the project is and how to start safely;
• short, owned agent instructions with project and path-specific rules;
• skills or playbooks for recurring procedures;
• runbooks for operating real systems;
• ADRs for consequential decisions; and
• tests and executable configuration, because they are often the most honest documentation you have.

Move out of the live context after delivery:

• raw product specifications;
• long proposal threads and meeting notes;
• abandoned plans and exploratory prompts;
• generated design dumps;
• duplicate architecture explainers; and
• onboarding material that has become archaeology.

Then leave a useful trail. An ADR can link to the original proposal. A docs/archive/ index can say what is historical and why. An issue can keep the product conversation. The goal is not to make history impossible to find. The goal is to make current intent difficult to misunderstand.

One more rule helps: every AI-facing instruction file should have an owner and a review cadence. It does not need ceremony. Add it to the same maintenance rhythm as dependency upgrades, runbook reviews, or quarterly engineering hygiene. Delete rules that repeat the obvious. Split instructions by path when they are only relevant to one part of the system. Turn repeated operational prose into a reusable playbook.

In other words, keep the repository teachable.

less memory, better memory

The temptation is to preserve everything because storage is cheap and someone might need it someday. That was already a weak documentation strategy. Agents make it actively risky.

The repository does need memory. It needs the memory that changes future work: stable rules, repeatable procedures, and concise explanations of important choices.

It does not need every thought that led there injected into the next task.

Clean context is not anti-documentation. It is documentation with a job description.

references

• Anthropic: Effective context engineering for AI agents
• Sourcegraph: Context Engineering for AI Agents
• LangChain: Context Engineering
• GitHub Docs: Adding repository custom instructions for GitHub Copilot
• VS Code Docs: Use custom instructions
• Microsoft Learn: Maintain an architecture decision record
• Martin Fowler: Architecture Decision Record
• GitHub Blog: 5 tips for writing better custom instructions for Copilot

To test my projects, I use Railway. If you want $20 USD to get started, use this link.