Software teams have tried to document architectural decisions for decades. ADRs, RFCs, design documents, architecture wikis, the formats have changed but the pattern has not. Someone writes down what was decided and why. Others read it, hopefully, at some point in the future. The benefit is real: future team members understand why the code is shaped the way it is, onboarding is faster, and the same arguments don’t have to be relitigated every six months.
The practice rarely sticks. Not because people don’t understand the value, but because the feedback loop is too long. You write an ADR today. The benefit shows up when a new engineer joins in four months and reads it rather than asking four people separately. You never see that conversation. The causal connection between the documentation you wrote and the confusion it prevented is invisible. Human motivation is poorly suited to rewards that arrive months later and affect people you haven’t met.
Context Anchoring, described by Rahul Garg as part of Martin Fowler’s Reducing Friction with AI series, is decision documentation for AI coding sessions. The format is a living markdown document maintained alongside the conversation, capturing decisions made during the session, the rationale for each, and the options that were explicitly ruled out. The model is pointed to it at session start and re-referenced whenever significant design choices are made.
It is the same discipline as an ADR, applied to a different artifact. But the feedback loop is completely different, and that difference might matter more than anything else about the practice.
Why the Feedback Is Immediate
Transformer attention is not uniform across a long context window. Information that appeared early in a conversation, even within the same session, exerts less influence on model output as the context grows. The Lost in the Middle paper, published by Liu et al. at Stanford and UC Berkeley in 2023, documented this concretely: models tested on multi-document question answering performed substantially worse when the relevant document was placed in the middle of the context versus at the beginning or end. The effect held across model sizes and context lengths.
Applied to a coding session: a decision you made at message five is sitting in the middle of the context by message fifty, and its influence on what gets generated next has weakened considerably. The decision is still in the transcript. The model has not discarded it. It has just stopped paying close attention to it.
This is why you can negotiate a clear architectural approach at the start of a session and watch the model drift away from it forty messages later without any single wrong turn you can point to. The constraint was real when you stated it. It became progressively less constraining as implementation details and follow-up exchanges accumulated above it in the context window.
Write the decision into a context anchor and explicitly re-reference it before consequential generation steps, and the model’s output stays consistent. The explicit reference pulls the decision back toward the beginning of attention rather than letting it sit in the middle. The benefit appears in the next response, not in four months.
This is a fundamentally different incentive structure from any prior form of decision documentation. The reason to write an ADR is that your future teammates will benefit. The reason to write a context anchor is that you will benefit, in the current session, within the next dozen messages.
What the Document Contains
The structure of a context anchor resembles an ADR in its most important parts: what was decided, what was rejected, and why. A representative example for a refactoring session:
# Session Context: Payment Flow Refactor
## Objective
Refactor the checkout payment flow to use the repository pattern,
removing direct database calls from the payment service layer.
## Decisions Made
### Architecture
- Repository pattern (not service locator)
- Rationale: service locator obscures dependencies and makes
the payment service harder to test in isolation
- Repositories live in /src/repositories, injected via constructor
### Scope
- PaymentRepository and OrderRepository only this session
- SubscriptionRepository is out of scope (different team)
- No schema changes; data model is fixed
### Constraints
- No DI framework; manual constructor injection is sufficient
- All repository interfaces use explicit return types, no implicit `any`
## Open Questions
- Whether to wrap repository errors in domain exceptions or let
them surface as-is to the service layer (not yet decided)Two structural features matter beyond the obvious. First, the rationale. A model that knows only the conclusion, “use the repository pattern,” will apply it correctly in cases the constraint directly addresses. A model that also knows the reasoning, “service locator obscures dependencies,” will generalize correctly to adjacent cases that weren’t anticipated when the decision was made. The rationale extends the effective scope of the constraint without requiring you to enumerate every possible application.
Second, the Open Questions section. When a question remains unresolved but implicit, the model will resolve it anyway, in whatever way seems most locally reasonable given the recent context. The decision still gets made; it just gets made during generation, without review, embedded in output that looks like an implementation detail rather than a design choice. Listing open questions forces them into the open where you can decide whether to resolve them intentionally or explicitly defer them.
The Distinction From CLAUDE.md
Both documents look like markdown files containing instructions, which makes it easy to conflate them. They solve different problems at different time scales.
CLAUDE.md describes your project. It contains conventions that apply across all sessions, architectural constraints already established, patterns to follow or avoid, non-obvious behaviors the model needs to know. It is maintained as part of the codebase, updated in pull requests, and read once at session start. It is stable across months.
A context anchor describes this session. It captures decisions specific to the current task and scope. It changes during the session as decisions are made and questions get resolved. It should be re-referenced at significant decision points, not just once at the start. After the session, its contents may migrate into CLAUDE.md if the decisions belong to the permanent project record, or serve as reference material for the next developer who touches the same area.
The practical boundary: if a decision will apply to every future session on this project, it belongs in CLAUDE.md. If it only applies to what you are building today, it belongs in the context anchor. The two documents are complementary; neither replaces the other.
Tools like adr-tools, which manage Architecture Decision Records as part of version-controlled repositories, represent one end of the spectrum. A context anchor is the other end: lower ceremony, shorter-lived, optimized for the current session rather than the long-term project record. A well-maintained anchor from a complex session makes a natural starting point for a permanent ADR once the session is complete. The rationale is already written.
The Maintenance Problem
The honest difficulty is that someone has to maintain the document during the session. Decisions need to be recorded as they are made, not reconstructed afterward. Open questions need to be promoted to decisions once resolved. Scope changes need to be reflected.
Two approaches work reasonably well in practice. Decision-point-triggered updates: whenever a significant design question is resolved, pause and ask the model to record it in the anchor before continuing. The interruption arrives exactly when you are most absorbed in building, but capturing the decision in the moment costs thirty seconds and prevents the drift that compounds over the following hour.
Periodic AI-assisted updates: at natural breakpoints, ask the model to review the recent conversation and update the anchor to reflect decisions made since the last update. The model can reconstruct what was decided from the transcript. You review and confirm. This introduces some reconstruction risk for complex sessions with significant back-and-forth, but removes the interruption at each individual decision point.
Neither approach is frictionless. What makes the friction worth absorbing is the immediate return. Unlike writing an ADR at sprint end and hoping someone reads it, the cost of maintaining a context anchor is paid back within the session that incurs it. The model’s output stays consistent. Constraints don’t drift. Open questions get resolved intentionally rather than implicitly.
Whether This Changes How Teams Document Decisions
There is a reasonable question about whether a discipline sustained by immediate feedback in AI sessions transfers to the broader practice of decision documentation. If engineers internalize the habit of writing down decisions and rationale in the context of AI work, because the feedback arrives immediately and concretely, they may carry it back to ADRs and design reviews where the feedback is deferred.
The pattern of capturing “what was decided, what was rejected, and why” is identical across all of these artifacts. Learning it in a context where the feedback is immediate may build the intuition that was hard to build when the only feedback was a new engineer asking a question six months later. The incentive structure is different enough that the hypothesis is worth taking seriously.
Whether that happens at scale is genuinely unclear. What is clear is that for AI coding sessions specifically, the immediate feedback loop changes the economics of decision documentation in a way that no prior format has managed. The discipline has always made sense. It has never had this kind of immediate reinforcement before.