§ 01 — The Irony: Faster Development, Faster Decay
The legacy codebase problem has always been understood as something that happens over years. A system built in 2015 accumulates undocumented decisions, tribal knowledge, dependency rot, and inconsistent patterns gradually — the slow erosion of context that made the system comprehensible when it was fresh. The conventional wisdom was that you had at least three to five years before a greenfield project became genuinely difficult to maintain.
AI-assisted development has compressed that timeline dramatically. Teams building with agentic tools in 2026 are reporting context debt — the accumulated gap between what the system does and what’s documented about why — within six months of starting a new project. Some are experiencing it within weeks.
The mechanism is counterintuitive: the very speed that makes AI-assisted development so productive is what creates the problem. When an AI agent can scaffold a service in an afternoon and wire up integrations in a morning, the code moves faster than any human can document it. The decisions that would have been recorded in ADRs during a two-week implementation sprint are made and forgotten in a two-hour session. The context that existed in the original session window evaporates at session end. The codebase that remains is technically functional and institutionally opaque.
“Traditional legacy code took years to become unmaintainable. AI-accelerated development can produce the same result in a quarter — at ten times the scale.”
§ 02 — The Mechanism: How AI-Assisted Greenfield Becomes Legacy
Understanding how this happens requires tracing the specific ways that AI development erases the context trail that makes codebases maintainable.
Session Context Never Leaves the Session
In traditional development, the process of building something — even quickly — tends to generate artifacts that record decisions: commit messages that explain why (not just what), comments written in the moment of solving a hard problem, PR descriptions that summarize the approach. These artifacts are imperfect and incomplete, but they exist as residue of the decision-making process.
In AI-assisted development, the primary locus of decision-making is the session conversation — a dialogue between engineer and agent that exists entirely within the context window. The decisions made in that conversation — which approach to take, which alternatives were rejected, which constraints were established — live in the chat history. When the session ends, that history is archived at best, gone at worst. The code it produced contains no record of the reasoning behind it.
The Vibe Coding Documentation Gap
The practice informally called “vibe coding” — using natural language prompts to generate code without deep review of the output — produces functional code with zero accompanying rationale. The engineer asked for something, the agent produced it, it worked. What the engineer does not know — and what no document records — is why the agent made the implementation choices it made. Which pattern it used and why. What it assumed about the calling environment. What constraints it inferred from context that weren’t explicitly stated.
Six months later, when someone needs to modify the code, they face the same problem as someone maintaining legacy code: a system that works by convention and inference, where the conventions aren’t written down and the inferences aren’t recoverable.
CONTEXT ACCUMULATION: TRADITIONAL vs AI-ASSISTED DEVELOPMENT Traditional Development (12 months): ├── Week 1-2: Architecture spike → ADR written +context ├── Week 3-6: Implementation → PR descriptions + comments +context ├── Month 3: First incident → postmortem + annotations +context ├── Month 6: Refactor → migration guide written +context └── Month 12: System well-documented. New eng productive in 2 weeks. AI-Assisted Development (12 months): ├── Day 1-3: Architecture in AI session → session ends -context ├── Week 1-2: Implementation in sessions → sessions end -context ├── Month 1: Feature complete. No docs. No ADRs. No why. (gap) ├── Month 3: Second team member asks “why does this work?” confusion ├── Month 6: Original engineer leaves. System opaque. crisis └── Month 12: Effectively legacy. Cannot safely modify.
Inconsistency at AI Speed
Traditional teams accumulate inconsistency slowly, through the gradual divergence of conventions as different engineers make different choices over time. AI-assisted teams can accumulate inconsistency rapidly, because each session begins without memory of prior sessions and generates code from whatever patterns are most prominent in the current context.
A team of five engineers running separate AI coding sessions against the same codebase — without a shared, persisted context layer — will produce a codebase where five different conventions co-exist. The AI in each session inferred patterns from whatever context was loaded. Those patterns may differ. The resulting codebase looks like the output of five different teams rather than one.
§ 03 — The Standard: Context Infrastructure as Day-One Practice
The mistake teams make is treating context infrastructure — AGENTS.md, ARCHITECTURE.md, decision registries, inline annotations — as remediation work for legacy codebases. This framing is understandable: the articles and tools discussing context documentation emerged in response to the legacy problem. But context infrastructure is not a cleanup task. It is a foundation task.
Building context infrastructure at the start of a project costs almost nothing — a few hours of setup, a lightweight convention for ongoing maintenance. Building it six months in, when the institutional knowledge exists only in departed chat histories and the memories of engineers who may have left, costs enormously more. And not building it at all produces a new kind of legacy: not the 2015-era legacy of a slowly aging system, but an AI-era legacy of a rapidly built system with no accessible rationale.
The Day-Zero Checklist
Before your first AI-assisted session on a new project, these five artifacts should exist:
- AGENTS.md at repository root — architecture overview, forbidden zones, tech stack, conventions
- ARCHITECTURE.md — component map, data flow, ownership table, external dependencies
- Decision registry — even if empty, the file should exist with the intended schema
- Session handoff convention — the team should know how sessions end (summary format, where it goes)
- Context governance rules — what the AI is and isn’t permitted to modify without human review
None of these takes more than a few hours to draft at project inception. AGENTS.md and ARCHITECTURE.md at day zero will be short — the system is new, there’s not much to document. But having the document means decisions get recorded as they’re made rather than reconstructed after the fact. The cost is asymmetric: cheap to start, expensive to reconstruct.
The Living Update Protocol
Context infrastructure that isn’t maintained becomes misleading — actively worse than no documentation, because it creates false confidence. The update protocol needs to be frictionless enough that engineers do it during normal development, not as a separate documentation task.
Lightweight Update Protocol — add to Definition of Done # For any PR that: # - Changes module boundaries → update ARCHITECTURE.md # - Establishes a new constraint → add to decision registry # - Modifies forbidden behavior → update AGENTS.md # - Ends a significant AI session → save session handoff summary # PR template addition: ## Context Infrastructure Impact - [ ] No context infrastructure changes required - [ ] Updated AGENTS.md (section: ___) - [ ] Updated ARCHITECTURE.md (section: ___) - [ ] Added decision registry entry (module: ___) - [ ] Saved session handoff summary (location: ___)
§ 04 — The Mindset Shift: Context First, Code Second
The deepest change required is a shift in how teams think about what they are building when they build software with AI assistance. The code is not the primary artifact. The code is the output of a decision-making process — and it is that process, properly documented, that makes the code maintainable.
Traditional software development internalized this norm through hard experience with legacy systems. AI development needs to internalize it proactively, because the speed and amnesia of AI-assisted workflows will create legacy systems faster than experience-based learning can correct the habit.
The greenfield project that starts with context infrastructure is not slower than the project that doesn’t. It is the same speed — the overhead of maintaining context artifacts is minimal when built into the development rhythm from the start. But six months later, it will be dramatically more maintainable, more safely modifiable, and more valuable to new engineers joining the team.
D0
Day Zero Infrastructure
AGENTS.md, ARCHITECTURE.md, decision registry, and session handoff convention before first AI session.
PR
PR-Gated Updates
Context infrastructure updates in Definition of Done. PRs that change boundaries update docs.
∞
Session Handoff Habit
Every significant session ends with a structured summary. Decisions don’t live only in chat history.
△
Quarterly Audit
Review context artifacts for staleness quarterly. Stale documentation is worse than none.
“The best time to write your AGENTS.md was before your first AI session. The second best time is now — before you forget why anything works.”
∎
6mo
Median time for AI-assisted greenfield projects to exhibit legacy codebase symptoms without context infrastructure
Why AI Accelerates Decay
- Decisions live in session context, not in artifacts
- Session context vanishes at session end
- Vibe coding produces no rationale trail
- Multiple agent sessions produce pattern inconsistency
Day-Zero Artifacts
- AGENTS.md
- ARCHITECTURE.md
- Decision registry (even if empty)
- Session handoff convention
- Context governance rules
The Cost Asymmetry
Context infrastructure at project start: a few hours. Context infrastructure at 6 months, from memory and chat logs: days to weeks, with significant accuracy loss. Context infrastructure never built: every new session re-discovers what was decided before.