⚡

文档审查Skill doc-review

这个技能用于系统性地审查和清理软件文档，确保文档的时效性、准确性和相关性。它自动化扫描文件、检查过时指标、验证代码引用、生成报告，并支持安全修复。关键词：文档审查、文档清理、代码文档、自动化维护、DevOps、软件维护。

DevOps 0 次安装 0 次浏览 更新于 3/15/2026

名称: 文档审查 描述: “审查和清理过时文档。定期使用以维护文档健康。触发条件：审查文档、清理文档、检查过时文档。”

文档审查技能

系统性地审查文档的过时性、准确性和相关性。

任务

  1. 扫描所有文档文件
  2. 检查过时指标
  3. 验证引用的代码/文件是否仍存在
  4. 识别过时内容
  5. 生成清理报告
  6. 可选地应用修复

使用时机

计划性

  • 每个里程碑完成后
  • 每月维护周期
  • 主要发布前

按需

  • 当文档感觉过时时
  • 重大重构后
  • 入职培训揭示混淆时

审查过程

步骤1：清点文档

扫描文档文件：

find . -name "*.md" -not -path "./.git/*" -not -path "./.vendor/*" -not -path "./.worktrees/*"

常见位置：

  • README.md（根目录和子目录）
  • docs/ 目录
  • AGENTS.md, CLAUDE.md
  • .claude/skills/*/SKILL.md
  • knowledge/ 目录
  • scripts/aha-loop/templates/

步骤2：检查过时指标

对于每个文档，检查：

指标 检查方法 阈值
最后修改 git log -1 > 30 天
引用文件 grep + 验证 缺失 = 过时
代码示例 语法检查 错误 = 过时
版本号 与实际比较 不匹配 = 过时
链接 HTTP 检查 损坏 = 过时

步骤3：验证代码引用

对于文档中的每个代码引用：

## 代码引用检查

文件: [文档路径]
引用: `src/main.rs:45-60`
状态: [存在 | 缺失 | 已更改]

如果已更改：
- 原始: [文档所述]
- 当前: [代码显示]
- 操作: [更新文档 | 标记审查]

步骤4：检查外部链接

# 提取URL
grep -oP 'https?://[^\s)]+' file.md

# 检查每个URL
curl -s -o /dev/null -w "%{http_code}" URL

步骤5：生成报告

创建 docs-review-report.md：

# 文档审查报告

**日期:** [YYYY-MM-DD]
**已审查:** [N] 文件
**发现问题:** [N]

## 摘要

| 类别 | 数量 |
|----------|-------|
| 过时 (>30 天) | [N] |
| 缺失引用 | [N] |
| 损坏链接 | [N] |
| 过时示例 | [N] |

## 按文件问题

### [file1.md]
- [ ] 第45行：引用 `src/old.rs` - 文件不再存在
- [ ] 第78行：代码示例使用已弃用API

### [file2.md]
- [ ] 第12行：版本 "1.0.0" 应为 "2.0.0"
- [ ] 第56行：损坏链接到外部文档

## 推荐操作

1. **删除:** [应删除的文件]
2. **更新:** [需要内容更新的文件]
3. **审查:** [需要人工审查的文件]

## 可自动修复

以下可以自动修复：
- [ ] 更新版本号
- [ ] 移除死链
- [ ] 更新文件路径

运行 `./scripts/aha-loop/doc-cleaner.sh --fix` 以应用。

过时标准

确定过时

  • 引用不存在的文件
  • 包含不编译的代码
  • 链接到404页面
  • 描述已移除的功能

可能过时

  • 60+天未修改
  • 使用旧API模式
  • 引用旧版本号
  • 最近git提交未提及该文件

需要人工审查

  • 包含过时但复杂的内容
  • 描述已弃用但仍支持的功能
  • 历史文档（变更日志、决策记录）

自动修复规则

可安全自动修复

  • 更新文件路径（如果存在清晰映射）
  • 移除损坏的外部链接
  • 更新依赖列表中的版本号
  • 修复代码引用中的明显错别字

需要人工审查

  • 超出机械更新的内容更改
  • 删除整个部分
  • 更改技术指令
  • 修改架构决策

集成

与文档清理脚本

# 仅生成报告
./scripts/aha-loop/doc-cleaner.sh --report

# 应用安全修复
./scripts/aha-loop/doc-cleaner.sh --fix

# 交互模式
./scripts/aha-loop/doc-cleaner.sh --interactive

与可观察性

记录审查活动：

## 2026-01-29 16:00:00 | 任务: 维护 | 阶段: 文档审查

### 文档审查
扫描45个文件，发现7个问题。

### 关键发现
- AGENTS.md 引用过时的技能路径
- README 示例代码使用已弃用API

### 采取的行动
- 自动修复3个版本号问题
- 标记4个项目供人工审查

检查清单

审查完成前：

  • [ ] 所有Markdown文件已扫描
  • [ ] 代码引用已验证
  • [ ] 外部链接已检查
  • [ ] 报告已生成
  • [ ] 自动修复已应用（如果安全）
  • [ ] 人工审查项目已标记

示例审查

输入

文件: docs/api.md 最后修改90天前

# API 文档

## 认证

见 `src/auth/mod.rs` 了解实现。

使用认证库版本0.5.0：
```toml
auth-lib = "0.5.0"

更多信息：https://example.com/old-docs


### 审查发现

1. **过时**: 最后修改90天前
2. **缺失引用**: `src/auth/mod.rs` 不存在（已移至 `src/api/auth.rs`）
3. **过时版本**: 当前版本是1.2.0，不是0.5.0
4. **损坏链接**: https://example.com/old-docs 返回404

### 报告条目

```markdown
### docs/api.md

**过时性:** 90天自上次更新
**问题:**
- [ ] 第5行：`src/auth/mod.rs` → `src/api/auth.rs`
- [ ] 第8行：版本 0.5.0 → 1.2.0
- [ ] 第12行：损坏链接 (404)

**推荐:** 更新文件路径和版本，移除损坏链接

预防

减少未来过时：

  1. 与代码一起更新文档 - 更改代码时，更新相关文档
  2. 在CI中添加文档检查 - 引用损坏时失败
  3. 安排定期审查 - 每月或每里程碑
  4. 使用相对链接 - 比绝对链接更易维护
  5. 日期戳示例 - “截至v1.2.0”