代码文档生成器Skill code-documenter

---

名称: 代码文档生成器 描述: 为编码项目提供专家级文档生成。分析代码库，为开发者和用户创建全面、详尽的文档。支持增量更新、多受众文档、架构决策记录和文档健康跟踪。适用于任何项目类型（API、CLI、Web应用、库）。当您需要为新项目编写文档、添加功能后更新文档或为开源版本创建综合文档时使用。

代码文档生成技能

一个智能文档系统，分析代码库并根据项目类型和受众需求生成全面、详尽的文档。

核心理念

文档服务于读者，而非作者。 关于结构、深度和内容的每个决策都从读者角度评估：

• 这能帮助他们理解吗？
• 这能帮助他们成功吗？
• 这能回答他们的问题吗？
• 这值得存在吗？

全面而不令人不知所措。 彻底覆盖重要内容，无情剔除无关内容。目标是完整、准确、有用的文档——而非逐行代码的详尽文档。

文档作为代码工件。 文档应与代码一样严格进行版本控制、测试和维护。它们不是事后想法；它们至关重要。

何时使用此技能

主要使用场景：

• 完成重要新工作后（史诗、主要功能、新应用）
• 发布开源项目时
• 当文档与代码不同步时
• 当入职需要更好文档时
• 当正确设置新项目时

不适用于：

• 进行中的功能（等待稳定）
• 代码注释或文档字符串（此技能生成外部文档）
• 从代码生成API参考（使用语言特定工具）

会话流程

模式选择

技能以两种模式运行：

模式	何时使用	行为
快速模式	新功能后的增量更新	自主、快速、专注于变更内容
综合模式	新项目、重大修订、首次设置	协作、全面、全程质量关口

技能将询问： “快速更新还是综合文档？”

阶段1：多代理项目分析

技能部署专门分析代理以了解您的项目：

分析阶段：
├─ 代理1：项目结构
│  └─ 扫描文件树、识别项目类型、技术栈
├─ 代理2：代码表面分析  
│  └─ 查找API、组件、命令、导出
├─ 代理3：依赖分析
│  └─ 审查包、框架、关键依赖
├─ 代理4：Git历史分析
│  └─ 分析上次文档更新以来的提交
├─ 代理5：现有文档审查
│  └─ 阅读当前文档、评估状态
└─ 综合：生成文档计划...

快速模式： 专注于上次更新以来的变更分析
综合模式： 整个项目的完整分析

每个代理以结构化格式报告发现。您可以看到所有过程。

阶段2：文档状态评估

技能比较代码状态与文档状态：

如果存在清单（.doc-state.json）：

• 加载上次运行的文档状态
• 比较当前代码与上次记录的文档状态
• 识别变更内容（添加/修改/删除）
• 显示文档债务

如果无清单：

• 首次为此项目编写文档
• 完成后将创建新清单

显示的关键指标：

• 健康评分： 当前文档健康状况（0-100）
• 覆盖率： 公共表面的文档百分比
• 新鲜度： 文档与代码的当前程度
• 债务： 需要关注的内容（优先级）

阶段3：受众与范围发现

技能询问：

1. “谁需要这些文档？”

   • 仅开发者
   • 仅用户
   • 开发者和用户两者

2. “文档深度如何？”

   • 标准： 适当覆盖（4,000-7,000字）
   • 深度： 全面的内部文档（8,000-12,000字）

快速模式： 使用清单中存储的偏好
综合模式： 明确询问、显示示例

阶段4：文档边界

技能建议应记录的内容：

基于对您的Express + PostgreSQL API的分析：

公共表面（始终记录）
├─ /routes中的12个API端点
├─ 数据库架构（3个表）
├─ 14个环境变量
└─ 身份验证流程

内部实现（推荐用于深度）
├─ 6个中间件函数
├─ 错误处理模式
└─ 数据库迁移策略

基础设施（所有级别必需）
├─ Docker设置
├─ CI/CD管道
└─ 部署流程

排除内容（建议跳过）
├─ 测试文件（名称显而易见）
├─ 构建脚本（标准工具）
└─ 内部助手（每个<10行）

调整这些边界？ [批准/修改]

您在文档生成开始前批准或调整。

阶段5：文档计划呈现

技能呈现完整计划：

文档计划

结构：
└─ /docs
   ├─ developers/
   │  ├─ api.md（API端点参考）
   │  ├─ architecture.md（系统设计+图）
   │  ├─ contributing.md（如何贡献）
   │  ├─ deployment.md（部署与操作）
   │  ├─ troubleshooting.md（常见问题）
   │  ├─ examples/（12个可运行示例）
   │  └─ adr/（4个架构决策）
   ├─ users/
   │  ├─ getting-started.md（快速入门指南）
   │  ├─ features.md（功能概述）
   │  ├─ troubleshooting.md（面向用户的问题）
   │  └─ examples/（5个用户示例）
   ├─ CHANGELOG.md（文档变更日志）
   └─ documentation-map.md（导航指南）

要更新的文件：
- README.md（完整重写，逐步披露）
- docs/developers/api.md（2个新端点，1个修改）
- docs/CHANGELOG.md（新条目）

要创建的文件：
- docs/adr/004-caching-strategy.md（新决策）
- docs/developers/examples/pagination.js（新示例）

要删除的文件：
- docs/developers/legacy-auth.md（端点已删除）

估计范围：总计约5,200字
目标健康评分：92/100

继续？ [是/调整范围/中止]

综合模式： 生成前审查并批准
快速模式： 简要预览，选项审查或继续

阶段6：文档生成

综合模式（带质量关口）

技能分阶段处理文档，暂停审查：

关口1：核心文档（README + 快速入门）

• 生成逐步披露的README
• 创建快速入门指南
• 质量检查： 这能有效吸引和入职吗？
• 您审查并批准或请求更改

关口2：参考文档（API/命令/组件）

• 生成参考文档
• 创建工作示例
• 质量检查： 是否全面覆盖？示例清晰？
• 您审查并批准或请求更改

关口3：架构与决策

• 用Mermaid图记录架构
• 为关键决策创建ADR
• 质量检查： 这解释为什么吗？
• 您审查并批准或请求更改

关口4：支持文档

• 生成故障排除指南
• 创建贡献指南
• 文档导航图
• 质量检查： 完整且有用？
• 您审查并批准或请求更改

关口5：抛光与验证

• 为示例生成测试脚本
• 创建链接验证脚本
• 运行可访问性检查
• 最终健康评分计算
• 最终审查

快速模式（自主）

技能高效执行计划：

• 仅更新变更部分
• 保留未更改区域的手动编辑
• 根据需要生成新内容
• 更新清单和变更日志
• 报告最终结果

阶段7：会话完成

技能生成：

创建/更新的文件：

• 所有计划文档文件
• .doc-state.json（更新清单）
• docs/CHANGELOG.md（新条目）
• 测试和验证脚本

文档健康报告：

文档健康报告

总体健康评分：92/100（↑从78）

组件评分：
├─ 覆盖率健康：95/100（↑从82）
│  └─ 97%的公共表面已记录
├─ 新鲜度健康：98/100（↑从65）
│  └─ 所有文档截至提交a3f2b1c
├─ 质量健康：88/100（↑从81）
│  └─ 12个示例，4个ADR，故障排除完整
└─ 一致性健康：90/100（↑从84）
   └─ 语气一致，术语标准化

债务状态：
├─ 关键：0项（曾是2）
├─ 重要：1项（曾是4）
└─ 次要：3项（未变）

下次会话建议：
- 记录新的Webhook系统（标记为潜在）
- 添加性能故障排除部分
- 考虑在GitHub Pages托管文档

会话笔记：

• 做出的决策
• 范围调整
• 包括/排除内容及原因
• 下一步步骤

文件输出

核心文档结构

仅开发者项目：

/docs
├── CHANGELOG.md
├── api.md / commands.md / components.md
├── architecture.md
├── contributing.md
├── deployment.md
├── troubleshooting.md
├── examples/
│   ├── example-1.js
│   ├── example-2.js
│   └── test-examples.sh
├── adr/
│   ├── 001-initial-decisions.md
│   ├── 002-database-choice.md
│   └── ...
└── scripts/
    ├── validate-links.sh
    └── accessibility-check.md

多受众项目：

/docs
├── CHANGELOG.md
├── documentation-map.md
├── users/
│   ├── getting-started.md
│   ├── features.md
│   ├── troubleshooting.md
│   └── examples/
│       ├── basic-usage.js
│       └── advanced-usage.js
├── developers/
│   ├── api.md / architecture.md
│   ├── contributing.md
│   ├── deployment.md
│   ├── troubleshooting.md
│   ├── examples/
│   │   ├── integration.js
│   │   ├── extending.js
│   │   └── test-examples.sh
│   └── adr/
│       ├── 001-framework-choice.md
│       └── ...
└── scripts/
    ├── validate-links.sh
    └── accessibility-check.md

文档清单（.doc-state.json）

跟踪完整文档状态：

{
  "版本": "1.0",
  "项目": {
    "名称": "my-api",
    "类型": "express-api",
    "上次扫描": "2025-01-10T14:30:00Z",
    "Git提交": "a3f2b1c"
  },
  "偏好": {
    "受众": ["开发者", "用户"],
    "深度级别": "标准",
    "语气": "专业"
  },
  "健康评分": {
    "总体": 92,
    "组件": {
      "覆盖率": 95,
      "新鲜度": 98,
      "质量": 88,
      "一致性": 90
    },
    "趋势": [78, 85, 92]
  },
  "覆盖率": {
    "端点": {"总计": 12, "已记录": 12, "变更": 0},
    "组件": {"总计": 8, "已记录": 8, "变更": 0},
    "架构": {"总计": 3, "已记录": 3, "变更": 0}
  },
  "债务": {
    "关键": [],
    "重要": [
      {
        "项目": "记录Webhook系统",
        "工作量": "中等",
        "状态": "待修复"
      }
    ],
    "次要": [
      {
        "项目": "添加性能故障排除",
        "工作量": "低",
        "状态": "已接受"
      }
    ]
  },
  "文档地图": {
    "README.md": {
      "上次更新": "2025-01-10T14:30:00Z",
      "覆盖": ["概述", "快速入门"],
      "字数": 850
    },
    "docs/developers/api.md": {
      "上次更新": "2025-01-10T14:30:00Z",
      "覆盖": ["端点"],
      "字数": 2400
    }
  }
}

协作行为

综合模式中

主动贡献：

• “我注意到您使用Redis但没有ADR解释原因——我应该记录该决策吗？”
• “您的错误处理很复杂。这值得在架构文档中解释。”
• “身份验证流程非标准。用户会有疑问——让我解决它们。”

挑战假设：

• “您说‘标准深度’，但您有47个端点。那需要深度文档。”
• “这个‘快速入门’指南假设太多。您的用户不会知道X。”
• “这里三个示例不够。概念复杂。”

表面洞察：

• “您的Git历史显示您重构了身份验证3次。那是等待编写的ADR。”
• “这三个文件处理所有业务逻辑但完全未记录。差距。”
• “您有内联JSDoc但与markdown文档矛盾。一致性问题。”

快速模式中

高效执行：

• “基于提交a3f2b1c的变更更新3个文件…”
• “检测到2个新端点，添加到api.md…”
• “删除已删除的legacy-auth端点文档…”

标记关注：

• “警告：检测到architecture.md中的手动更改，保留您的编辑”
• “注意：由于新未记录功能，健康评分从92降至85”

质量标准

技能通过以下方式维护高文档质量：

清晰度

• 概念在使用前解释
• 技术术语首次使用时定义
• 示例在概念前或紧随其后
• 逐步披露（简单→复杂）

完整性

• 每个面向公共的元素记录
• 边缘情况和陷阱解决
• 可预测故障的故障排除
• 常见用例示例

准确性

• 所有事实根据代码验证
• 示例测试并工作
• 链接验证
• 无过时信息

可访问性

• 图包括替代文本
• 链接有描述性文本
• 标题层次逻辑
• 代码片段有语言标签

一致性

• 术语统一使用
• 语气全程保持
• 格式标准化
• 结构可预测

特殊功能

架构决策记录（ADR）

捕获决策的原因：

技能通过以下方式识别决策点：

• 主要依赖添加（Git历史）
• 非标准架构模式（代码分析）
• 框架/库选择
• 标记的“决策”语言提交
• 您的明确标识

每个ADR记录：

• 背景（情况是什么？）
• 决策（我们决定了什么？）
• 理由（为什么选择此？）
• 后果（接受的权衡）
• 考虑过的替代方案

活动、测试示例

可运行代码在/examples中：

• 实际工作（非伪代码）
• 覆盖常见用例
• 包括验证运行的测试脚本
• 从文档引用
• 随着代码演进维护

故障排除数据库

两种风格：

• 用户故障排除： 常见错误，如何修复
• 开发者故障排除： 调试指南、边缘情况、陷阱

技能在综合模式中植入初始内容，在快速模式中随着您添加真实故障排除内容增长。

文档地图

对于大型项目，导航指南：

• 不同学习路径（初学者/高级）
• 文档如何相互连接
• 何时阅读什么
• 视觉/文本导航辅助

Mermaid图

技能生成基于代码的图：

• 架构图
• 序列图
• 实体关系图
• 状态图
• 流程图

所有版本可控，所有在GitHub中渲染。

文档托管集成

检测您是否使用：

• GitHub Pages
• ReadTheDocs
• GitBook
• MkDocs

生成适当的配置文件并优化静态站点生成结构。

参考文档

需要时上下文加载：

• references/project-types-guide.md — 如何记录不同项目类型
• references/documentation-patterns.md — 常见文档模式和结构
• references/quality-standards.md — 详细质量标准示例
• references/manifest-spec.md — .doc-state.json的技术规范
• references/depth-levels-guide.md — 标准与深度解释及示例
• references/health-score-formula.md — 健康评分计算方式
• references/adr-guide.md — 编写有效架构决策记录

模板

在templates/中可用：

• README-template.md — 逐步披露README结构
• api-docs-template.md — API端点文档
• component-docs-template.md — 组件/模块文档
• troubleshooting-template.md — 故障排除指南结构
• contributing-template.md — 贡献指南
• documentation-map-template.md — 导航指南模板

成功标准

文档在以下情况完成：

✓ 健康评分 ≥ 85
✓ 所有关键和重要债务解决
✓ 示例运行无错误
✓ 链接验证成功
✓ 可访问性检查通过
✓ 语气全程一致
✓ 您确信有人可以仅从文档使用您的项目

关键提醒

• 始终读者为先： 每个决策服务读者
• Git感知： 智能增量更新，非重新生成
• 透明度： 您看到所有分析和决策
• 保持质量： 不覆盖良好手动编辑
• 测试示例： 为工作代码生成测试脚本
• 跟踪健康： 健康评分随时间趋势
• 优先债务： 并非所有债务平等
• 全面而非详尽： 记录重要内容