技能介绍

问题从哪来

新项目要交 README、接口要补 API 说明、发版要写变更日志、架构选型要留 ADR——格式各写各的，读者扫一遍抓不住重点，维护的人也不知道该补哪一节。更麻烦的是，2025 年起文档还要能被 RAG、MCP 和爬虫读懂：层级乱、缺示例、章节互相引用，模型索引质量会直接变差。

技能在做什么

本技能把常见文档类型拆成可复用的结构清单，按优先级告诉你「先写什么、后写什么」，而不是给一段空洞的范文。

README：标题与一句话描述 → 快速开始 → 特性 → 配置 → API 参考 → 贡献 → 许可证；表格里写明每节回答什么问题。
API 文档：按端点套同一套字段模板，避免有的接口写满、有的只留一行路径。
代码注释：对照表区分「该写为什么 / 契约」与「不必逐行解释显而易见实现」；附带 JSDoc/TSDoc 写法参考。
变更日志：对齐 Keep a Changelog 的章节习惯。
ADR：架构决策记录的固定骨架，方便事后追溯「当时为什么这么选」。
AI 友好文档：llms.txt 思路、面向 MCP 的说明方式，以及给 RAG 用的排版要求——清晰的 H1–H3、JSON/YAML 示例、流程用 Mermaid、章节尽量自包含。

文末还有四条结构原则（可扫读、示例优先、渐进式细节、保持最新），用来检查你改完的稿子是否还像工程师会维护的文档。

边界与注意点

模板是起点，不是审计标准：单体脚本、内部工具、开源库需要的章节深度不一样，可以删减章节，但不要为了「齐全」堆无信息量的占位段。技能不替你生成项目专属内容，也不替代你们团队已有的文档规范；若组织里已有 Confluence/Notion 模板，应以内部规范为准，用本技能补齐 README、ADR、AI 可读性等常见缺口。