SuperAPI AI 工具集

principle-encode-lessons-in-structure

通用与其它

查看项目

更新于 10-16 04:54

技能介绍

用途:当同一条指令即将第二次被写下,或同一个纠正再次出现时,用此原则把重复修复固化为机制(工具、代码、元数据、自动化),而不是再加一条文字说明。文字只有在读者注意到、记住并遵守时才有效,机制则无需请求即可强制执行。

主要能力:把已发生两次的错误视为一类问题,修类而非只修眼前实例;按“能站得住的最高层级”修复,架构优先——每份状态只有一个所有者、每项任务只有一种受支持做法、内部实现放在外部无法导入之处、列表只有一个事实来源、旧做法被删除。其下依次为:无法表示因而编译失败的状态、lint 规则或 CI 检查、规范辅助函数、运行时检查或元数据标志、行为测试,最后才是文字说明(保留给需要判断的调用)。

用法要点:lint 规则或 CI 检查应在错误信息中说明改用哪个文件、类型或函数;模式已普遍存在时只对新出现处报错。每个新检查都要用真实错误验证:把过去的实例放回(修复前的当前失误,或旧提交中的那一行),运行检查看到失败,再移除实例看到通过;从未见过失败的检查不能证明任何事,且本地与 CI 运行方式一致。例外需在其被豁免的那一行注明原因、失效时间和批准人。AGENTS.md 或 CLAUDE.md 维护一张表,每行一条规则及其执行机制,或写“none”;新增检查时补上对应行;机制为“none”的行再次被纠正即为重复,应在该次变更中按最高层级修复;错误已不可能发生的行移出表。需要判断的规则保留说明、放到更显眼处并给出所防失败的示例。结构性修复一旦存在,被它取代的说明即属症状应删除,表中改记机制。

限制与边界:对每个函数都返回空仍保持绿色的测试不守护任何东西,应修复或删除。每个错误、人工纠正和意外都是信号,需捕获并判断是一次性还是模式;按影响范围路由:一次性写入项目记录(如 CONTEXT.md 的术语、通过 ADR 测试的决策写入 docs/adr/),重复修复写入技能或 lint 规则,系统性问题写入 principle-* 技能。闭环方式:立即应用,或开一个具体待办。三种失败:承认教训却不记录;记录却不路由;只修一个实例而留下模式。机制生效后,write-skill 的循环只覆盖剩余文字,且该文字仍需有观察到的基线失败。不可表示状态层级由 principle-type-system-discipline 负责,脚本由 principle-build-the-lever 负责。