仓库记忆，是 Coding Agent 的长期复利

Coding Agent 每次进入陌生仓库，都要重新发现项目做什么、如何构建、哪些模式是刻意保留的、哪些目录风险最高。模型再强，这段重复侦察也会消耗时间并制造不一致。

仓库记忆的作用，是把团队已经付过代价得到的认知留在代码旁边。AGENTS.md、CLAUDE.md、Copilot instructions 和 ADR 等机制，正在把构建命令、约定与架构意图变成机器可读取的资产。

仓库记忆应按作用域在执行时逐层装载。根目录保存全局构建与安全边界，模块附近记录局部契约，ADR 解释跨模块决策，脚本与测试提供可执行事实；Agent 先根据任务路径检索相关内容，再用当前代码验证它们是否仍成立。这样的记忆不是一次塞满上下文，而是在需要时提供最小、可信的约束集合。检索命中后仍需标明优先级，防止说明文字覆盖更可靠的运行结果。

但把所有历史聊天塞进上下文并不是记忆。未整理的记录会相互冲突、迅速过期，并把真正重要的规则淹没。有效记忆需要结构、作用域、来源和更新责任。

记忆也会制造路径依赖。旧决策被写得过于绝对，新方案可能还没比较就被排除；多个说明文件若互相冲突，模型常会选择措辞更强而非更新更近的一份。自动沉淀聊天内容更危险，因为临时猜测会伪装成团队规则。没有来源、日期、责任人和失效条件的记忆，很容易成为规模化偏见。规则应允许提出异议，否则记忆会阻止团队修正已经变化的现实。

第一层应是稳定规则：技术栈、目录职责、不可违反的安全边界和标准验证命令。第二层是局部规则，随目录或模块加载。第三层才是任务相关历史，通过搜索按需取回。

记忆还必须可验证。写着“运行测试”的说明不如给出准确命令和成功条件；写着“保持兼容”的原则不如列出公共 API 和契约测试。能够被机器检查的事实，优先级高于只能被解释的口号。

维护质量可以通过真实任务检验：新 Agent 是否无需口头补充就能找到正确命令，局部规则能否只影响相关目录，过期指令是否会在 CI 中暴露，架构例外是否能追溯到决策背景。团队还应定期删除已被代码和测试表达的重复文字，让文档关注无法从实现直接推断的意图。这类测试比统计文档数量，更能说明记忆是否真的降低了探索成本。

过期是最大风险。仓库指令如果仍指向已删除脚本，会系统性地误导每一次执行。团队应把关键指令纳入代码审阅，在工具链变化时同步更新，并用 CI 检查链接和命令。

长期看，最有价值的仓库会形成“执行—纠正—沉淀”的闭环：事故教训变成检查，重复解释变成局部文档，成功路径变成脚本。Agent 的每次工作都在增加下一次的确定性。

仓库记忆的本质，是把一次协作中的昂贵解释转化为未来执行的公共资本。它并不追求让 Agent 知道所有历史，而是确保关键约束在正确时刻被发现、质疑和更新。真正的复利来自纠错速度：每次失败不仅修当前补丁，还降低同类误解再次发生的概率。因此删除、合并和标记过期，与新增知识具有同等重要的价值。知识治理因此是一项持续维护工作。

所以仓库记忆的壁垒不在容量，而在知识治理。谁能把隐性经验持续转化为精确、分层、可测试的约束，谁就能让不同模型和不同 Agent 都获得稳定复利。

记忆的检索策略与内容同样重要。若每次都加载全部规范，关键指令会被长上下文稀释；若只按关键词搜索，又可能漏掉目录继承和架构依赖。系统应结合文件路径、变更类型和引用关系选择材料，并在执行摘要中列出实际采用的规则，让审阅者能发现缺失或错误优先级。被忽略的规则也应在审阅阶段快速补回索引。

《仓库记忆，是 Coding Agent 的长期复利》落到工程现场，第一步不是让 Agent 改代码，而是让它读懂变更的边界：仓库规则、相关模块、兼容约束、测试入口和不可触碰的区域。一个能解释“为什么只改这些文件”的系统，通常比能一次写出大量代码的系统更值得进入团队流程，因为它已经把修改控制在可审阅的单位里。

最危险的假成功是检查变绿但系统质量下降。Agent 可能删除断言、放宽类型、绕开错误分支，或为满足局部任务而引入无关耦合。评测因此应包含反向样本：故意给出不完整需求、过时文档和冲突约束，观察它是否会扩大改动范围、掩盖不确定性，还是能够留下明确的验证缺口。

历史教训最好沉淀为多层资产。事故背景与取舍进入 ADR，重复修复步骤进入脚本，不能再次发生的行为进入测试，暂时注意事项才留在文字说明。把所有知识都写成长文档，会要求模型反复解释；把可执行部分下沉到工具链，才能在不同模型和成员之间稳定复用。每种载体承担不同寿命和验证强度的知识。并减少歧义。

有效指标应沿交付链采集，而不是停在代码生成量：首次可审阅差异的时间、测试与评审的返工次数、合并后回滚率、未解决告警，以及维护者解释变更的成本。若吞吐增加但审阅负荷和故障恢复同步上升，自动化只是把成本推迟到了更昂贵的环节。

仓库记忆也需要退出机制。决策达到失效条件、模块被删除或技术栈迁移后，相关规则应被标记、归档或移除，并检查是否仍被其他文档引用。没有删除流程的知识库只会单向膨胀，最终让新 Agent 花更多时间解决规则冲突。高质量记忆的标志不是保存最多，而是当前信息密度最高。删除旧记忆能够直接提高下一次检索的可靠性。

要让系统持续进步，团队需要把人类反复提出的意见转化成可执行资产：目录级规则、测试夹具、静态检查、脚本和架构决策记录。这样每一次审阅不只是纠正当前补丁，也会减少同类错误再次出现的概率。Agent 最有价值的作用，是促使组织把隐性工程知识写成机器和新人都能遵守的约束。

因此，软件 Agent 的终点不是替代写代码的人，而是提高可信变化的供给。实现文本会越来越便宜，需求边界、运行环境、验证证据和责任归属仍然稀缺。能把这些稀缺要素组织成稳定、可复用的工作流的团队，才会真正把模型能力转化为交付速度。