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

Source: Dev.to

System Degradation Over Time

Every system degrades over time. This is universal—Japan, the US, Europe… it doesn’t matter where.

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, but it doesn’t accelerate understanding.

• “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 is not a “memory.”

Why Most AI Discussions Miss This

Most developers 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

Key insight: AI can’t remember, but AI can read.

Before AI

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

Humans couldn’t realistically read months of decision history, so detailed records were rarely kept.

After AI

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

AI makes “reading” cost zero, so we can now record everything.

The New Architecture

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

Key Principles (borrowed from archivists)

These aren’t new ideas; libraries and governments have used them 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 no longer needs to hunt for the “expert.” The expert’s decisions are preserved in the structure.

Why This Only Works Now

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

The Paradigm Shift

# 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

• Time horizon is too short — Most AI discussions focus on single sessions
• Wrong people in the conversation — Marketers and researchers, not maintenance engineers
• Problem takes time to appear — You don’t notice until 6+ months in
• 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?