From Session to Repository: The Decision Lifecycle That Context Anchoring Manages
Source: martinfowler
The problem Rahul Garg describes in Context Anchoring on Martin Fowler’s site is specific and mechanical. Transformer attention does not distribute uniformly over long context windows. Research from 2023 confirmed what practitioners had already experienced: recall performance degrades significantly for content positioned in the middle of long contexts. A decision articulated at message five of a sixty-message session has, by message forty, drifted toward the worst-attended position in the window. The decision is still there; it has simply lost its ability to constrain what comes next.
Context anchoring proposes to externalize decisions into a living document maintained alongside the session, updated as choices are made, and re-injected explicitly when the model needs to orient to current constraints. The mechanics are sound and the practice is well-supported by the empirical literature on attention degradation. What the core article describes less fully is the operational reality over time: a context anchor does not just manage one session. It manages the full lifecycle of every decision from the moment it is first tentatively made to the moment it either becomes a permanent property of the codebase or gets discarded. Understanding that lifecycle changes how you build and maintain the document.
What Makes the Context Window Difficult to Use
Before the pattern, the constraint. The context window in a language model session behaves like a database with unusual failure modes. It has bounded capacity that varies by model and pricing tier. Content inserted early reaches a low-attention middle position as the session grows. Content at the beginning and end receives the highest attention; the middle is the worst location for information that needs to exert consistent constraint.
The cost structure creates a second pressure. Longer context windows cost more per token, and every turn in a long session accumulates tokens that the model processes at inference time regardless of how relevant they remain. A session that accumulates seventy exchanges about how to structure a payment flow is paying inference cost on all seventy turns for every subsequent response, including turns that represent wrong directions, corrections, and tangents that are no longer relevant. That accumulated noise has a cost in money as well as in attention quality.
Context anchoring addresses both pressures simultaneously. A short document with high signal density costs less to process than a long conversation with high noise density. A document re-injected near the top of the context sits in the best-attended position rather than wherever it fell naturally in the conversation timeline. These two motivations, attention quality and token efficiency, point to the same structural response.
The Three Tiers
Every major AI coding tool has independently converged on at least one tier of this architecture. Claude Code reads CLAUDE.md at session start and re-injects it after context compaction. Cursor has .cursorrules at the project root and per-directory rule files in .cursor/rules/. GitHub Copilot reads .github/copilot-instructions.md, added in 2024. Aider builds a weighted repo map from tree-sitter parses of the codebase, ranking files by relevance to the current task. None of these vendors coordinated. Independent convergence on the same architecture reflects real constraints rather than product fashion.
What these tools provide is the stable tier: project invariants that hold across all sessions. The tier context anchoring addresses sits above it: decisions that are specific to the current session and task. The tier above that is architecture decision records, permanent version-controlled documents that commit a decision and its rationale to the codebase history.
The three tiers handle decisions at different stages of their lifecycle:
| Tier | Location | What it holds | Audience |
|---|---|---|---|
| Session anchor | Open scratchpad file or note | Tentative decisions, current scope, open questions, ruled-out approaches | The current working session only |
| Workspace instructions | CLAUDE.md, .cursorrules, etc. | Settled project-wide conventions, permanent constraints, repeated rules | Every AI session on this project |
| ADR | docs/decisions/ in version control | Historical decisions with full context, alternatives, consequences | Future contributors, human and AI |
The common failure mode is conflating tiers. Teams put session-level decisions into CLAUDE.md, which then grows with each session until the file is long enough that the model attends to it less reliably. They skip ADRs entirely and rely on CLAUDE.md as permanent history. Or they treat every decision as ADR-worthy and create a documentation burden that collapses the practice entirely. The three tiers are distinct because different decisions have different properties and different audiences.
The Upgrade Path
The decision lifecycle has a standard path. It begins as an open question in the session anchor. It becomes a settled decision within the session, still in the anchor. If it proves durable across sessions, it graduates to workspace instructions. If it carries architectural weight that future contributors need to understand, it graduates to an ADR in version control.
Not every decision completes all four stages. Many session decisions are tactical and specific to a task; they are relevant during the session and not worth preserving afterward. The judgment about which tier a decision belongs in at any given moment is a judgment about its scope and durability.
The trigger for graduating from session anchor to workspace instructions is repetition. When the same constraint gets added to the session anchor at the start of two or three separate sessions because the model keeps violating it without explicit guidance, that constraint belongs in CLAUDE.md. The repetition is the signal that the constraint is project-wide rather than task-specific.
The trigger for graduating from workspace instructions to an ADR is architectural weight and questions from contributors. When a constraint in CLAUDE.md starts attracting questions, the rationale that belongs in an ADR is probably missing. The workspace instruction tells the model what to do; the ADR tells human contributors why, including the alternatives that were considered and rejected. Michael Nygard’s original ADR proposal, documented at cognitect.com from 2011, emphasized exactly this: decisions made without externalized rationale become archaeology projects for later contributors. Context anchoring at the session level is the same discipline applied to the timescale of a conversation rather than the timescale of a codebase’s history.
The Cold Start Problem
Building the first session anchor from nothing has a specific difficulty. You do not know yet which decisions are worth tracking, because you have not encountered the failure modes that make tracking them necessary. The model will behave well in the early turns of a new project because there are few constraints it can violate.
A practical approach: start with a scope section and an open questions section, leaving decisions empty.
# Session Context: 2026-03-18
## Scope
Implementing the /remind command handler in src/commands/remind.ts.
Rate limiting and permission checks are out of scope this session.
## Open Questions
- Whether reminder state should survive bot restarts (in-memory vs. Redis)
- Maximum reminder duration: no product decision yet; do not hardcode a value
## Decisions Made
(empty at session start)The scope section forces explicit scoping of the first session’s work, which tends to produce better sessions even without any other content. The open questions section forces identification of unresolved design choices before the model answers them silently in implementation. As the session produces decisions, they get added. By the end of the session, the first draft of an anchor is populated from actual work rather than pre-planned rules.
The first anchor also tends to be short, which is correct. A newly started project has few settled decisions worth tracking. Anchors that start long often reflect aspirational constraints rather than demonstrated ones. Constraints that the model has not yet violated do not yet need to be in the anchor.
Decision Rot
A session anchor updated during active development but not maintained afterward becomes a liability. A session anchor from three months ago contains decisions that were relevant then, may reflect a design since changed, and will actively mislead any session that starts from it without review.
The rot pattern typically looks like this: a decision gets added to CLAUDE.md because the model kept violating the corresponding constraint. Time passes. The constraint is refactored or superseded. The CLAUDE.md entry remains. Now the model is explicitly instructed to behave in ways the codebase has moved away from.
The mitigation is maintenance triggers tied to actual code changes. When a refactor changes the database access pattern, the corresponding workspace instructions constraint gets updated in the same commit. When an ADR’s decision is reversed, the original ADR gets superseded by a new one rather than silently abandoned, using the same pattern tools like adr-tools support natively. This is the same commit discipline that makes good commit messages valuable: the documentation of the decision lives adjacent to the implementation of the decision, and changes to one prompt changes to the other.
The session anchor has a different maintenance pattern. It represents working state, not history. When a decision is complete and no longer relevant to active development, remove it from the anchor and promote it to its appropriate permanent home or simply discard it if it was tactical. An anchor that accumulates completed decisions without pruning becomes a document that no session needs to reference in full.
Team Contexts
When multiple developers share a CLAUDE.md file in version control, the workspace instructions tier gains a coordination function. A constraint added by one developer to guide their AI sessions becomes a constraint that shapes every team member’s sessions. This is a feature: shared workspace instructions ensure that AI-assisted work on the same codebase converges on the same conventions.
The coordination surface also creates a governance question. Who decides what goes in CLAUDE.md? The same people who decide what goes in the coding standards documentation, which in most teams means informal consensus or whoever has commit access. The difference is that a workspace instructions file is authoritative in a way that a wiki document often is not: the model actually reads and applies it, so the contents have operational consequences rather than aspirational ones. A stale or incorrect rule in a wiki costs a developer some confusion when they discover it. A stale or incorrect rule in CLAUDE.md actively guides AI-assisted changes in the wrong direction until someone catches and corrects it.
Session anchors, by contrast, are individual. Each developer maintains their own for their own sessions. The content may overlap when working on the same feature, but session anchors do not merge or conflict in the same way. The overlap is a signal that a decision probably belongs in the shared workspace instructions rather than in each developer’s individual session anchor.
What the Pattern Requires Over Time
The discipline context anchoring requires is not writing the document once. It is maintaining the document with the same commitment as the code it accompanies: updating it when decisions change, graduating decisions up the tier hierarchy when they earn permanence, pruning it when the session or feature it tracked is complete.
The Lost in the Middle research gave practitioners a research-backed explanation for something they had already observed: long sessions produce inconsistent results because attention distribution across long contexts is unreliable. Context anchoring is the engineering response to that specific constraint. Like most engineering responses to fundamental constraints, it requires ongoing discipline rather than a one-time setup.
The constraint is not going away as models improve. Longer context windows shift the threshold at which the problem appears but do not eliminate the attention distribution issues that make content in the middle of long windows less reliable. And longer context windows cost more per token, making the efficiency argument for a short, high-signal anchor document stronger as context windows grow rather than weaker. A maintained anchor document with high signal density is a better input than a long conversation with accumulated noise, independent of how large the context window gets. The three-tier lifecycle gives that maintenance discipline a structure that makes the ongoing work legible rather than ad hoc.