# 文档技能 **您必须执行此工作流程。不要只是描述它。** 生成并验证任何项目的文档。 ## 执行步骤给定 `/doc [命令] [目标]`： ### 第 1 步：检测项目类型 # 检查指标 ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null # 检查现有文档 ls -d 文档/ doc/ 文档/ 2>/dev/null 分类为： * **CODING** ：有源代码，需要 API 文档 * **信息**：主要是文档（wiki、知识库） * **OPS** ：基础设施、部署、运行手册 ### 第2步：执行命令 **发现** \- 查找未记录的功能： # 查找没有文档字符串的公共函数 (Python) grep -r "^def " --include="*.py" | grep -r "^def " --include="*.py" | grep -r "^def " --include="*.py" | grep -v '"""' | head -20 # 查找没有注释的导出函数（Go） grep -r "^func [A-Z]" --include="*.go" | grep -r "^func [A-Z]" --include="*.go" |头-20 **覆盖率** \- 检查文档覆盖率： # 记录记录与未记录记录的计数总计=$(grep -r "^def \|^func \|^class " --include="*.py" --include="*.go" | wc -l) 记录=$(grep -r '"""' --include="*.py" | wc -l) echo“覆盖范围：$DOCUMENTED / $TOTAL” **gen [feature]** \- 生成文档： 1. 阅读该功能的代码 2.了解它的作用 3. 生成适当的文档 4.写入docs/目录 **全部** \- 更新所有文档： 1.运行discover来寻找差距 2. 为每个未记录的功能生成文档 3. 验证现有文档是否最新 ### 第 3 步：生成文档生成文档时，包括： **对于函数/方法：** ## 函数名 **目的：** 它的作用 **参数：** - `param1`（类型）：描述 - `param2`（类型）：描述 **返回：** 返回什么 **示例：** ````蟒蛇结果 = 函数名称(arg1, arg2) **注释：** 任何重要的警告 **对于课程：** ``降价 ## 类名 **目的：** 这个类代表什么 **属性：** - `attr1`：描述 - `attr2`：描述 **方法：** - `method1()`：它的作用 - `method2()`：它的作用 **用途：** ````蟒蛇 obj = 类名() obj.method1() ### 步骤 4：创建代码映射（如果需要） **写入：** `docs/code-map/` ``降价 # 代码图：<项目> ## 概述 <高层架构> ## 目录结构 src/ ├── module1/ # 用途 ├── module2/ # 用途 └── utils/ # 共享实用程序 ## 关键组件 ### 模块 1 - **目的：** 它的作用 - **入口点：** `main.py` - **关键文件：** `handler.py`、`models.py` ### 模块 2 ... ## 数据流 <数据如何在系统中移动> ## 依赖关系 <外部依赖以及原因> ### 第 5 步：验证文档检查： * 过时的文档（代码更改，文档未更改） * 缺少部分（没有示例，没有参数） * 损坏的链接 * 格式不一致 ### 第 6 步：撰写报告 **写入：** `.agents/doc/YYYY-MM-DD-<目标>.md` # 文档报告：<目标> **日期：** YYYY-MM-DD **项目类型：** <编码/信息/OPS> ## 覆盖范围 - 可记录项目总数： - 记录：<计数> - 覆盖率：<百分比>% ## 生成 - <生成的文档列表> ## 发现差距 - <未记录的项目 1> - <未记录的项目 2> ## 验证问题 - <问题1> - <问题2> ## 后续步骤 - [ ] 记录剩余间隙 - [ ] 修复验证问题 ### 步骤 7：向用户报告告诉用户： 1. 文档覆盖率 2. 文档生成/更新 3. 剩余差距 4. 报告地点 ## 关键规则 * **首先检测项目类型** \- 方法各不相同 * **生成有意义的文档** \- 不仅仅是存根 * **包括示例** \- 始终显示用法 * **验证现有** \- 文档可能会过时 * **撰写报告** \- 跟踪一段时间内的覆盖范围 ## 命令总结命令 |行动 ---|--- `发现` |查找未记录的功能 `覆盖范围` |检查文档覆盖范围 `gen [功能]` |为特定功能生成文档 `全部` |更新所有文档 `验证` |检查文档匹配代码 ## 示例 ### 生成API文档 **用户说：** `/doc gen 身份验证` **发生了什么：** 1. Agent 通过检查 `package.json` 并查找 Node.js 项目来检测项目类型 2. Agent 使用 grep 在代码库中搜索与身份验证相关的函数 3. Agent读取认证模块文件以了解实现 4. 代理生成包含目的、参数、返回和使用示例的文档 5. Agent使用代码示例写入`docs/api/authentication.md` 6. 代理验证生成的文档是否与实际函数签名匹配 **结果：** 为身份验证模块创建了完整的 API 文档以及工作代码示例。 ### 检查文档覆盖范围 **用户说：** `/doc 覆盖率` **发生了什么：** 1. Agent从`pyproject.toml`中检测Python项目 2. Agent 使用 `grep -r "^def \|^class "` 计算函数/类总数 3. 代理通过搜索文档字符串（`"""`）来对记录的项目进行计数 4. 代理计算覆盖率：45/67 项 = 67% 覆盖率 5. Agent将报告写入`.agents/doc/2026-02-13-coverage.md` 6. 代理将 22 个未记录的功能列为空白 **结果：** 文档覆盖率报告显示覆盖率达到 67%，其中包含需要文档的 22 个函数的具体列表。 ## 故障排除问题 |原因 |解决方案 ---|---|--- 覆盖率计算不准确 | Grep 模式并不匹配所有代码风格 |调整项目惯例的模式。对于 Python，检查“async def”和类方法。对于 Go，请检查“func”和“type”定义。生成的文档缺少示例 |缺少有关典型用法的上下文 |阅读现有测试以查找使用模式。检查 README 中的代码示例。如果不清楚，请询问用户典型的用例。 Discover 命令发现太多项目 |现有文档覆盖率低 |通过在特定子目录上运行“discover”来确定优先级。首先关注公共 API，然后关注内部实用程序。使用`--limit`来批量处理。验证显示文档不同步 |文档编写后代码发生了变化 |对受影响的功能重新运行“gen”命令。考虑添加 git hook 来标记代码更改时所需的文档更新。 ## 参考文档 * [references/ Generation-templates.md]() * [references/project-types.md]() * [references/validation-rules.md]()

文档

包含技能