代码文档

它解决什么问题

接手一个没人写文档的老项目，最先暴露的不是“文档太少”，而是“没人知道现在缺了哪份文档”。src/ 下几十个公开函数只有一半有 docstring，Python 用 NumPy 风格、TypeScript 用 JSDoc、Go 连注释块的位置都不对，CI 里也没有 doc lint。补文档变成一件靠人肉翻文件的体力活，最后往往只补了 README 的第一屏。

这个技能瞄准的就是这层摩擦：让 agent 自己遍历项目树，判断每个公开符号缺什么，再按项目已有的约定把文档写回去，而不是另起一份没人维护的 docs.md。

核心能力与工作方式

技能把流程拆成六个步骤，前两步决定了最终质量：

• 盘点代码库：遍历项目树，登记公开的模块、类、函数、常量和类型定义，并标注哪些已有文档、哪些缺失或已过期。这一步的产物是一份缺口清单，而不是直接开写。
• 确定文档范围：根据用户指令决定产出是内联 docstring、独立的 API 参考、项目级 README，还是三者组合。
• 分析签名与行为：逐符号核对参数类型、返回类型、默认值、抛出的异常和副作用。有测试文件时会读测试，用例本身往往比函数体更能说明意图。
• 生成文档：至少包含一行摘要、复杂逻辑的扩展说明、带类型的参数与返回值说明、异常文档，以及每个公开 API 至少一个调用示例。
• 原地插入或更新：内联文档直接写进符号上方或内部；README.md、API 参考这类独立文件则写到项目根目录或 docs/ 下。
• 校验与交叉引用：确认文档里的参数名与实际签名一致、引用的类型真实存在、示例语法合法，不一致的地方标记出来交用户确认。

支持的格式覆盖了主流语言生态：Python 的 Google-style / NumPy-style docstring 和 Sphinx reST，JavaScript / TypeScript 的 JSDoc 与 TypeDoc 注解，Java 的 Javadoc，Go 的 godoc 注释块，Rust 的 /// 文档注释与 #[doc] 属性，Ruby 的 YARD，以及 Markdown 层的 README、CHANGELOG 和 ADR。

适用边界与注意点

匹配项目现有风格优先于个人偏好。 如果代码库已经在用 NumPy-style docstring，就不要中途切到 Google-style。

写意图，不只是类型。 参数类型从签名上基本能看出来，真正有信息量的是约束、前置条件和不直观的行为。

私有内部逻辑默认不写。 过度文档化实现细节会制造维护负担，还会误导调用者依赖不稳定的接口。

文档随代码一起过期，所以要随代码一起更新。 理想情况是把文档校验放进 CI，让签名变更时文档校验同时失败。

几个容易踩的坑：运行时通过装饰器或插件注册的路由和方法，静态分析会漏掉，需要运行时内省或手动标注；TypeScript 的 overload 和 Python 的 @overload 要为每个签名变体单独写参数说明和示例；monorepo 应该生成根 README 再链接到各包文档，而不是堆成一份巨型文档；变量名和注释是非中文时，需要先确认文档语言；生成的 README 如果可能对外公开，记得剔除内部 URL、凭据和业务细节。