docs-architectlisted

## 何时使用 当需要把一个**现有代码库**提炼成长篇、权威的技术参考文档时使用，典型产物为 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` 格式。 ## 示例 为一个微服务后端生成文档时的骨架： ```markdown # 订单系统技术手册 ## 1. 执行摘要 （一页：系统做什么、为谁服务、核心能力） ## 2. 架构总览 （系统边界 + 组件交互图，文字详述） ## 4. 核心组件 ### 4.1 OrderService - 职责：…… - 关键实现见 `src/order/service.go:42` - 设计取舍：为什么采用 Saga 而非两阶段提交…… ``` > 提示��每个「设计决策」都要回答「为什么不是另一种方案」，这是综合技术文档区别于普通 README 的关键。 ## 注意事项 - 仅在任务明确落入上述范围时使用本技能。 - 产出不能替代环境相关