这是【DSH 工程哲学】系列的第二篇。在第一篇《跳出工具调用执念》中，我确立了“编写权让渡与裁判权收拢”的底线原则。但当开发者真正开始让 Agent 大规模接管复杂工程时，最先遭遇的幽灵并不是编译报错，而是模型的失忆与反复——两周前全团队刚推翻的错误方案，换个会话后被 Agent 兴高采烈地重新写了出来。本篇直面这一致命瓶颈，拆解 DeepSeek Harness 如何用双轴 ADR（Agent Notes）与冷冻退场机制，为 AI 原生项目铸造长期记忆。
你是否经历过这样的绝望时刻？
在会话 A 中，你与 Agent 辩论了半小时，最终确定了方案的严重隐患并断然否决；然而两周后，开启了新会话的 Agent 面对相似的需求，又把那个已被否决的方案一字不差地写进了代码库，并附带了一段无比真诚、看似无懈可击的解释。
在传统的软件工程里，这种“幽灵方案反复复活”的现象被称为沟通断层；但在由编码代理主导的工程体系中，这是最致命的系统性危机——Agent 拥有惊人的生成速度，却只有金鱼般的持久记忆。
很多团队试图用更大的上下文窗口（Context Window）或聊天记录摘要来对抗失忆。但事实证明，聊天窗口是转瞬即逝的沙滩，浪潮一过便了无痕迹。代码库真正需要的，是一套被纳入版本控制、受物理门禁捍卫的决策黑匣子。
一、第一性原理：P1 记忆瓶颈原理
在 DeepSeek Harness 源码库 的方法论体系中，最基础的第一性原理即是 P1 记忆瓶颈原理（Memory Bottleneck）：
代码只承载“是什么”（What）；团队真正丢失的是“为什么这样”（Why）和“为什么不那样”（Why Not）。 任何只存在于人脑、聊天记录或 PR 线程里的决策，都会随人员流动与上下文重置而瞬间蒸发。
代码本身是一具干瘪的骨架。它记录了一个函数接收什么参数、返回什么类型；但它从未记录：
- 为什么选择了方案 A 而不是更直观的方案 B？
- 方案 B 的致命缺陷究竟是什么？
- 未来如果出现什么新条件，方案 B 才可以被重新考虑（复活条件）？
一旦这些信息丢失，后来介入的无论是新员工还是新会话的 Agent，都会不可避免地跳入同一个陷阱。为了解决这一痛点，DSH 放弃了零散的 Issue 讨论，将架构决策记录（ADR）泛化为一种覆盖所有非平凡变更的工程载体——Agent Notes。
flowchart TD
subgraph P1["P1 记忆瓶颈原理"]
A[Git 源码] -->|仅承载| B["代码现状是什么 (What)"]
C[人脑与会话] -->|极易流失| D["为什么这样做 (Why)"]
C -->|彻底丢失| E["为什么不那样做 (Why Not)"]
end
subgraph Defense["DSH 长期记忆防御"]
F[Agent Notes 决策载体]
B --> F
D -->|强制 Decision 节| F
E -->|强制 Alternatives considered 门禁| F
end
classDef primary fill:#2563eb,stroke:#1d4ed8,color:#ffffff
classDef soft fill:#f8fafc,stroke:#cbd5e1,color:#0f172a
class F primary
class A,B,C,D,E soft
二、双轴路径设计：把标签做进物理路径里
在很多团队的文档管理中，最常见的腐化是“文档标签与实际内容漂移”：文件 frontmatter 里明明写着 status: active，但正文里却写着“已被替代”；或者在表格里打着勾，实际代码早已删除。
DSH 采用了一种极度硬核的解决方案——双轴路径设计（Dual-Axis Path）：
将记录的两个维度直接编码进文件系统的物理路径中：
{lifecycle}/{class}/yyyy-mm-dd-topic-title.md
1. 状态轴（Lifecycle）
proposed/（提案中）：决策尚未实施或正在审校阶段；implemented/（已落地）：当前活跃的权威事实，正文随源码同 PR 更新；rejected/（已否决）：明确被否决的提案，永久保留以防止后人重蹈覆辙；archived/（冻结归档）：退场的历史事实，永久封印。
2. 类别轴（Class）
来自封闭集合（由 scripts/agent-note-tree.ts 强校验）：
feature：新引入的用户/模型可见能力；bug-fix：缺陷修复与事故复盘闭环；architecture：交付源码的结构设计、包边界与运行时契约；process：工具链、门禁规则、包管理策略；testing：测试策略与质量套件；simplification：移除冗余代码、缩小表面积（重构不单设类别，属于此类）。
文件夹即标签（Folder-as-Tag）。分类和状态直接是物理路径本身，从根源上消除了“元数据与物理位置不一致”的伪状态。
三、状态机流转与 Alternatives considered 硬门禁
在 DSH 中，写 ADR 不是写随笔，每一篇 Active Note 都必须经历严格的机器语法与结构门禁：
stateDiagram-v2
[*] --> proposed: 提出变更提案
proposed --> rejected: 审校否决(记录Verdict)
proposed --> implemented: 落地并同提交改写
implemented --> archived: 决策闭合且不指导未来(哈希封印)
rejected --> [*]
archived --> [*]
1. 转换即改写（Status Transition is a Rewrite）
当一个提案从 proposed/ 移入 implemented/ 时，绝不仅仅是 git mv：
scripts/verify-agent-note-format.ts强制检查：提案时的将来时标题（如## Proposal/## Plan）严禁出现在 implemented 状态中；- 必须原地重写为代表当前事实的现在时
## Decision，验收清单与风险必须收拢至## Consequences。
2. Alternatives considered 强制门禁
在任何一篇决策记录中，必须显式包含 ## Alternatives considered（被考量的替代方案）小节。
门禁脚本会通过正则与 AST 严格扫描这一节的存在性。“不记录落选方案的决策，是在邀请团队重开争端。” 每一项被否决的备选方案，都必须阐明“为何不那样做”，从而在物理上切断 Agent 日后“幽灵复活”该方案的可能。
四、退场的艺术：archived 永久冷冻与哈希封印
许多技术团队的 ADR 库最终退化为垃圾堆，原因在于没有解决退场机制。当代码库演进到数万次提交时，过期的决策会混杂在搜索结果中，成为干扰大模型与人类的陈旧噪音。
DSH 独创了工业级的第三态——archived/ 永久冷冻归档：
- 严格归档判据：只有
implemented能够归档。归档意味着该决策已经彻底闭合，且其推理上下文不再指导未来研发；如果涉及核心安全边界、持久协议或易复发缺陷，必须永久保持 active。 - 物理隔离与搜索屏蔽：
.rgignore显式将archived/排除在常规代码检索之外，防止全局 grep 搜出作废的历史事实误导 Agent。 - SHA-256 内容哈希封印：
在
scripts/verify-archived-agent-notes.ts门禁中，每一个被归档的 Notes 三件套（英文 + 中文 + i18n 配置）都会计算其内容的 SHA-256 指纹，并永久封印进manifest.json。 CI 门禁在每次运行时强制校验：已归档的文件不仅禁止修改，甚至连一个字节的空格变动都会直接触发非零退出。
五、从原理到实践：明天就能用上的落地动作
不要被 DSH 数百篇 Notes 的庞大规模吓退。作为向 AI 全栈转型的中基层工程师，你可以在自己的项目中用 10 分钟 建立第一道记忆防线：
- 建立最小目录：在项目根目录创建
.agents/notes/，下设proposed/、implemented/与rejected/三个目录； - 立下第一条团队铁律：凡是非平凡变更（接口变动、引入新依赖、修改构建规则），必须在同一次提交（Same-Commit）中提交一份最小 Notes，必须包含两句话：
- Why：为什么必须这样改；
- Why Not：有哪些想到的候选方案，分别因为什么理由放弃。
- 把 Notes 变成 Agent 的必读输入：在你的
AGENTS.md规则中写入一条简单指示：“在执行任何涉及架构与核心逻辑的任务前，必须先检索.agents/notes/中相关决策”。
让 Agent 负责高速生成，让 ADR 守住决策记忆。唯有当每一次取舍都被物理锚定，AI 原生工程才不再是一场在流沙上建高楼的危险赌博。
🛠️ 本课哲学的实证落地：作为 AI Coding 工程质量控制元框架，PonyGo 将上述“双轴决策记忆与退场机制”沉淀为开箱即用的命令行工具。通过内置的
write-adr规范与ponygo audit生命周期自检，现代代码库可以零成本建立起对标 DSH 的物理级决策记忆闭环。实践参考：https://github.com/lanhui100/ponygo