Why AI Makes "Over-Documentation" Your New Secret Weapon

I once asked AI to refactor a module. Six months later, nobody knew why that layer existed—not even me.

In the pre-AI era, we were taught that "the code is the documentation" because writing and reading docs was too expensive.

AI just changed that fundamental math.

But here's what nobody is talking about: AI is an incredible "hand" for writing code, but it has zero "memory" of why that code exists. In 6 months, your AI-assisted codebase won't just be complex—it will be a place where even the AI can't explain the original intent.

The real bottleneck in development is no longer code generation. It's intent inheritance.

This article explores how to apply time-tested archival principles to AI development—so your system survives its original builders.

---

The Degradation Pattern Is Universal

Every system degrades over time. This is universal. Japan, US, Europe—doesn't matter.

The question isn't whether systems degrade. The question is why.

Initial build:  Coherent design with clear intent
     ↓
Change 1:       "Working" fix by someone who doesn't know the intent
     ↓
Change 2:       Fix to accommodate Change 1
     ↓
Change 3:       "Don't know why, but it breaks without this"
     ↓
Critical mass:  Nobody understands the whole system
     ↓
End state:      Touch it and it breaks. Don't touch it and it rots.

Each change is "correct." But the accumulation of changes that don't align with the original intent kills the system.

AI Makes This Worse, Not Better

Before AI:
  Code generation ████░░░░░░  Quality check ████░░░░░░

After AI:
  Code generation ██████████  Quality check ████░░░░░░
                                    ↑
                              Still the same

AI accelerates production. It doesn't accelerate understanding.

Worse:

• "AI wrote it, so it's probably fine" → less scrutiny
• Faster code generation → faster accumulation of intent-less changes
• Session resets → AI doesn't remember why decisions were made

AI is an excellent "hand." It's not a "memory."

Why Most AI Discussions Miss This

What people discuss	What actually matters
Prompt optimization	Keeping "why we decided this" alive
Single-session productivity	Multi-month continuity
Code generation speed	Intent inheritance
Model capabilities	Structural design

Most people using AI for development are still in the "wow, this is fast!" phase.

The problem only becomes visible after months of real use—when you try to understand why something was built a certain way, and realize nobody knows.

The Solution: Decisions as Infrastructure

The key insight:

AI can't remember. But AI can read.

This changes everything.

Before AI

Records exist → Humans read them → Understanding → Action
                     ↑
                 Bottleneck (too slow, too much)

Humans couldn't realistically read through months of decision history. So we didn't bother keeping detailed records.

After AI

Records exist → AI reads them → Explains to humans → Action

AI makes "reading" cost zero. So now we can record everything.

The New Architecture

Human + AI → Decision → History (Git)
                           ↓
                      (Persists)
                           ↓
New person + AI → Reads history → Reconstructs intent

Key principles (the same ones archivists use to preserve historical documents):

Principle	Meaning	Implementation
Authenticity	Record is what it claims to be	AI generates, human only verifies
Reliability	Content is trustworthy	Only decisions enter history (not exploration)
Integrity	Not tampered with	Git is the single source of truth
Usability	Can be found and understood	Structured decision diffs

These aren't new ideas. They're how libraries and governments have preserved important records for decades. We're just applying them to code.

What Gets Recorded

Every decision includes:

• What was decided
• Why it was decided
• What changed from before
• What remains open

What does NOT get recorded:

• Session logs
• Brainstorming
• Failed attempts
• Exploration

Exploration is allowed. Persistence is not.

The Critical Rule: Separate Exploration from Decisions

Session log:     Exploration + failures + decisions + chat → all mixed
Decision history: Decisions only → single authoritative past

To an AI, everything written is equally "real." If you mix exploration with decisions, rejected ideas will resurface as valid options.

How New People Learn the System

Old way:

New person → Reads documentation → Asks senior engineer → Maybe understands

New way:

New person → Asks AI: "Why is this designed this way?"
AI → Reads decision history → Explains with context

The new person doesn't need to find the "expert." The expert's decisions are preserved in the structure.

Why This Only Works Now

Before AI:

• Writing decision logs was tedious → people skipped it
• Reading decision logs was slow → people asked colleagues instead
• Searching for relevant decisions was hard → knowledge stayed in heads

After AI:

• AI generates decision logs automatically
• AI reads and summarizes instantly
• AI finds related decisions by meaning, not keywords

Documentation could be written. It couldn't be read. AI changed that.

The Paradigm Shift

Old thinking	New thinking
AI is a "tool"	AI is an "interface" to knowledge
Documentation is for humans	Records are for AI to read
Handoff is person-to-person	Handoff is structure-to-AI-to-person
Less documentation is better	Record everything, AI extracts what's needed

Why Nobody Talks About This

1. Time horizon is too short — Most AI discussions focus on single sessions
2. Wrong people in the conversation — Marketers and researchers, not maintenance engineers
3. Problem takes time to appear — You don't notice until 6+ months in
4. Requires cross-domain knowledge — AI + software engineering + archival thinking

The Bottom Line

AI won't save your system from becoming legacy nobody understands.

Structure will.

The question isn't "how do I use AI better?"

The question is "what infrastructure do I need so that intent survives across time, people, and AI sessions?"

The answer:

• Decisions (not sessions) become history
• Git is the single authority
• AI generates and reads the records
• Humans verify and make trade-off calls

This is how systems survive beyond their original builders.

---

This article is part of an ongoing exploration of how structural approaches outperform prompt optimization in AI-assisted development. If you're interested in the practical implementation, check out my "Context as Infrastructure" series.

---

How do you preserve intent in your system?