为什么 AI 让“过度文档化”成为你的新秘密武器

I’m unable to retrieve the content from the external link. Could you please paste the text you’d like translated here? Once I have the article’s text, I’ll translate it into Simplified Chinese while preserving the source line, formatting, markdown syntax, and technical terms as you requested.

系统随时间的退化

每个系统都会随时间退化。这是普遍现象——日本、美国、欧洲……地点并不重要。

问题不在于系统是否会退化，而在于为什么会退化。

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.

每一次更改都是“正确的”。但那些与最初意图不一致的更改累计起来，就会毁掉系统。

---

AI让情况更糟，而不是更好

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

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

AI 加速了产出，但它 并没有加速理解。

• “AI 写的，应该没问题” → 监督力度下降
• 更快的代码生成 → 更快累积没有意图的更改
• 会话重置 → AI 不记得为什么做出某些决定

AI 是一个出色的“手”。它不是“记忆”。

为什么大多数 AI 讨论忽略了这一点

大多数开发者仍停留在“哇，好快！”的阶段。问题只有在几个月的真实使用后才会显现——当你试图理解某个实现方式的 原因 时，才会发现没人知道。

解决方案：将决策视为基础设施

关键洞见： AI 记不住，但 AI 能阅读。

AI 之前

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

人类实际上不可能阅读数月的决策历史，因此很少保留详细记录。

AI 之后

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

新架构

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

关键原则（借鉴自档案管理员）

这些并非新概念；图书馆和政府数十年来一直在使用它们。我们只是把它们应用到代码上。

什么被记录

每个决策包括：

• 什么 被决定
• 为什么 被决定
• 什么 与之前不同
• 什么 仍然未决

什么 不 被记录

• 会话日志
• 头脑风暴
• 失败的尝试
• 探索

探索是被允许的。持久化则不被允许。

关键规则：将探索与决策分开

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

对 AI 来说，所有写下的内容都同样是“真实”的。如果将探索与决策混在一起，被拒绝的想法会重新出现，成为有效选项。

新人如何学习系统

旧方式

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

新方式

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

新手不再需要去寻找“专家”。专家的决策已保存在系统结构中。

为什么现在才有效

文档可以被编写，但无法被阅读。AI 改变了这一点。

范式转变

# 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  

为什么没人谈论这个

• 时间视野太短 — 大多数 AI 讨论聚焦于单次会话
• 对话中的人选错误 — 市场营销人员和研究员，而非维护工程师
• 问题需要时间才能显现 — 你要到 6 个月以上才注意到
• 需要跨领域知识 — AI + 软件工程 + 档案思维

底线

AI 并不能拯救你的系统免于成为无人理解的遗留系统。

结构会。

问题不在于 “我该如何更好地使用 AI？”
问题在于 “我需要什么基础设施，才能让意图在时间、人员和 AI 会话之间得以保存？”

答案

• 决策（而非会话）成为历史
• Git 是唯一的权威
• AI 生成并读取记录
• 人类进行验证并做出取舍决策

这就是系统能够超越最初构建者而存续的方式。

本文是关于结构化方法在 AI 辅助开发中优于提示优化的持续探索的一部分。如果你对实际实现感兴趣，请查看我的 “Context as Infrastructure” 系列。

你如何在系统中保留意图？