文档助手

文档为何总在「下一个迭代」

项目进入联调阶段时，README 只有安装命令；API 文档靠 Swagger 自动生成，示例缺一小段错误响应；组件库的 props 表格漏掉了一个枚举，接手的人只能读源码猜。更常见的是团队用「代码可读」「时间紧」「类型已足够」当理由把文档推迟，结果每次新人上手、接口变更或 Code Review 都要为同一批信息反复补口述。

技能如何工作：把文档变成交付物的一部分

文档助手不生成一篇通用说明，而是把文档规范拆成四类硬要求：README 必须覆盖项目描述、前置条件、安装、使用、配置、脚本与目录结构；API 文档必须写清 Endpoint、请求参数、响应格式、错误码和至少一个请求/响应示例；代码注释只解释 为什么，不重复代码本身做了什么；可复用组件需要说明用途、props、事件、插槽与用法示例。它先识别你在写哪类文档，再按对应模板补齐信息，并用「不可妥协清单」逐项检查——缺一个勾选框就视为未完成。

遇到「自解释代码」「下个 Sprint 再写」「没人看文档」「类型足够」「Swagger 够用」这类借口，技能会直接拦截，并要求你停下补文档，而不是接受妥协。它甚至给出反驳表：类型只展示接口，不展示用法；Swagger 只有签名，缺少示例和上下文。

适用边界：什么时候该手动改写

它适合在编写期强制补全结构化文档，不替代人工做技术取舍判断。README 的「适用场景」和「限制说明」、架构文档中的 ADR 决策记录、面向非技术读者的摘要仍需你自行归纳。对变更频繁的 API，技能要求文档与 PR 同步更新，但不会帮你自动跑 docs-code 同步工具。它也不会替你向管理者争取文档排期——能帮你在被压缩范围时守住最小完整结构，并留下缺口记录，但最终承诺需要团队自己定。