代码Agent的技能文档会随时间腐化失效,解决方案是将指令按变更频率分为三层:项目级常量(硬约束)、命令(中等频率)、本地约定(高频),分别用不同机制维护,防止Agent无声地执行过时流程。
上个月,我发现我的编程 Agent 正在认真地解释如何通过手动复制粘贴到网站上来发布文章——我早在几个月前就写好了这个操作的脚本。但它的项目文件里有一行仍然描述着旧的手动流程,而 Agent 完全置信地遵循了那一行,每次会话都是如此。没有任何报错。它只是礼貌地、不可见地错了。
这就是没有人警告过你的失败模式。过期插件会崩溃,过期指令会被遵循。
修复方法不是更好的文件,而是把 Agent 的指令按一个问题的答案分成三层:这东西多久变一次? 然后给每层配备不同的机制。混淆变化频率就是我所有腐坏的根源。
一份 Agent 每次会话都会读取的简短项目文件。包含约定、命令、硬约束。我的文件按上面的问题来组织,而非按主题:
# Project
## HARD CONSTRAINTS <- 几乎不变;违反这些是 bug
- 不得发布任何关于 <雇主> 或其产品的内容。
- 文章不加 AI 披露行。
## Commands <- 工具变化时改变
- 检查草稿: node scripts/aiscan.js drafts/<slug>/index.md
- 发布: python3 scripts/publish.py published/<slug>/index.md --publish
- 封面图: python3 scripts/make_cover.py --kicker ... --out drafts/<slug>/cover.png
## Layout <- 结构变化时改变
- drafts/<slug>/index.md gitignored,仅本地
- published/<slug>/ 被追踪;图片的原始 URL 来源
我执行的规则:如果这里面的某样东西每月变化超过一次,那它就在错误的层。简短且稳定意味着 Agent 实际上会遵循它,而不是在四十条规则里丢失三条真正的规则。
技能就是"如何完成一个特定任务"。它在任务变化时变化,频率高于规则但远低于会话。有两个特性阻止了我的技能腐坏。
首先:frontmatter 里的日期。技能是依赖,所以它有版本。
---
name: publish-post
description: 将草稿移到 published/,推送,然后通过 dev.to API 发布。
last_verified: 2026-09-14 # 主机或工具变化时重新检查
---
当我的工具变化时,我会重新验证重要的技能,日期告诉了我哪些值得怀疑。没有它,一个针对四个月前 API 写的技能会在每次会话中都轻微地引导错误,而且永远不会报错。
其次,也是最重要的:每个技能都要对自身输出运行真实的检查。我的写作技能不会只说"按 house style 写"然后指望运气。它会调用一个扫描器,在分数不达标时让草稿失败。这才是真正的关卡,scripts/aiscan.js:
const D = require(path.join(os.homedir(),
'.claude/skills/avoid-ai-writing/detector/patterns.js'));
const TARGET = 2.0; // 高于此值 = 重写
const text = fs.readFileSync(file, 'utf8');
const r = D.analyzeText(text); // { score, issues[], stats }
for (const i of r.issues) {
console.log(` [${i.type}] ${JSON.stringify(i.text)} => ${i.suggestion}`);
}
console.log(` VERDICT: ${r.score > TARGET ? 'REVIEW / REWRITE' : 'PASS'}`);
process.exit(r.score > TARGET ? 1 : 0); // <- 这行让它成为一个关卡
最后一行是整个设计。它以非零退出,所以技能的流程不会在草稿失败后继续。没有验证步骤的技能是在信任基础上遵循的指令。技能可能出错,但检查会捕获它。
此刻 Agent 面前的任务:它正在处理的文件、我要求的内容、检索到的上下文。每次会话都变化,而且绝对不能向上渗透。一旦会话细节被"为了下次"写入技能,腐坏就开始了,因为它曾经是真的,而且会被永远假定为真。
所以晋升是刻意的,绝不是复制粘贴的本能反应:
会话笔记 ──(仅今天为真)──> 留在对话中,随对话消亡
──(每次都为真)──> 晋升为第一层规则,或带日期的第二层技能
当 Agent 做错了某事,本能反应是修复输出。付出红利的习惯是问哪一层失败了,然后修复那一层:
修复输出,你修复一次。修复层,它停止 recurrence。
我的写作技能的验证步骤读取整个草稿文件,包括顶部我保存 review notes 的 HTML 注释块。我曾在那个注释里方便地列出了要避免的词。扫描器把它们计入分数,然后让文章因为包含我恰恰告诉它要避免的词而失败。
[tier1] "leverage" => use
[holier-intensifier] "genuinely"
VERDICT: REVIEW / REWRITE # 分数 6,来自读者从未看到的注释
关卡运行得完美。我把测试数据放进了被测试的东西里面。现在注释说"避免交换表里的词",列表存在一个独立文件里,而且我现在假定每个验证步骤看到的东西比我以为的更多。
三层,每层技能有日期,某处的非零退出,以及一条规则:会话上下文永远不凭本能晋升。这就是整个系统,也是第一个没有悄悄过期的版本。
如果你运行 Agent 技能:你的验证步骤是什么?我坚信没有验证步骤的技能就是会腐坏的技能,我想知道其他人在用什么做关卡。