Agent 的记忆文件会过期：用 stalebrain 给 CLAUDE.md、AGENTS.md 建立可追溯的校验循环
AI 编码 Agent 的失误不总是模型能力不足。更隐蔽的一类问题来自项目里的“记忆”：CLAUDE.md 写着已经迁走的目录，AGENTS.md 还要求运行一个改名的脚本，Cursor 规则坚持用早已废弃的包管理器。它们看起来像明确指令，Agent 却会在每次会话里照单全收；结果是任务还没开始，上下文就已经偏离真实仓库。
stalebrain 是一个面向这类问题的 MIT 许可证工具。它不把规则文件当成静态文档，而是把其中的陈述拆成可检查的主张，再用当前工作树和 Git 历史寻找证据。其目标不是替你自动重写团队规范，而是回答一个更基础的问题：这条给 Agent 的说明，今天还可信吗？
为什么“把规则写进 Markdown”还不够
项目规则通常会跨越多个 Agent。Claude Code 常读 CLAUDE.md，Codex 等跨工具工作流可能读 AGENTS.md，Cursor、Copilot、Gemini CLI 也各自有规则入口。一个仓库随着重构积累多份文件时，冲突很容易出现：一份文件说用 yarn，另一份说 npm；一处写测试目录在 tests/，实际已经迁到 packages/*/test/。
普通 Markdown lint 无法判断这种描述是否符合代码现状。stalebrain 的做法是把句子按路径、脚本、符号、依赖、事实、负责人和约定等类型处理：路径是否存在、脚本是否在 package.json 或 Makefile 中定义、负责人是否能在 CODEOWNERS 或 Git 历史中找到依据。对于找不到的路径，它会借助 Git 历史追踪重命名线索，而不是只报一个“文件不存在”。
这带来一个重要边界：它校验的是可以机械验证的项目记忆，不是裁决技术偏好。“代码应该保持简洁”这类主观意见不会被伪装成失败的事实；没有可靠检查方式的内容应当明确标为不可验证，而不是由工具猜测。
先安装，再让它写入 Agent 可发现的位置
项目要求仓库有 Git 历史。推荐通过 uv、pip 或 pipx 安装；安装后，命令可以将 skill 放到用户级或当前项目级位置：
uv tool install stalebrain stalebrain install stalebrain install --project .
如果不希望安装 Python 工具，项目也提供纯 Git 的项目级方式：
git clone https://github.com/stalebrainlabs/stalebrain \ .claude/skills/stale-brain
完成后，可在支持 skill 的助手里调用 /stale-brain，或直接要求 Agent 审核项目记忆。对于不具备本地工具权限的聊天环境，项目提供 PORTABLE.md：把协议放进仓库或粘贴进对话，Agent 会退化为请求必要的命令输出和给出可人工应用的 diff，而不是假称已完成本地检查。
一次审计到底检查了什么
stalebrain 覆盖根目录与嵌套的 CLAUDE.md、AGENTS.md、.cursorrules、.cursor/rules/**/*.mdc、GitHub Copilot instructions、GEMINI.md 等多种位置。它对每项主张给出四类结果：已确认、陈旧、被证据反驳、不可验证。
“陈旧”尤其值得单独看待。项目为不同类型的事实定义半衰期，例如路径的变化速度通常快于团队约定。超过相应周期的陈述会重新验证，无法确认时降级为带日期的假设，而不是继续作为绝对命令影响 Agent。已经确认的内容可写入带日期的 provenance stamp；下次审计可以据此做增量工作，保留“何时、基于什么证据确认”的线索。
报告还会给出记忆的 token 估算、相互矛盾的跨文件规则，以及带提交依据的修正建议。这里的核心设计是 approve-only：非交互式运行不会直接改文件，每条建议都应由维护者审阅后再应用。对团队来说，这比让 Agent 静默“修好”规则更安全；规则本身往往也是架构决策的一部分。
把它放进日常维护，而不是出事后才运行
比较实用的节奏是：大型重构、脚本迁移、包管理器切换后运行一次；每隔一段时间再做一次全量检查；在关键规则文件中加一条轻量提醒。当 Agent 发现指令与现实冲突时，它应指出矛盾并建议审计，而不是强行执行旧说明。
例如，团队把“所有变更必须运行 npm run verify”写进 AGENTS.md 后，可以在重构 CI 或 scripts 时用审计确认该命令是否仍存在。若仓库已改成 workspace 级命令，保留旧规则会让每个新会话重复走错路径；改正一次规则，减少的是之后每次 Agent 调用的错误上下文和无效 token。
适用范围与取舍
stalebrain 适合多 Agent 并行、规则文件较多、重构频繁的代码库，也适合希望把“项目知识”当作可维护资产的个人项目。它不替代测试、代码审查或安全扫描：它验证的是 Agent 获得任务上下文之前的事实基础。Git 历史很浅时，重命名和演进证据会变弱；此时应保守看待结论，而不是把没有历史的仓库当成没有变化。
真正有价值的结果不是报告里多了一个健康度百分比，而是团队停止把过期 Markdown 当成可靠接口。给 Agent 的每条可执行说明都能追溯、会衰减、可复核，Agent 才更可能在正确的约束下开始工作。它也让规则维护从“有人想起来才更新”的手工习惯，变为有证据、能回看、可逐步收敛的工程活动。
在 CI 或例行任务中怎样使用才不制造噪声
把记忆审计接入工程流程时，不建议把它设计成“发现任何变化就阻断合并”的硬门禁。规则文件的很多内容来自人类协作，变更可能是正在进行的迁移，也可能是尚未写入代码的决定。更合理的做法是分层处理：本地开发阶段让 Agent 在开始任务前执行审计；拉取请求中把报告作为可阅读的附件；只有能被直接证据反驳的路径、脚本、依赖和安全约束，才进入必须修复的检查清单。
一个可复现的人工复核流程可以是：先阅读被标为 CONTRADICTED 的条目和关联提交，确认工具识别到的是实际迁移而不是临时分支差异；再检查 STALE 条目是否仍应作为项目约定保留；最后将同意的修复合并到相应的 CLAUDE.md、AGENTS.md 或规则文件。这样，审计输出成为维护文档的待办队列，而不是一台未经授权的批量改写器。
跨文件冲突也应按优先级处理。比如根目录 AGENTS.md 要求执行全库测试，而某个子包的 CLAUDE.md 规定只运行该包测试，二者不一定矛盾；它们可能只是缺少适用范围。修复时应补充目录边界和命令前提，例如明确“修改 packages/api 时运行对应 workspace 命令”，而不是机械删除其中一条。对 Agent 来说，带作用域的精确指令比泛化的口号更能减少误操作。
先识别失败模式，再决定是否值得引入
这类工具无法保证所有结论都正确。Git 历史被压缩、重写或浅克隆时，工具能用来解释路径迁移的证据会减少；生成式配置、动态脚本和外部平台权限也可能没有可本地验证的依据。此时“不确定”是比强行给出通过或失败更好的结果。维护者应该把 UNVERIFIABLE 当作需要补充来源、注释或可观察性的信息缺口，而不是要求工具凭经验补全。
另一个常见误区是把版本化记忆当作替代运行时验证。即使 CLAUDE.md 中的测试命令被确认存在，也不表示它本次一定通过；即使路径仍存在，也不代表 API 的语义没变。stalebrain 的位置在于降低 Agent 从错误事实起步的概率，后续仍需要测试、类型检查、代码评审与部署前检查共同兜底。
对于规模很小、规则只有几行且几乎不重构的仓库，引入完整审计流程未必划算。反之，只要项目同时维护多个 Agent 入口、多人频繁修改构建脚本，或曾经遇到 Agent 被旧指令带偏，建立一次可追溯基线通常就足够有收益。先从项目级安装和一次只读审计开始，观察哪些记忆最容易失效，再决定是否扩展到团队例行流程。