用途
docs-agent 是面向多智能体构建流程的文档生成角色技能，仅由编排器（orchestrator）调度使用。它在契约编写完成后被生成，读取 contract-author 在 /contracts/ 中的输出，为项目生成开发者文档。该技能假设采用契约优先的多智能体构建模型：编排器并行派发角色智能体，每个角色智能体消费 /contracts/ 中的机器可读契约，qe-agent 通过 qa-report.json 对构建进行门禁。对于单智能体或临时性工作，此技能不适用。
主要能力
- 生成 README.md（第 14 阶段交付物），包含项目描述、技术栈摘要、前置条件与安装说明、运行方式（开发、测试、构建、部署）、环境变量表、API 概览、项目结构概览。
- 生成 API 文档：记录每个端点的方法、路径、描述、请求/响应示例，包含认证要求、错误码与错误结构，并提供常用操作的 curl 示例。
- 生成架构文档：系统概览图（文本形式，如 ASCII 或 Mermaid）、组件职责、数据流描述、集成点。
- 生成 CHANGELOG.md：采用 Keep a Changelog 格式，按 Added、Changed、Deprecated、Removed、Fixed、Security 分组。
- 维护 CONTRIBUTING.md。
使用方式
该技能由编排器在契约编写完成后调度。输入来自 lead：plan_excerpt（描述项目范围与功能的构建计划相关章节）、contracts（OpenAPI 规范、共享类型定义和接口契约）、tech_stack（使用的语言、框架和工具）、ownership（文件所有权映射，用于了解其他智能体产出什么）。
处理流程：
-
阅读契约与源代码：在编写任何文档之前，先阅读 /contracts/ 中的集成契约（API 规范、共享类型、数据层），并浏览将要记录的源代码。与契约矛盾的文档比没有文档更糟——先加载事实来源。
-
README.md（第 14 阶段交付物）：编排器在第 14 阶段专门生成该技能来编写具有全系统上下文的 README.md。使用 references/doc-templates.md 中的模板。
-
API 文档：如果项目有 API，记录每个端点，包含认证要求、错误码与结构、curl 示例。
-
架构文档：对于复杂项目，提供系统概览图、组件职责、数据流、集成点。
-
CHANGELOG.md：跟踪重要变更，使用 Keep a Changelog 格式。
所有权与边界
拥有：docs/、README.md、CHANGELOG.md、CONTRIBUTING.md。
排除区（不属于该技能，即使位于 docs/ 下）：docs/agents/ 由 setup-project-skills 专属拥有；docs/adr/ 由 maintain-context 专属拥有。可以阅读它们以获取上下文，但绝不写入——目录所有权是排他的，这两个子树从 docs/ 所有权中排除。
只读：其他所有内容。
禁止访问：src/、配置文件、测试文件、docs/agents/、docs/adr/。
协调规则
- 绝不修改应用代码——仅文档。
- 契约是 API 文档的事实来源——不要从代码猜测。
- 保持简洁——开发者是浏览而非阅读小说。
- 包含可工作的示例——每个 API 端点都需要一个可用的 curl 命令。
- backend-agent：阅读其 API 契约和源代码以编写端点文档；他们拥有 src/——该技能记录它，但不触碰它。
- frontend-agent：阅读其组件结构以编写面向用户的功能文档；他们拥有 src/components/ 及相关 UI 代码。
- infrastructure-agent：阅读其 Docker/部署配置以编写安装和部署文档；他们拥有 docker-compose.yml、Dockerfile 和基础设施配置。
验证
在报告完成之前，运行 references/doc-templates.md 检查清单：
- README.md 具有与实际项目设置匹配的可工作 Quick Start。
- 契约中的所有 API 端点都已记录，并带有 curl 示例。
- 项目结构概览与实际文件树匹配。
- CHANGELOG 遵循 Keep a Changelog 格式。
- 没有损坏的内部链接。
适用场景与限制
适用场景：契约优先的多智能体构建流程，由编排器调度，需要为项目生成开发者文档。
限制：仅由编排器调度使用，不适用于单智能体或临时性工作。不编写应用代码。docs/agents/ 和 docs/adr/ 为专属排除区，不可写入。qe-agent 会在其 completeness 和 code_quality 评分中权衡文档质量，但这些评分被记录，并不对构建进行门禁——构建门禁仅在 CRITICAL 阻塞、contract_conformance.score < 3 或 security.score < 3 时阻止。文档工作不会通过 completeness/code_quality 阻止构建，但仍应交付完整、准确的文档：薄弱的文档会降低记录的评分，并可能被引用为问题，而严重缺口（例如与契约矛盾的文档）可能被提升为 CRITICAL 阻塞。