docs-specialist

文档专家技能

概述

此技能提供技术文档方面的专业能力：根据代码生成文档、检测文档与实现之间的偏差、验证质量，并应用一致的模板。

文档参考

**重要：**开始处理文档任务前，请查阅：

• docs-specialist/skills/docs-specialist/references/documentation-patterns.md

专业领域

1. 从代码生成文档

分析源代码并自动生成文档：

流程：

1. 扫描代码文件（路由、模型、组件、服务）
2. 提取结构（类、函数、签名）
3. 解析现有注释（JSDoc、文档字符串）
4. 应用适当的模板
5. 生成格式规范的文档

2. 检测文档与代码的同步情况

对比文档与代码，找出差异：

状态	符号	含义
已实现	✅	代码与文档完全一致
部分实现	⚠️	代码存在，但与文档不一致
未实现	❌	文档有说明，但代码中缺失
未记录	📝	代码中存在，但文档中没有说明

3. 文档验证

检查质量、准确性和完整性：

• 链接有效性（内部和外部）
• 代码示例的准确性
• 结构和格式
• 按文档类型检查完整性
• 对照代码检查技术准确性

4. 模板系统

为不同类型的文档应用一致的模板：

模板	用途
readme	项目 README
api-endpoint	REST API 端点
component	UI 组件
model	数据库模型
service	服务类
guide	操作指南
architecture	架构决策记录
changelog	版本更新日志

命令

命令	用途
/docs-specialist:docs	验证、生成、更新文档并检查状态
/docs-specialist:sync	检测并修正文档与代码之间的偏差
/docs-specialist:template	列出、查看并应用文档模板
/docs-specialist:init	创建文档文件夹结构
/docs-specialist:doctor	诊断并修正文档问题

完整语法和选项请参阅各命令对应的文件。

工作原则

准确性优先

• 始终对照源代码进行验证
• 编写文档前先测试代码示例
• 标明假设或不确定之处
• 代码变更后立即更新文档

代码分析方法

分析代码并编写文档时：

1. 解析文件结构（尽可能使用 AST）
2. 优先提取公开接口
3. 包含类型信息
4. 在测试中查找用法示例
5. 遵循现有文档注释

同步检测方法

对比文档与代码时：

1. 建立文档条目清单
2. 建立代码条目清单
3. 按名称/路径/签名进行匹配
4. 对匹配结果分类（完全一致、部分一致、缺失）
5. 详细说明部分匹配的差异

文档规范

文件组织

docs/
├── README.md               # Documentation hub
├── api/                    # API reference
├── guides/                 # User guides
├── architecture/           # System design
└── development/            # Developer docs

Markdown 约定

• 使用 ATX 风格标题（#）
• 代码块注明语言
• 内部引用使用相对链接
• 每行一句（便于查看差异）

代码示例

• 提供完整且可运行的示例
• 包含导入和设置步骤
• 展示预期输出
• 突出显示关键行

工具专用文件

将以下文件保留在原始位置（不要移动到 /docs）：

• CLAUDE.md - 根目录
• .claude/commands/*.md - 命令定义
• .claude/agents/*.md - Agent 定义
• .cursorrules - Cursor AI 配置

版本控制

• 使用约定式提交：docs: description
• 相关时，将文档提交与代码提交关联
• 将相关的文档更新分组处理

质量检查清单

在确认文档已完成之前：

• 所有代码示例均已测试且正常运行
• 已对照代码确认技术准确性
• 链接有效且正确
• 格式保持一致
• 操作步骤完整且可执行
• 同步检查通过
• 验证得分高于阈值

常见工作流

###“我写了新代码，需要编写文档”

/docs-specialist:docs generate <path>

###“我修改了代码，更新文档”

/docs-specialist:sync check
/docs-specialist:sync fix

###“审核文档质量”

/docs-specialist:docs validate
/docs-specialist:sync check

###“为新项目设置文档”

/docs-specialist:init
/docs-specialist:docs generate all

###“发布前检查”

/docs-specialist:doctor --check
/docs-specialist:sync check
/docs-specialist:docs validate

成功指标

优秀的文档应当：

• 准确 - 反映当前代码的实际情况
• 完整 - 涵盖所有必要主题
• 保持同步 - 与实现保持一致
• 清晰 - 易于理解
• 易于维护 - 易于更新
• 可执行 - 读者能够达成目标