code-documenter

Code Documenter Skill

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

核心理念

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

• 这能帮助他们理解吗？
• 这能帮助他们取得成功吗？
• 这能回答他们的问题吗？
• 这项内容值得保留吗？

全面而不冗杂。 充分涵盖重要内容，果断删去无关内容。目标是生成完整、准确且实用的文档，而非详尽记录每一行代码。

将文档视为代码产物。 文档应像代码一样进行版本管理、测试和维护，遵循同等严格的标准。文档不是事后补充，而是不可或缺的一部分。

何时使用此技能

主要使用场景：

• 完成重要的新工作后（史诗级任务、重大功能、新应用）
• 发布开源项目时
• 文档与代码不同步时
• 入门指导需要更完善的文档时
• 规范地搭建新项目时

不适用于：

• 尚在开发中的功能（等稳定后再处理）
• 代码注释或文档字符串（此工具生成的是外部文档）
• 根据代码生成 API 参考文档（请使用相应语言的工具）

会话流程

模式选择

此技能以两种模式运行：

模式	适用场景	行为
快速模式	新功能完成后的增量更新	自主、快速，专注于变更内容
全面模式	新项目、重大改造、首次设置	协作、详尽，全程设有质量关卡

此技能会询问：“快速更新还是全面编写文档？”

阶段 1：多 Agent 项目分析

此技能会调度专门的分析 Agent 来了解你的项目：

Analysis Phase:
├─ Agent 1: Project Structure
│  └─ Scanning file tree, identifying project type, tech stack
├─ Agent 2: Code Surface Analysis
│  └─ Finding APIs, components, commands, exports
├─ Agent 3: Dependency Analysis
│  └─ Reviewing packages, frameworks, key dependencies
├─ Agent 4: Git History Analysis
│  └─ Analyzing commits since last doc update
├─ Agent 5: Existing Documentation Review
│  └─ Reading current docs, assessing state
└─ Synthesis: Generating documentation plan...

快速模式： 专注分析自上次更新以来的变更
全面模式： 全面分析整个项目

每个 Agent 都会以结构化格式报告结果。你可以看到整个过程。

阶段 2：文档状态评估

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

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

• 加载上次运行时的文档状态
• 比较当前代码与上次记录的状态
• 确认发生了哪些变更（新增／修改／移除）
• 显示文档欠账

如果没有清单文件：

• 这是首次为此项目编写文档
• 完成后会创建新的清单文件

显示的关键指标：

• 健康评分： 当前文档健康度（0-100）
• 覆盖率： 已记录的公共接口占比（%）
• 新鲜度： 文档与代码的同步程度
• 欠账： 需要处理的事项（按优先级排序）

阶段 3：受众与范围确认

此技能会询问：

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

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

2. “需要多深入的文档？”

   • 标准： 适度覆盖（4,000-7,000 字）
   • 深入： 全面介绍内部细节（8,000-12,000 字）

快速模式： 使用清单文件中保存的偏好
全面模式： 明确询问并展示示例

阶段 4：文档范围

此技能会提出需要编写文档的内容：

Based on my analysis of your Express + PostgreSQL API:

PUBLIC SURFACE (Always Document)
├─ 12 API endpoints in /routes
├─ Database schema (3 tables)
├─ 14 environment variables
└─ Authentication flow

INTERNAL IMPLEMENTATION (Recommended for Deep)
├─ 6 middleware functions
├─ Error handling patterns
└─ Database migration strategy

INFRASTRUCTURE (Essential for all levels)
├─ Docker setup
├─ CI/CD pipeline
└─ Deployment process

EXCLUDED (Recommend skip)
├─ Test files (obvious from names)
├─ Build scripts (standard tooling)
└─ Internal helpers (<10 lines each)

Adjust these boundaries? [approve/modify]

开始生成文档前，你可以批准或调整方案。

阶段 5：展示文档计划

此技能会展示完整计划：

DOCUMENTATION PLAN

Structure:
└─ /docs
   ├─ developers/
   │  ├─ api.md (API endpoint reference)
   │  ├─ architecture.md (System design + diagrams)
   │  ├─ contributing.md (How to contribute)
   │  ├─ deployment.md (Deploy & operate)
   │  ├─ troubleshooting.md (Common issues)
   │  ├─ examples/ (12 runnable examples)
   │  └─ adr/ (4 architecture decisions)
   ├─ users/
   │  ├─ getting-started.md (Quick start guide)
   │  ├─ features.md (Feature overview)
   │  ├─ troubleshooting.md (User-facing issues)
   │  └─ examples/ (5 user examples)
   ├─ CHANGELOG.md (Documentation change log)
   └─ documentation-map.md (Navigation guide)

Files to update:
- README.md (complete rewrite, progressive disclosure)
- docs/developers/api.md (2 new endpoints, 1 modified)
- docs/CHANGELOG.md (new entry)

Files to create:
- docs/adr/004-caching-strategy.md (new decision)
- docs/developers/examples/pagination.js (new example)

Files to remove:
- docs/developers/legacy-auth.md (endpoint removed)

Estimated scope: ~5,200 words total
Target health score: 92/100

Proceed? [yes/adjust scope/abort]

全面模式： 生成前审阅并批准
快速模式： 简要预览，可选择审阅或继续

阶段 6：生成文档

全面模式（包含质量关卡）

该技能分阶段处理文档，并在各阶段暂停以供审阅：

关卡 1：核心文档（README + 入门指南）

• 采用渐进式披露生成 README
• 创建入门指南
• 质量检查：能否有效吸引用户并帮助他们入门？
• 由你审阅并批准，或提出修改要求

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

• 生成参考文档
• 创建可运行的示例
• 质量检查：是否涵盖所有内容？示例是否清晰？
• 由你审阅并批准，或提出修改要求

关卡 3：架构与决策

• 使用 Mermaid 图表记录架构
• 为关键决策创建 ADR
• 质量检查：是否解释了背后的原因？
• 由你审阅并批准，或提出修改要求

关卡 4：辅助文档

• 生成故障排查指南
• 创建贡献指南
• 创建用于导航的文档地图
• 质量检查：内容是否完整且实用？
• 由你审阅并批准，或提出修改要求

关卡 5：润色与验证

• 为示例生成测试脚本
• 创建链接验证脚本
• 运行无障碍检查
• 计算最终健康评分
• 最终审阅

快速模式（自主执行）

该技能高效地执行计划：

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

阶段 7：完成会话

该技能将生成：

创建/更新的文件：

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

文档健康报告：

DOCUMENTATION HEALTH REPORT

Overall Health Score: 92/100 (↑ from 78)

Component Scores:
├─ Coverage Health: 95/100 (↑ from 82)
│  └─ 97% of public surface documented
├─ Freshness Health: 98/100 (↑ from 65)
│  └─ All docs current as of commit a3f2b1c
├─ Quality Health: 88/100 (↑ from 81)
│  └─ 12 examples, 4 ADRs, troubleshooting complete
└─ Consistency Health: 90/100 (↑ from 84)
   └─ Tone consistent, terminology standardized

Debt Status:
├─ Critical: 0 items (was 2)
├─ Important: 1 item (was 4)
└─ Minor: 3 items (unchanged)

Next session recommendations:
- Document the new webhook system (flagged as potential)
- Add performance troubleshooting section
- Consider hosting docs on 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）

跟踪完整的文档状态：

{
  "version": "1.0",
  "project": {
    "name": "my-api",
    "type": "express-api",
    "lastScanned": "2025-01-10T14:30:00Z",
    "gitCommit": "a3f2b1c"
  },
  "preferences": {
    "audiences": ["developers", "users"],
    "depthLevel": "standard",
    "tone": "professional"
  },
  "healthScore": {
    "overall": 92,
    "components": {
      "coverage": 95,
      "freshness": 98,
      "quality": 88,
      "consistency": 90
    },
    "trend": [78, 85, 92]
  },
  "coverage": {
    "endpoints": { "total": 12, "documented": 12, "changed": 0 },
    "components": { "total": 8, "documented": 8, "changed": 0 },
    "schemas": { "total": 3, "documented": 3, "changed": 0 }
  },
  "debt": {
    "critical": [],
    "important": [
      {
        "item": "Document webhook system",
        "effort": "medium",
        "status": "to-fix"
      }
    ],
    "minor": [
      {
        "item": "Add performance troubleshooting",
        "effort": "low",
        "status": "accepted"
      }
    ]
  },
  "documentationMap": {
    "README.md": {
      "lastUpdated": "2025-01-10T14:30:00Z",
      "covers": ["overview", "quickstart"],
      "wordCount": 850
    },
    "docs/developers/api.md": {
      "lastUpdated": "2025-01-10T14:30:00Z",
      "covers": ["endpoints"],
      "wordCount": 2400
    }
  }
}

协作行为

全面模式下

主动提出建议：

• “我注意到你在使用 Redis，但没有 ADR 解释原因——要我记录这项决策吗？”
• “你的错误处理很完善，值得在架构文档中加以说明。”
• “身份验证流程并不常见，用户会有疑问——我来解释一下。”

质疑假设：

• “你说的是‘标准深度’，但你有 47 个端点。这需要深入的文档说明。”
• “这份‘入门’指南默认了太多前提。你的用户可能不了解 X。”
• “这里仅有 3 个示例并不够，这个概念比较复杂。”

揭示洞见：

• “你的 git 历史显示，你重构了 3 次身份验证逻辑。这正是有待编写的 ADR。”
• “这 3 个文件处理了所有业务逻辑，却完全没有文档说明。存在缺口。”
• “你有内联 JSDoc，但它与 Markdown 文档中的内容相矛盾，存在一致性问题。”

快速模式下

高效执行：

• “根据提交 a3f2b1c 中的变更更新 3 个文件……”
• “检测到 2 个新端点，正在添加到 api.md……”
• “已移除有关已删除的 legacy-auth 端点的文档……”

标记问题：

• “警告：检测到 architecture.md 中有手动修改，正在保留你的编辑”
• “注意：由于新增功能尚未编写文档，健康评分从 92 降至 85”

质量标准

该技能通过以下方式保持高质量的文档：

清晰度

• 先解释概念，再使用概念
• 首次出现时定义技术术语
• 示例置于概念之前或紧随其后
• 渐进式披露（从简单到复杂）

完整性

• 记录每个面向公众的元素
• 说明边缘情况和注意事项
• 为可预见的故障提供故障排查指南
• 为常见用例提供示例

准确性

• 根据代码核实所有事实
• 测试示例并确保其可运行
• 验证链接
• 不保留过时信息

无障碍性

• 图表包含替代文本
• 链接文字具有描述性
• 标题层级合乎逻辑
• 代码片段标注了语言

一致性

• 术语使用统一
• 全文语气一致
• 格式规范统一
• 结构清晰可预测

特殊功能

架构决策记录（ADR）

记录做出决策的原因：

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

• 添加主要依赖项（Git 历史记录）
• 非标准架构模式（代码分析）
• 框架／库的选择
• 标记为包含“decision”字样的提交
• 你明确指出的决策

每份 ADR 都会记录：

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

持续更新且经过测试的示例

/examples 中的示例是可运行代码：

• 确实可运行（不是伪代码）
• 覆盖常见用例
• 包含用于验证运行情况的测试脚本
• 在文档中提供引用
• 随代码演进而维护

故障排除数据库

分为两类：

• 用户故障排除： 常见错误及其解决方法
• 开发者故障排除： 调试指南、边缘情况和注意事项

该技能会在 Comprehensive Mode 中填充初始内容，并在你添加实际故障排除内容时于 Quick Mode 中逐步扩充。

文档地图

适用于大型项目的导航指南：

• 不同的学习路径（初级／高级）
• 文档之间的关联方式
• 不同阶段应阅读的内容
• 可视化／文本导航辅助

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 — 通过示例说明 Standard 和 Deep
• 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： 智能增量更新，而非重新生成
• 透明： 你可以查看所有分析和决策
• 保持质量： 不要覆盖优质的手动修改
• 测试示例： 为可运行代码生成测试脚本
• 跟踪健康度： 关注健康度评分随时间的变化趋势
• 优先处理待改进项： 并非所有待改进项都同等重要
• 全面但不穷尽： 记录重要内容