audit-docs — 文档与代码合规性审计

技能目的

对项目中的文档与配置文件进行合规性审计，确保文档目录结构、命名规范、配置文件格式与文档元数据均符合项目规范。通过扫描、检查与验证，生成合规报告，帮助团队维持文档与配置的长期可维护性。

参数说明

本技能无参数。自动扫描项目全部文档与配置目录。

分阶段工作流

阶段 1：扫描文档目录

• 输入：项目目录
• 处理：
  1. 使用 Glob 扫描 docs/**/*.md 获取全部文档文件清单
  2. 使用 Glob 扫描 .claude/docs/**/*.md 获取 Agent 文档清单
  3. 使用 Glob 扫描配置文件（*.json、*.yaml、*.yml）
  4. 使用 Read 读取 docs/directory-structure.md 获取预期目录结构
  5. 对比实际目录与预期结构，标记缺失或多余目录
• 输出：文档目录扫描结果

阶段 2：检查命名规范

• 输入：文档与配置文件清单
• 处理：
  1. 使用 Grep 检查文件名是否符合 kebab-case 命名规范
  2. 检查文档内的标题层级是否规范（H1 唯一性、层级递进）
  3. 使用 Read 抽样检查文档内容命名一致性
  4. 标记不符合命名规范的文件与标题
• 输出：命名规范检查结果

阶段 3：验证 JSON/YAML 格式

• 输入：配置文件清单
• 处理：
  1. 使用 Read 读取每个 JSON 文件内容
  2. 使用 Read 读取每个 YAML 文件内容
  3. 使用 Grep 检查 YAML 缩进与结构一致性
  4. 验证 frontmatter 格式是否符合 YAML 规范
  5. 标记格式错误或不合规的配置文件
• 输出：格式验证结果

阶段 4：检查文档元数据完整性

• 输入：文档清单 + 格式验证结果
• 处理：
  1. 使用 Grep 检查文档是否包含必需元数据字段（标题、日期、作者或状态）
  2. 使用 Read 抽样验证元数据内容的有效性
  3. 检查 SRS 文档是否包含需求 ID 与验收标准
  4. 检查设计文档是否包含 8 个必需章节
  5. 标记元数据缺失或不完整的文档
• 输出：元数据完整性检查结果

阶段 5：生成合规报告

• 输入：全部阶段产物
• 处理：
  1. 汇总目录结构、命名规范、格式验证与元数据完整性结果
  2. 按严重度分类问题：错误（格式错误、必需字段缺失）、警告（命名不规范）、提示（可改进项）
  3. 计算整体合规评分
  4. 使用 Write 写入报告至 docs/reports/audit-docs.md
• 输出：文档合规审计报告

协作协议引用

• 遵循 docs/examples/COLLABORATIVE-DESIGN-PRINCIPLE.md 用户驱动协作协议
• 参考 docs/directory-structure.md 目录结构规范
• 参考 docs/coding-standards.md 编码规范
• 参考 docs/rules/docs-standards.md 文档标准
• 审计为只读分析，不修改文档与配置文件

推荐下一步

根据合规报告修复格式错误与缺失元数据。文档内容差距使用 /content-audit 分析。技能文件合规性使用 /skill-test 验证。修复后重新运行本技能确认合规度提升。