Docs architect

何时使用

当需要把一个现有代码库提炼成长篇、权威的技术参考文档时使用，典型产物为 10–100+ 页的技术手册、架构白皮书或电子书，既讲「是什么（what）」也讲「为什么（why）」。适用场景：

• 为新人 onboarding、架构评审、长期维护沉淀系统级文档。
• 需要梳理系统边界、核心组件、数据流、集成点与设计决策的来龙去脉。
• 需要分受众（开发、架构师、运维）提供阅读路径。

不该用边界：

• 任务与代码库文档无关，或属于其他领域/工具范畴。
• 只需单文件注释、README 速写、changelog 或自动抽取的 API 参考——本技能是「长篇综合」而非「片段速记」。
• 缺少必要输入（代码访问权限、目标受众、成功标准）时，先停下来澄清，不要凭空臆造。

步骤

1. 发现（Discovery）：分析代码库结构与依赖，识别关键组件及其关系，提取设计模式与架构决策，绘制数据流与集成点。
2. 结构化（Structuring）：建立逻辑化的章节层级，设计「渐进式复杂度披露」（先全局后细节），规划图表与可视化，统一术语表。
3. 写作（Writing）：从执行摘要与总览起笔，由高层架构逐步下沉到实现细节，对每个设计决策给出 rationale（为什么这么选），并配带充分解释的代码示例。

指令

• 先澄清目标、约束与必需输入，再动笔。
• 套用相关最佳实践，并验证产出是否自洽、可导航。
• 给出可执行步骤与验证方式；若需要详尽样例，打开 resources/implementation-playbook.md。
• 始终解释设计决策背后的「为什么」，用代码库中的真实例子而非杜撰。
• 同时记录当前状态与演进历史，附上排错指南与常见坑。
• 为不同受众（developers / architects / operations）提供独立阅读路径。

建议包含的关键章节：

1. 执行摘要（一页，面向干系人）
2. 架构总览（系统边界、关键组件、交互）
3. 设计决策（架构取舍的 rationale）
4. 核心组件（逐个模块/服务深入）
5. 数据模型（Schema 设计与数据流）
6. 集成点（API、事件、外部依赖）
7. 部署架构（基础设施与运维考量）
8. 性能特征（瓶颈、优化、基准）
9. 安全模型（认证、授权、数据保护）
10. 附录（术语表、参考、详细规格）

输出格式约束（保留源约束）： 使用 Markdown，要求清晰的标题层级；代码块带语法高亮；结构化数据用表格；列表用项目符号；重要提示用引用块（blockquote）；指向源码的链接统一用 file_path:line_number 格式。

示例

为一个微服务后端生成文档时的骨架：

# 订单系统技术手册

## 1. 执行摘要
（一页：系统做什么、为谁服务、核心能力）

## 2. 架构总览
（系统边界 + 组件交互图，文字详述）

## 4. 核心组件
### 4.1 OrderService
- 职责：……
- 关键实现见 `src/order/service.go:42`
- 设计取舍：为什么采用 Saga 而非两阶段提交……

提示：每个「设计决策」都要回答「为什么不是另一种方案」，这是综合技术文档区别于普通 README 的关键。

注意事项

• 仅在任务明确落入上述范围时使用本技能。
• 产出不能替代环境相关的验证、测试或专家评审。
• 若缺少必需输入、权限、安全边界或成功标准，停下来询问澄清。
• 图表（架构图、时序图、流程图）即使无法直接绘制，也要用文字详细描述到可据此还原的程度。

互见

• README / API 参考类轻量文档需求：改用更聚焦的速写型技能或文档生成器。
• 涉及飞书在线协作产物时，可结合 lark-doc、lark-wiki 将本地 Markdown 导入为云文档。

---

采编自 sickn33/antigravity-awesome-skills（MIT）。