用途:通过结构性规则而非人工警觉来防止文档漂移,适用于认知架构或大型项目中的文档维护。
主要能力:
- 计数治理:正文中禁止硬编码计数(如“109 skills”),改用指向目录或目录清单的引用;表格中的计数可接受;每个指标只保留一个权威来源;用链接代替复制;计数应靠近“Last Updated”日期。
- 权威来源:文件系统始终是事实来源,技能数、指令数、提示数、智能体数等均从对应目录派生,命令数取自 package.json,Synapse 数取自 Brain QA 验证输出。
- 文档新鲜度:计数与文件系统不符、活文档“Last Updated”超过30天、版本号不匹配、引用已删除或重命名文件时需处理。
- 活文档与历史文档:活文档(README、copilot-instructions、ROADMAP、USER-MANUAL)应尽量减少计数并保持最新;历史文档中的计数是快照,保持原样;生成文档中的计数是审计输出,可保留。
- 链接完整性:活文档中的每个 Markdown 链接必须可解析;文件夹中重要文件应从其 README.md 链接;移动文件需在同一提交中更新所有引用;归档文档不应从活文档链接;文档树内使用相对路径。
- 孤儿检测:存在于文档文件夹但未被任何索引或父文档引用的文件,应加入索引或归档删除。
- 整合协议:规划目标结构、移动前 grep 所有引用、移动与更新一步完成、移动后验证链接、更新所有 README.md 索引。
- 目录结构:按受众分目录,如 docs/guides/(用户)、docs/architecture/(开发者与 AI)、docs/features/(开发者)、docs/platforms/、docs/operations/(维护者)、docs/research/(策略)、docs/archive/(历史)。
- 多受众与分层:写作前先问“谁读这个”,按受众放置;重要架构至少包含摘要与详细两层。
- 时机:先构建、发布、再文档化;架构决策记录(ADR)应在实现前编写。
- 漂移检测:在冥想与梦境会话中检查版本号、框架名、图表标签、README“What's New”。
- 审计清单:搜索变更指标、grep 过期计数、检查权威来源、验证交叉引用、时间戳检查、孤儿检查、受众检查。
- CHANGELOG 最佳实践:记录架构决策而非仅代码变更,解释原因,每个用户可见变更一条,使用 Added/Changed/Fixed/Removed 结构,不跳过版本。
- 预检验证:可在发布脚本或 CI 中自动比对文档计数与文件系统,例如 PowerShell 示例检查技能数漂移。
使用方式:将上述规则作为文档维护规范,在开发后审计、发布前预检、文档重组时执行。
限制:资料未提供具体安装命令、收费、平台支持或效果数据;规则需按项目实际情况调整。