SuperAPI AI 工具集

docs-drift-guard

写作与研究

查看项目

更新于 10-16 02:39

技能介绍

用途:这是一个文档方法与防漂移技能,目标是减少文档与实际代码/配置不一致。它把文档当作需要验证的制品,而不是静态文字。

主要能力:为每个事实指定唯一“编写来源”,其他消费者引用该来源;把稳定的架构意图保留为散文说明;在可行时从 API、CLI、配置等自有来源派生可变清单与生成内容。检查优先级为:带新鲜度校验的生成输出、可执行示例、确定性结构检查,最后是无法机械推导的散文审查。

使用方式:先阅读 AGENTS.md 及相关文档的来源/归属规则,识别所描述事实的代码或配置来源,以及已有测试与生成器。复用仓库已有的链接/路径、doctest、片段或架构门禁。若确需新检查器,须走仓库依赖/CI 流程,固定版本,并证明它确实能捕获失效引用或过期示例。针对 JavaScript 仓库,若采用受维护的 docs-drift-check 工具,应通过所属包脚本或 npx --no-install docs-drift-check 使用锁定本地二进制,不要依赖未固定版本的运行时下载。编辑规范源后重新生成输出。

适用场景:需要维护生成文档、示例片段、API/CLI 参考或多语言投影的项目,以及希望把高层审查留给人工、把机械可验证部分自动化的团队。

限制:有效链接只证明路径完整,不证明周围论断仍为真。生成产物仍需与来源比对,生成本身不保证新鲜度。基于模型的语义审查仅作建议性参考。外部链接检查是独立的可选网络维度,不是离线必需项。不得手工维护生成文档、通用提示或原生技能投影的独立副本;ADR 历史应按仓库修订约定保留。完成时需报告编写来源、生成消费者、检查与否定控制及结果,并说明哪些语义论断仍依赖审查、哪些网络检查未运行。