mcpField
E
ensure-docs

ensure-docs

github.com/existential-birds开发8566 次安装11 周前更新
代码仓库

关于 ensure-docs

ensure-docs 是用于审查代码库文档覆盖情况并报告缺口的 Agent Skill。它结合按语言进行的符号检查与 Diataxis 文档类型审查，并仅在用户选择后生成缺失文档。

主要功能

  1. 01检测适用的编程语言
  2. 02按语言标准检查文档
  3. 03审查四类 Diataxis 文档覆盖
  4. 04按严重程度汇总发现
  5. 05经用户选择后生成文档
  6. 06提供编辑后的 Linter 验证

适用场景

  1. 01审计代码库的文档覆盖
  2. 02发现缺失的 Diataxis 文档类型
  3. 03报告文档字符串和 API 文档缺口
  4. 04生成用户选定的缺失文档

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/existential-birds/beagle --skill ensure-docs

安装后在 Claude Code 中输入/ensure-docs确认已加载。

附带文件references/workflow.md

详细介绍

确保文档覆盖率

验证代码库中的文档覆盖率，报告缺口，并生成缺失的文档。如果 Agent 支持子 Agent，则为检测到的每种语言并行分派一个验证器；否则，按语言依次执行相同的验证——两种方式的输出相同。

覆盖率有两个互补的视角，健康的项目两者都不可或缺：

  1. 符号覆盖率——函数、类和模块是否按照该语言的标准编写了文档（文档字符串、JSDoc、GoDoc）？下文将按语言进行验证。
  2. Diataxis 类型平衡——整个文档集是否满足用户的四种需求：用于学习的教程、用于完成任务的操作指南、用于查阅的参考文档，以及用于理解的说明文档？代码库即使有 100% 的文档字符串覆盖率，新手也可能仍然无从入门。请参阅下文的 Diataxis 平衡检查。

工作流

按顺序完成各步骤。只有满足每一步的通过条件后，才能继续。

  1. 检测语言——按照 references/workflow.md 中的阶段 1（语言检测）执行。

    • 通过条件： 对于每种要验证的语言，都有至少一个匹配源文件的证据（计数或命令输出）；如果没有符合条件的语言，则停止，并简短说明“没有适用的语言”，不要运行验证器。

  2. 加载标准——在同一参考文件中阅读检测到的语言对应的章节（语言标准、验证器提示词、汇总格式）。

    • 通过条件： 开始验证前，能够说明每种语言适用的标准（例如 Google 文档字符串、JSDoc、GoDoc）。

  3. 验证——使用参考文件中的验证器提示词和 JSON 输出格式（阶段 2），验证每种符合条件的语言。如果 Agent 支持子 Agent，则为每种语言并行运行一个验证器；否则依次运行。

    • 通过条件： 每项已完成的验证都返回可解析的 JSON，其中包含 language、files_scanned 和 findings（数组，可为空）。

  4. Diataxis 平衡检查——针对项目现有文档（例如 docs/ 目录树、README 或 wiki）运行 Diataxis 类型平衡检查。

    • 通过条件： 能够说明项目对四种类型（教程、操作指南、参考文档、说明文档）中的每一种是否至少有一份文档满足该需求，并记录缺失或内容单薄的类型。

  5. 汇总报告——按照阶段 3 汇总结果（摘要表、按严重程度分类、按需提供详细发现）。在符号覆盖率之外，还要纳入 Diataxis 平衡情况。

    • 通过条件： 在声称审计完成或提出修复方案之前，用户已看到合并后的报告（直接展示或写入双方约定的路径），报告涵盖符号覆盖率和 Diataxis 类型平衡。

  6. 生成——只有在未设置 --report-only 时，才按照阶段 4 提供选项；仅在用户明确选择生成后才应用文档编辑。对于缺失的 Diataxis 类型，应通过 draft-docs 为相应类型生成草稿，而不是直接生成文档。

    • 通过条件： 在用户选择包含生成的选项之前，不得为任何缺口编辑文档；如果用户拒绝或选择仅报告，则在报告后结束。

  7. 编辑后验证——生成任何文档后，对于修改过的语言，如果仓库中存在相关工具，则按照参考文件的阶段 5 运行或提供代码检查工具命令。

    • 通过条件： 已运行代码检查工具并记录输出，或注明 N/A 并用一句话说明原因（例如未配置该工具）；剩余问题已列出或解决。

Diataxis 类型平衡检查

调查项目的文字文档（docs/ 目录树、README、wiki 或文档站点），并将现有内容归为 Diataxis 的四种类型。根据 docs-style/references/diataxis-compass.md，使用指南针进行分类——行动还是认知？获取还是应用？

将平衡情况报告为表格：

类型是否存在？备注
Tutorial（学习）是 / 否 / 薄弱例如：“没有入门 / 首个项目指南”
How-To（任务）是 / 否 / 薄弱例如：“docs/how-to/ 下有多篇任务指南”
Reference（查阅）是 / 否 / 薄弱例如：“已生成 API 参考文档，但没有 CLI 参考文档”
Explanation（理解）是 / 否 / 薄弱例如：“没有架构 / 设计原理文档”

按优先级标出：

  1. 缺失的类型——文档集完全无法满足这类用户需求。最常见、影响也最大的缺口是缺少 Tutorial：项目即使有详尽的参考文档，也可能让新手无从入门。
  2. 薄弱的类型——虽然存在，但未覆盖项目的主要功能或使用界面。
  3. 混合型文档——单页文档试图同时承担两种类型的职责（例如在 How-To 中嵌入参考表格）。建议通过 improve-doc 拆分。

不要为缺失的类型提议生成空白文档骨架。遵循 Diataxis 的“通过改进来工作”原则，推荐接下来最有价值的一份文档来添加或修复，并提出通过 draft-docs 协助起草。

备注

  • 使用 --report-only 跳过生成。
  • 避免处理测试文件，但测试辅助文件除外。
  • 确保报告输出符合参考文件中针对相应语言的标准。
  • Diataxis 平衡检查针对整个文档集；各语言的符号覆盖率与类型平衡是相互独立的——两者都要报告。

评论

支持 Markdown