derive-instead-of-transcribing
任何从别处手抄过来的东西,只正确一次。能生成就生成,并在副本过期时让构建失败。
由读过该卡片的评审者赋予,而不是文件自我声明的。智能体在处理不可信内容的运行中提炼出的卡片,生来即被标记为受污染,在被检索之前会一直等待评审。
何时会想到它
- 给命令列表写文档
- 在项目之间复制配置值
- 让两个文件保持同步
- 写一份参考文档
价值通常在「避免」和「检查」里。「该做」是人人都会写的那一节。
上面的卡片正文是译文。英文原文才是 CLI 导入的内容、智能体运行时读取的内容,也是下方哈希所证明的内容。
触发
你的系统里有两个地方持有同一份信息:一份配置和它的文档、一份模式(schema)和它的客户端类型、一套调色板和使用它的站点、一份命令清单和一个参考页面。
如果第二份拷贝是故意做得不一样的,这条就不适用——一份精心编写的入门指南不是参考文档的一份过时拷贝,它是承担不同职责的散文。
该做
- 选定哪一份是源头。通常是程序在运行时实际读取的那一份。
- 生成另一份,并把生成出来的文件提交(commit)进版本库,这样 diff 才可审查。
- 加一个 CI 步骤:重新生成一遍,如果和已提交的版本不一致就失败,错误信息里要给出该运行的确切命令。
- 在生成的文件上打上它是从哪个版本或哪次提交生成出来的印记,这样读者才知道它描述的是什么。
避免
靠人记着来保持两份拷贝同步。这在一个人同时把两份文件都装在脑子里时管用,一旦有别人碰了其中一份,第一周就会失效。
也要避免那种半吊子做法:生成了文件,却没有用门禁(gate)拦住它。一个偶尔才会重新生成的产物,比手写的还糟,因为它顶着"是生成出来的"这份权威性,却和手写的一样容易过时。
还要避免生成散文式的内容。参考资料适合生成;说明性文字不适合,一页机械展开出来的字段描述,是一页没人会读的东西。
检查
修改源头,不重新生成,直接推送(push)。CI 必须变红,并告诉你该运行什么命令。
然后去生成出来的文件里找你改动的那个东西,确认它确实出现了——门禁(gate)证明的是文件是最新的,而不是证明生成器(generator)真的捕捉到了你关心的那个字段。
风险
一个没人能读懂的生成产物是违背初衷的;如果输出只对机器有意义,就还需要一层渲染,那又是更多要维护的代码。
这里还有耦合的代价。消费方现在依赖于生产方的形状,一边的重构会打破另一边的构建。这通常正是意义所在——但这也意味着门禁(gate)必须容易满足,否则会有人在一次不相关的重构里把它关掉,然后忘记重新打开。
如何使用
卡片就是数据。克隆仓库并按路径导入——任何经由网络到达的内容都会被视为受污染并等待批准,这正是你想要的行为,也是这里没有一行命令安装器的原因。
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/derive-instead-of-transcribing/SKILL.md完整性
文件发布版本的 SHA-256。导入方可以据此核对收到的内容与本页展示的一致。
8b9a25705790b36bd8b04294161cac342e63b667c0e6a6e36240d981687f35f9