documentation-writer · 基于代码事实的技术文档

路径约定：references/、scripts/、assets/ 都相对于本 SKILL.md 所在目录。运行脚本前先设 SKILL_DIR="<本 SKILL.md 所在目录>"；文档路径、仓库根等参数按目标仓填写。

这份 skill 要的文档有三个特点：说的都是仓库里真实存在的东西；读者拿到就能用（命令能跑、例子能抄、图能看懂）；读起来像熟悉这套代码的工程师写的，不像模型生成的。三者冲突时，准确优先。

选文档类型

用户要的	读者	先读	默认位置（仓库已有约定时从约定）
README：新建、补全、按代码变更同步	第一次接触项目的人	references/readme.md	仓库根或子包根的 `README.md`
API 文档：HTTP 接口、OpenAPI、库 / SDK 参考	调用方开发者	references/api-docs.md	`docs/api/` 或服务目录下 `docs/`
架构文档：系统怎么搭起来、为什么这样搭	新加入的工程师、评审者	references/architecture.md	`docs/architecture.md` 或 `ARCHITECTURE.md`
代码库说明：成套的结构、约定、功能、测试、风险文档	日常改代码的人和 AI agent	references/codebase-map.md	`docs/codebase/`
用户手册、教程、操作指南、运维手册	最终用户、运营、运维	references/user-manual.md	`docs/user-guide/` 或 `docs/manual/`

架构文档和代码库说明容易混。用户要一份能从头读到尾的「系统是怎么工作的」，走架构文档；要一套放在仓库里、按主题随查随用的参考（技术栈、目录、约定、功能清单、测试、风险），或者明确说「代码库说明 / 功能说明 / map this codebase」，走代码库说明。拿不准时问一句，问不了就写架构文档，并在交付说明里提一句另一种选择。

一个请求涉及多类文档（比如「给这个服务写 README 和接口文档」），按类型分别读对应参考，各写各的，互相链接，不要把 API 参考塞进 README。