docs-quality-check

分析并验证代码库的文档质量，确保 PRD、ADR、PRP、CLAUDE.md 和 .claude/rules/ 符合标准且内容是最新的。

上下文

• 目标路径：$1（未指定时默认为当前目录）
• 蓝图目录是否存在：!find .claude -maxdepth 1 -name 'blueprints' -type d
• CLAUDE.md 是否存在：!find . -maxdepth 1 -name 'CLAUDE.md' -type f
• 规则目录：!find .claude/rules -maxdepth 1 -name '*.md'
• ADR（docs/adr）：!find docs/adr -maxdepth 1 -name '*.md'
• ADR（docs/adrs）：!find docs/adrs -maxdepth 1 -name '*.md'
• PRD（docs/prds）：!find docs/prds -maxdepth 1 -name '*.md'
• PRD（蓝图）：!find .claude/blueprints/prds -maxdepth 1 -name '*.md'
• PRP（docs/prps）：!find docs/prps -maxdepth 1 -name '*.md'
• PRP（蓝图）：!find .claude/blueprints/prps -maxdepth 1 -name '*.md'

参数

• $1：要分析的路径（未指定时默认为当前目录）

任务

使用以下方法全面分析文档质量：

第 1 阶段：创建待办清单

创建结构化待办清单，以跟踪分析进度：

- Analyze CLAUDE.md structure and quality
- Check .claude/rules/ directory and standards
- Validate ADRs (Architecture Decision Records)
- Validate PRDs (Product Requirements Documents)
- Validate PRPs (Product Requirement Prompts)
- Check documentation freshness and git history
- Generate quality report with recommendations

第 2 阶段：分析 CLAUDE.md

2.1 检查是否存在及结构

• 确认项目根目录下存在 CLAUDE.md
• 检查是否包含必需的 YAML frontmatter：

  ---
  created: YYYY-MM-DD
  modified: YYYY-MM-DD
  reviewed: YYYY-MM-DD
  ---
  

2.2 内容质量检查

• 完整性：是否清楚地说明了项目背景？

  • 项目结构概览
  • 开发规范
  • 关键规则和指南
  • 适用时列出插件/工具参考

• 清晰度：组织是否合理、易于阅读？

  • 使用清晰的章节标题
  • 正确使用 Markdown 格式
  • 使用表格呈现结构化数据
  • 在有帮助的地方提供示例

• 准确性：检查信息是否过时

  • 将修改日期与近期 git 提交进行比较
  • 查找已弃用模式的相关引用
  • 验证文件路径和引用的目标是否存在

2.3 最佳实践

根据 CLAUDE.md 标准进行检查：

• 应指导 AI 助手如何处理该代码库
• 包含项目结构说明
• 引用关键规则和规范
• 指向其他文档（ADR、规则）
• 使用表格以便快速查阅
• 保持内容重点明确、简洁

第 3 阶段：分析 .claude/rules/

3.1 目录结构

• 确认 .claude/rules/ 目录存在
• 列出所有现有规则文件
• 检查是否包含推荐的核心规则：
  • 架构/设计模式
  • 编码标准
  • 开发工作流
  • 测试要求

3.2 验证各项规则

针对 .claude/rules/ 中的每个规则文件：

必需的 Frontmatter：

---
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
name: docs-quality-check
---

内容标准：

• 标题和用途清晰
• 范围定义明确
• 指导内容具体且可执行
• 适当提供示例
• 交叉引用相关规则

3.3 规则组织

• 规则是否经过合理分类？
• 规则数量是否过多或过少？
• 规则之间是否存在重复或冲突？
• 规则名称是否清晰且一致？

第 4 阶段：验证 ADR

4.1 检查 ADR 目录

• 确认 docs/adrs/ 或 docs/adr/ 存在
• 检查是否有 ADR 索引/README
• 列出所有 ADR 文件（文件名应带编号：0001-title.md）

4.2 验证 ADR 结构

针对每份 ADR，检查以下内容：

命名规范：

• 格式：NNNN-kebab-case-title.md（例如：0001-plugin-architecture.md）
• 编号连续
• 标题具有描述性

必需章节（MADR 格式）：

# ADR-NNNN: Title

**Date**: YYYY-MM
**Status**: Accepted | Superseded | Deprecated
**Deciders**: [who made the decision]

## Context
[The issue motivating this decision]

## Decision
[The change being proposed or made]

## Consequences
[What becomes easier or harder]

4.3 ADR 质量检查

• 状态准确性：已弃用的 ADR 是否已标记？
• 完整性：ADR 是否包含所有必需章节？
• 相关性：ADR 是否仍适用于当前代码库？
• 索引维护：ADR 索引是否为最新？

4.4 覆盖范围分析

• ADR 是否涵盖主要架构决策？
• 最近的重要变更是否已有文档记录？
• 是否存在明显缺少文档记录的决策？

第 5 阶段：验证 PRD

5.1 检查 PRD 目录

• 确认 docs/prds/ 或 .claude/blueprints/prds/ 存在
• 列出所有 PRD 文件

5.2 PRD 结构验证

对于每份 PRD，验证以下内容：

Frontmatter（如果采用 Blueprint 方法论）：

---
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
status: Draft | Active | Implemented | Archived
name: docs-quality-check
---

必需章节：

• 执行摘要／问题陈述
• 利益相关者与用户画像
• 功能需求
• 非功能需求
• 成功指标
• 范围（范围内／范围外）
• 技术考量

5.3 PRD 质量检查

• 清晰度：需求是否具体且可衡量？
• 完整性：是否包含所有关键章节？
• 状态：状态字段是否准确？
• 可追溯性：能否将需求追溯到具体实现？
• 用户关注度：是否清楚阐述了用户需求？

第 6 阶段：PRP 验证

6.1 检查 PRP 目录

• 验证 docs/prps/ 是否存在（Blueprint 方法论）
• 列出所有 PRP 文件

6.2 PRP 结构验证

对于每份 PRP，验证以下内容：

必需章节：

• 目标与原因
• 成功标准（可测试）
• 上下文（文档参考、代码库情报、已知注意事项）
• 实施蓝图（架构、任务分解）
• TDD 要求（测试策略、关键测试用例）
• 验证关卡（可执行命令）
• 置信度评分（各维度为 0–10）

6.3 PRP 质量检查

• 具体性：文件路径和代码引用是否明确？
• 可测试性：成功标准是否可衡量？
• 完整性：置信度评分是否与内容质量相符？
• 可执行性：能否立即执行这份 PRP？
• 上下文：是否提供了足够且经过整理的实施上下文？

第 7 阶段：时效性分析

7.1 检查最后修改日期

对于所有文档：

• 将 modified frontmatter 日期与 git 历史记录进行比较
• 找出过时文档（超过 6 个月未审查）
• 标记因相关代码变更而需要审查的文档

使用 git 检查活动情况：

# Check recent commits affecting docs
git log --since="6 months ago" --oneline -- docs/ .claude/ CLAUDE.md 2>/dev/null || echo "Not a git repo or no history"

# Check when documentation was last touched
git log -1 --format="%ai %s" -- CLAUDE.md 2>/dev/null || echo "No git history"

7.2 与代码变更交叉核对

• 是否有重大代码变更却未更新文档？
• ADR 是否与实际架构保持一致？
• PRD 是否准确反映已实现的功能？

第 8 阶段：生成质量报告

8.1 文档清单

生成汇总表：

## Documentation Inventory

| Document Type | Status | Count | Issues |
|---------------|--------|-------|--------|
| CLAUDE.md | ✅/❌ | 1 | [list issues] |
| .claude/rules/ | ✅/❌ | N files | [list issues] |
| ADRs | ✅/❌ | N files | [list issues] |
| PRDs | ✅/❌ | N files | [list issues] |
| PRPs | ✅/❌ | N files | [list issues] |

8.2 质量评分

计算总体质量评分：

类别	评分（0–10）	备注
结构	X	文件组织、命名
完整性	X	是否包含必需章节
时效性	X	最近更新、与 git 同步情况
标准合规性	X	Frontmatter、格式
内容质量	X	清晰度、具体性
总体	X	平均分

评级指南：

• 9–10：优秀——维护良好、内容全面
• 7–8：良好——只需进行少量改进
• 5–6：一般——有若干问题需要处理
• 3–4：较差——存在重大缺漏或内容过时
• 0–2：危急——内容缺失或严重不足

8.3 问题与建议

对发现的问题进行分类：

关键问题（必须修复）：

• 缺少必需文档
• 存在严重的结构问题
• 信息已完全过时

警告（应该修复）：

• 文档过时（超过 6 个月）
• 缺少 frontmatter
• 章节不完整
• 轻微结构问题

建议（锦上添花）：

• 有助于理解的补充文档
• 改进组织方式
• 加强交叉引用
• 丰富示例

8.4 可执行建议

针对每个问题，提供具体指导：

## Recommendations

### Immediate Actions
1. [ ] Fix [specific issue] in [file]
   - **Why**: [reason]
   - **How**: [specific steps]
   - **Command**: [if applicable]

2. [ ] Update [document]
   - **Why**: [reason]
   - **How**: [specific steps]

### Maintenance Tasks
1. [ ] Review and update stale documents:
   - [file1] - last modified [date]
   - [file2] - last modified [date]

2. [ ] Improve documentation coverage:
   - [ ] Document [undocumented decision]
   - [ ] Create ADR for [architectural choice]

### Best Practices
- Run `/docs:quality-check` monthly
- Update `modified` dates when editing docs
- Review `reviewed` dates quarterly
- Use `/blueprint:adr` for new architecture decisions
- Use `/blueprint:prd` for new features

第 9 阶段：展示结果

9.1 执行摘要

提供清晰、简洁的摘要：

📊 Documentation Quality Report
═══════════════════════════════

Overall Score: X/10 ([Excellent/Good/Fair/Poor/Critical])

✅ Strengths:
- [strength 1]
- [strength 2]

⚠️  Issues Found:
- [issue 1]
- [issue 2]

📋 Recommendations:
- [top recommendation 1]
- [top recommendation 2]

See full report below for details.

9.2 完整报告

呈现完整分析，包含：

• 文档清单
• 各类别质量评分
• 详细发现
• 可执行建议
• 维护检查清单

9.3 改进指南

帮助用户了解后续步骤：

• 如果尚未初始化 Blueprint → 建议使用 /blueprint:init
• 如果缺少 ADR → 建议使用 /blueprint:adr
• 如果缺少 PRD → 建议使用 /blueprint:prd
• 如果文档过时 → 提供更新检查清单
• 如果未遵循标准 → 展示示例和模板

最佳实践

分析要求

• 全面但简洁
• 聚焦可执行的问题
• 提供具体的文件／行号引用
• 包含良好与不良模式的示例
• 提出具体的修复方案，而不只是指出问题

文档规范

• Frontmatter：始终包含创建、修改和审阅日期
• 结构：遵循既定模板（ADR、PRD、PRP）
• 清晰度：面向未来的维护者和 AI 助手撰写
• 维护：每季度审阅一次，并更新修改日期
• 交叉引用：链接相关文档
• 示例：包含代码片段和真实示例
• 范围：保持聚焦，每份文档只讨论一个主题

错误处理

• 如果不是 git 仓库 → 跳过基于 git 的新鲜度检查
• 如果目录不存在 → 在报告中注明缺失
• 如果文件格式错误 → 标出具体的解析错误
• 如果无法读取文件 → 注明权限／访问问题
• 如果 Blueprint 尚未初始化 → 建议先初始化，再创建文档

输出格式

使用清晰的 Markdown 格式：

• 用表格呈现结构化数据
• 用复选框列出待办事项
• 用代码块展示示例
• 用表情符号标记（✅ ❌ ⚠️），便于快速浏览
• 用可折叠区域呈现详细分析（如果支持）

请记住：目标是帮助用户维护高质量、及时更新的文档，让文档能有效服务于人类开发者和 AI 助手。