update-docs 的用途是在 API 发生变更后，跨整个仓库查找并修复过期的文档引用。它适用于函数或方法签名、类名与初始化签名、模块级常量与类型别名、被删除或重命名的公开符号发生改变之后。
执行流程分四步。第一步识别变更文件：运行 git diff --name-only main...HEAD -- '.py'；若相对 main 无变更，则回退到 git diff --name-only HEAD~1 -- '.py'，再失败则询问用户哪些文件改动。第二步提取 API 变更：对每个变更的 .py 文件用同一 ref 对比新旧签名，收集 (old_signature, new_signature) 对；若只有内部逻辑变化、无 API 变更，则报告“No API changes detected — no docs update needed”并停止。第三步通过 Task 工具启动 docs-updater 代理，subagent_type 为 general-purpose，description 字段必须包含“docs-updater”，并在提示中传入变更文件与 API 变更列表，要求其阅读 .claude/agents/docs-updater.md 并据此搜索整个仓库中旧 API 的引用并更新。第四步审查结果：核对更新报告、确认未触碰测试文件、确认改动最小且正确，并向用户汇报。
适用场景包括在 /implement 后 API 签名变化、在 /pre-submit-pr 前确保文档新鲜、重构公开 API 时。不适用场景包括仅内部变更、仅测试变更、仅文档变更。其工作流位置为：/write-tests 产生失败的测试，/implement 使其通过，/update-docs 修复仓库内过期文档，随后可选 /simplify 重构，最后 /pre-submit-pr 提交前校验。
限制：需要 git 仓库与可用的 Task 工具及 docs-updater 代理配置；具体收费、平台等信息暂未提供。