The most common failure mode in AI-assisted coding isn’t bad generation; it’s context fragmentation. A recent discussion on r/ClaudeCode highlighted a workflow where developers maintained a separate 'planner' chat in claude.ai Projects while building in Claude Code, resulting in a manual 'copy-paste tax' where humans acted as the bus between the decision log and the codebase. The solution, according to developer r3dtuxedo, is to abandon the separate chat project entirely and move specifications and Architecture Decision Records (ADRs) directly into the repository, wiring them into AGENTS.md so that planner, builder, and reviewer agents operate on the same source of truth.

The Cost of Context Drift

When decisions live in a chat log and code lives in the editor, three specific costs emerge: attention, drift, and blind reviews. Every time a developer pastes a plan into a tool or a result back into a chat, they consume cognitive bandwidth. Worse, the decisions log is often updated after a merge, creating a window where the two sources disagree; if an agent follows the stale version, it confidently implements the wrong logic. A reviewer that only sees a diff can assess code quality but cannot verify if the code matches the agreed-upon decision, because the decision itself isn’t in its context.

Specs vs. ADRs: Know the Difference

The author distinguishes between two file types that must live in the repo: specs and ADRs. A spec is temporary and feature-specific, containing goals, acceptance checks, and status; it is archived once the feature ships. An ADR, based on Michael Nygard’s 2011 format, is durable and captures a single architectural decision (e.g., 'Use Postgres RLS for tenant isolation') with Context, Decision, Status, and Consequences. Crucially, if a decision is reversed, the old ADR is marked 'Superseded' rather than deleted, allowing agents to read both the history and the current rule. Tools like adr-tools or Archgate can automate the creation and validation of these files, with Archgate even allowing CI to block merges if code violates an ADR’s associated rules.

Wiring It Into AGENTS.md

Files in docs/ are inert until agents are instructed to read them. This is the primary role of AGENTS.md, an open format for coding agent instructions. While Claude Code traditionally reads CLAUDE.md, recent versions support AGENTS.md directly, provided there is no CLAUDE.md on the path. To share a single source of truth, developers should use an import directive (@AGENTS.md) at the top of CLAUDE.md. Anthropic recommends keeping these files under 200 lines; rather than importing every ADR, the AGENTS.md file should contain an index and a rule that tells the agent to open only the specific ADRs linked in the current feature’s spec.

Decision-Aware Reviews

The most significant gain is in the review phase. A generic AI review asks 'is this code reasonable?' A decision-aware review, powered by a subagent configured in .claude/agents/adr-reviewer.md, asks 'does this diff satisfy the spec’s acceptance checks and violate any linked ADR?' This shifts the review from subjective style comments to objective constraint checking. For example, a reviewer can flag 'this query bypasses the RLS rule in ADR 0007,' which is a binary true/false condition. However, the author notes a limitation: while per-task reviews catch local defects, a final whole-branch review is still necessary to catch interactions between tasks, and humans must always approve new ADRs to prevent agents from quietly lowering their own standards.

Key Takeaways

  • Move specs and Architecture Decision Records (ADRs) from external chat logs into the repository to eliminate the 'copy-paste tax' and prevent context drift between planner and builder agents.
  • Use AGENTS.md (imported via @AGENTS.md in CLAUDE.md) to instruct agents on when to read specific ADRs linked to the current feature's spec, keeping the context window focused and deterministic.
  • Implement decision-aware reviews using a dedicated subagent that checks diffs against spec acceptance criteria and linked ADRs, turning subjective style comments into objective constraint verification.
  • Treat ADRs as durable, version-controlled artifacts: never delete superseded decisions, and require human approval for new ADRs to prevent agents from quietly relaxing architectural standards.

The Bottom Line

Stop treating your architecture decisions as ephemeral chat history. By forcing specs and ADRs into the repo and wiring them into your agent’s context window, you turn 'past plans between windows' into a deterministic, checkable workflow. The first time your reviewer catches a violation of ADR 0007, you’ll never go back.