用途
该技能用于生成全面、可维护的文档，涵盖代码文档字符串、API 规范、架构图、README 文件以及清晰的代码讲解。
激活触发条件
在以下情况激活该技能：
- 用户说“document this”“explain this code”“how does this work?”
- 用户提到“README”“docs”或“documentation”
- 完成某个功能或创建 API 端点之后
- 用户说“write comments for this”
文档类型
1. 代码文档（文档字符串）
目标：清晰、全面的函数/类文档。
关键组成部分：
- 简要描述（一行）
- 详细说明（目的与行为）
- 参数（类型、约束、示例）
- 返回值（类型与含义）
- 示例（真实用法）
- 抛出/异常（错误条件）
- 备注（实现细节）
各语言格式：
- Python："""三引号"""，Args/Returns/Raises 格式
- JavaScript/TypeScript：JSDoc /** */，@param/@returns/@throws 标签
- Java：Javadoc /** */，@param/@return/@throws 标签
- C#：XML 注释 /// <summary>
2. API 文档
目标：为每个端点提供完整的 API 参考。
每个端点必需的部分：
- HTTP 方法与路径
- 简要描述
- 请求模式（参数、请求体及其类型与约束）
- 成功响应（状态码、模式、示例）
- 错误响应（状态码、错误码、消息）
- 用法示例（cURL 和/或特定语言）
- 安全说明（认证、速率限制等）
模板：
METHOD /api/path
Description of what this endpoint does.
Request:
field(type, required/optional): Description
Response (200 OK):
field(type): Description
Errors: 400 (validation), 401 (auth), 429 (rate limit)
Security: Auth required, rate limit X req/min
3. 架构文档
目标：清晰的系统概览与组件关系。
必需部分：
- 概览：系统目的与架构风格
- 系统图：展示组件与连接的 ASCII 或 Mermaid 图
- 核心组件：每个组件的职责、功能、技术、扩展策略
- 数据流：关键操作的分步流程
- 集成点：外部服务与内部 API
- 安全架构：认证、授权、数据保护
- 性能：缓存策略、数据库优化、扩展策略
- 监控：指标、日志、告警
4. README 生成
目标：全面的项目 README。
必要部分：
- 标题 + 一行描述——解决什么问题
- 功能——以项目符号列表列出关键功能
- 安装——克隆、安装、配置、运行
- 用法——基本代码示例
- 配置——环境变量表（变量、描述、是否必需）
- 开发——测试、lint、构建命令
- 许可证
可选部分（按需添加）：
- 演示/截图、API 参考、项目结构、部署、贡献指南
5. 代码讲解
目标：清晰讲解复杂代码。
流程：
- 高层目的——解决什么问题？处于什么位置？
- 分步逻辑——拆分为阶段，逐一清晰解释
- 关键算法/模式——识别算法、解释思路、说明复杂度
- 边界情况——处理的异常输入、做出的假设、执行的校验
将每次讲解组织为：
- 目的（是什么与为什么）
- 工作原理（带公式/逻辑的编号步骤）
- 为何采用此方法（理由与考虑过的替代方案）
- 处理的边界情况（列表与说明）
何时编写文档
始终编写文档：
- 公共 API 与端点
- 复杂算法
- 不明显的逻辑
- 安全敏感代码
- 性能关键部分
- 错误处理策略
考虑编写文档：
- 带多个参数的辅助函数
- 类构造函数
- 配置选项
- 数据库模式
不必编写文档：
- 平凡的 getter/setter
- 自解释的代码
- 临时/实验性代码
最佳实践
- 为未来的自己写作：假设 6 个月后你会忘掉一切
- 解释“为什么”，而非“做什么”：代码展示做什么，文档解释为什么
- 保持示例最新：代码变更时更新示例
- 使用一致格式：遵循语言惯例
- 保持简洁：每个词都应增加价值
- 使用主动语态：“Returns user”而非“User is returned”
- 包含边界情况：记录异常输入与输出
- 随代码更新：过时的文档比没有文档更糟
集成点
- 与 spec-driven 技能配合，用于功能文档
- 与 review 技能配合，验证文档是否存在
- 在功能完成后自动触发
备注
- 默认优先清晰代码而非注释（代码总是正确的，注释会说谎）
- 良好的命名可减少对文档的需求
- 复杂逻辑值得解释
- API 需要全面的文档
- 如有疑问，就写文档