What Context Anchoring Borrows From ADRs, and What It Finally Gets Right

There’s a well-understood failure mode in software documentation: architectural decisions get made in meetings or Slack threads, never written down, and six months later nobody can explain why the codebase looks the way it does. Architecture Decision Records emerged as a lightweight remedy. The format, popularized by Michael Nygard, is minimal: a short document per significant decision, capturing context, options considered, and outcome. ADRs work in theory. In practice, adoption stalls. Writing them adds friction to a workflow that already has plenty, and most developers quietly skip the step unless a strong team norm enforces it.

Context anchoring, as Rahul Garg describes it on Martin Fowler’s site, targets a narrower and more immediate version of this problem. When you work with an AI coding assistant, every architectural constraint, design decision, and working agreement you establish during a session exists only in the active context window. Once that window fills or the session ends, the context is gone. The problem is not forgetting over months; it is forgetting over minutes.

The proposed solution is a living document that externalizes this decision context: a file the AI reads at the start of each session that re-establishes what matters. Claude Code uses CLAUDE.md. Cursor reads .cursorrules. GitHub Copilot supports .github/copilot-instructions.md. The format and name vary by tool, but the function is the same: a persistent system prompt that sits above any individual conversation.

Why the Economics Are Different

The core insight in Garg’s framing is that context anchoring has a fundamentally better feedback loop than ADRs. The consumer is the AI, not a human. When you write an ADR, the value is realized only when a future developer reads it, which may be months away and may never happen at all. When you maintain a context anchor document, the value is realized in the next session, and in every session after. The return on writing the document is immediate and measurable.

This is why ADR adoption consistently lags despite near-universal agreement that it is a good practice. The developer who writes the ADR is not the one who benefits directly. The benefit accrues to a future team member, possibly one who has not joined the project yet. Context anchoring inverts this: the developer who maintains the document benefits in the very next working session.

There is also a readability constraint that matters more when the consumer is an AI. A human developer reading an ADR can skim, jump around, and infer context from the surrounding codebase. An AI assistant reads what you give it in the order you give it. A context anchor that buries relevant constraints in three paragraphs of background will produce worse results than one where the operative constraints appear first. Format is not aesthetic; it is functional.

What to Include

A working context anchor document is not a project README rewritten for AI consumption. A README describes what the project does and how to run it. A context anchor describes the constraints that shape ongoing work: what you have already decided, what is off the table, and what tradeoffs you have consciously accepted.

In concrete terms, the document earns its place when it captures a few categories of information.

Architectural constraints that are not obvious from the code. Something like: “We use SQLite for persistence because the deployment target is a single VPS with no separate database process.” This constraint will not be discoverable by reading the code, but it eliminates a large class of suggestions the AI might otherwise generate. Without it, you will spend time in every session redirecting the AI away from Postgres or Redis recommendations.

Working agreements. “Do not add new dependencies without flagging it first.” “Error messages should always include enough context to debug from logs alone.” These are the things you would tell a contractor on day one, and they are exactly the kind of thing that gets re-established from scratch in every new session without an anchor document.

What you have tried and rejected. If you spent three sessions debugging a particular approach and abandoned it, capturing that saves you from relitigating it later. “We tried WebSockets for the event stream but ran into reconnection issues under load; we are using SSE now.” This is the closest equivalent to the ADR format, and it is genuinely useful.

Open questions. Not every architectural decision is settled. Naming open questions explicitly prevents the AI from making assumptions that diverge from your current thinking on them.

What the document should avoid: everything. The instinct to document comprehensively is the same instinct that kills ADR programs. A context anchor that is too long gets skimmed or ignored entirely. Shorter and more specific is almost always better, particularly for the constraints the AI needs to hold in mind while generating code.

The Staleness Problem

Garg’s framing correctly identifies the document as “living,” but that word deserves scrutiny. Living documents have a reliable tendency to die quietly.

The failure pattern is predictable. You start a project, write a careful context anchor, and for the first few weeks it stays current. Then you make a significant architectural change mid-session, do not update the file, and move on. A few more sessions pass. The file now describes a version of the project that no longer exists. The AI reads it, and the outdated constraints actively mislead rather than help. At that point you are worse off than having no anchor at all, because the AI is confidently working from a false model of the codebase.

The mitigation is to treat updating the anchor document as part of session cleanup, not an optional step. When a session ends with a significant decision, the last action in that session should be recording that decision in the file. Some developers run this the other way: start each session by reviewing the document and questioning whether it still reflects reality. Neither approach is free, but the cost is paid in the session where the decision was made, not deferred to a documentation sprint that never arrives.

A structural convention that helps here: separate stable constraints from volatile ones. Language choice, deployment target, and core library decisions are unlikely to change, and can live in a section you review infrequently. Current-state notes, open questions, and recently-made decisions belong near the top of the file, where they are easy to update and easy to notice when stale.

The Side Effect Worth Naming

The observation that writing a decision down changes the decision has been made often enough that it is nearly a cliche, but it describes something real. When you are forced to articulate a constraint in writing, ambiguities surface. The act of externalizing your decision context is also an act of clarifying it. You cannot write “we decided to use event sourcing because it fits our audit requirements” without noticing that you have not actually defined what those audit requirements are.

This is a genuine benefit of maintaining a context anchor document that goes beyond what the AI gets from reading it. The developer who writes and maintains the file may benefit more than the AI does. The document becomes a forcing function for clear thinking, triggered on every significant decision, not just the ones that happen to rise to the level of a formal ADR.

This is where context anchoring diverges most clearly from ADRs in practice. ADRs are written retrospectively, after a decision is finalized. Context anchor updates happen mid-workflow, often during the session where the decision is still being shaped. The format is looser and the content is rougher, but the timing means the clarifying effect happens when it can still influence the decision.

Where Context Anchoring Fits in the Broader Workflow

Context anchoring is one piece of a larger problem: maintaining useful state across AI coding sessions. The anchor document handles persistent constraints and settled decisions. It does not handle in-progress work, conversation-level context, or task tracking. Those require separate mechanisms, whether that is a TODO file, a kanban board, or explicit session notes at the top of the document that get cleared out at the start of each session.

The original article frames context anchoring as part of a broader effort to reduce friction in AI-assisted development. That framing is accurate, but the specific friction being reduced is worth naming precisely: decision amnesia. Every developer who has spent the first twenty minutes of a session re-explaining the codebase’s constraints has felt it. The context anchor document is a way to pay that cost once and amortize it across sessions rather than paying it fresh every time.

The practice works. The maintenance challenge is real. Acknowledging both up front changes how you structure the document from the beginning, which is the most practically useful thing to understand before you adopt it.