SuperAPI AI 工具集

validate-docs-implementation

写作与研究

查看项目

更新于 10-15 11:02

技能介绍

用途

该技能用于系统性地识别并修复实际实现代码与文档之间的不一致。核心价值是确保文档准确反映真实实现,避免用户困惑与无效的排查时间。

触发时机

根据资料,在以下情况加载:用户说“validate docs”“check documentation consistency”“docs vs implementation”“find documentation mismatches”,或提到“documentation mismatch”“docs don't match code”;以及在对文档可能产生影响的重大代码改动之后、发布前验证期间。

主要能力

  • 分析实现代码(脚本、核心逻辑)
  • 识别代码实际创建或执行的内容
  • 搜索所有文档中关于这些实体的引用
  • 比对文档描述的行为与实际行为
  • 系统性地修复所有不一致
  • 提供变更摘要

资料中列出的典型不一致类型包括:文件名(如文档写 design.md,代码实际创建 plan.md)、目录结构(如文档缺少 02-resources/ 目录)、数量(如文档写“3 files”,脚本实际创建“4 directories + 3 files”)、命名约定(新旧术语)、对已弃用功能的引用。

使用方式:五步验证流程

Step 1 分析实现:阅读用户指定的实现文件,记录其确切创建/生成/执行的内容,包括创建的文件(名称、位置、数量)、创建的目录(名称、结构、数量)、使用的数据结构、行为模式,形成“基准事实”参考清单。

Step 2 搜索文档:使用 Grep 在文档中搜索旧术语或可能不一致的术语,例如 grep -r "design\.md\|tasks\.md\|requirements\.md" 00-system/,以及搜索旧目录结构如 grep -r "02-working\|03-outputs" 00-system/;记录所有含相关引用的文件、行号与上下文。

Step 3 比对与识别不一致:逐文件阅读相关段落并与实现事实比对,归类不一致类型(文件名、结构、数量、缺失信息),并按优先级排序:关键(面向用户的文档、核心系统图)、重要(技能工作流、参考资料)、可选(示例、注释)。

Step 4 修复全部不一致:对每个存在不一致的文件,阅读后使用 Edit 工具逐处修复,保留上下文与格式,并更新相关引用。资料给出的常见修复模式包括:文件名 design.md → plan.md、tasks.md → steps.md;结构 02-working/ → 03-working/、03-outputs/ → 04-outputs/,并补充缺失的 02-resources/;数量描述改为完整准确形式。过程中使用 TodoWrite 跟踪进度。

Step 5 验证并生成报告:重新搜索旧术语确认已消失(如 grep -r "design\.md" 00-system/ 应无结果),抽查已修复文件;确定报告保存位置(首次或未设置时询问用户:04-workspace/validation-reports/、01-memory/validation-reports/、自定义位置或跳过;已配置则沿用);按模板生成报告,文件名为 validation-{implementation}-YYYY-MM-DD.md,内容包括分析的实现、更新的文件(含逐行变更)、按类型划分的不一致、验证结果、状态与后续步骤,并向用户展示摘要与完整报告链接。

适用场景

资料列出的常见场景包括:脚本创建的文件与文档所述不同;目录结构发生变化;数量或描述有误。集成时机包括:代码改动后提交前、发布前、用户报告不一致时、文档更新后确认未引入新不一致。

成功标准与限制

成功标准为:旧/弃用术语的 grep 结果为零;所有结构图与实际目录结构一致;所有数量与实际产物数量一致;所有文件引用使用当前名称;用户可无障碍按文档操作。

资料未提供该技能的具体安装命令、运行环境要求、平台支持、收费信息或性能指标,这些事实暂未提供。