architecture-docs

用途

Architecture Docs 是一个面向人类读者的架构文档编写与重构技能。它用于生成帮助读者快速理解以下内容的文档：

该技能强调架构文档应可视化优先、保持简单。

除非仓库有明确的本地例外，否则将规范架构文档放在 docs/architecture/ 目录。
面向人类快速理解而写，而不是追求详尽的实现细节。
以简短的平实英文说明开头。
优先在文档顶部附近放置一个简单的 Mermaid flowchart TD 图。
图表保持高层、可读。
当一个图会混合过多层级或关注点时，优先使用渐进式披露：从最简单有用的概览开始，再添加 Level 2 / Level 3 的放大图，而不是强行塞入一张密集的图。
将精确字段名、环境变量、限制、命令、模式以及运维契约推入 docs/references/。
如果仓库本地文档指南与本技能冲突，遵循仓库本地文档契约。

工作流程如下：

先阅读仓库本地文档契约，尤其是根目录 AGENTS.md、docs/AGENTS.md 以及相关的现有 docs/architecture/* 页面。
判断所请求的文档是否真的是架构文档。如果主要涉及系统形态、边界、流程或主要权衡，保留在 docs/architecture/；如果主要涉及精确事实或查找规则，放入 docs/references/。不确定时可阅读 references/02-architecture-vs-references.md。
只收集解释系统所需的最小上下文，聚焦主要组件、边界和流程，避免把底层实现细节倾倒入架构文档。
按以下顺序起草文档：简短的平实英文概览、Mermaid flowchart TD、解释主要流程或边界的简短章节、必要时关于权衡或重要约束的简短说明；对于更大的系统，使用 Level 1 / Level 2 / Level 3 结构，使每张图解释一个想法。
保持图表简单：使用少量有意义的节点和连接，而不是每个内部细节；容器标签保持被动，箭头应连接真实组件而非块标题；仅在能实质性提升可扫描性时使用一致的区域着色。编写或重构图表前阅读 references/01-mermaid-guidelines.md。
保持文档易于略读：使用短章节、直接措辞、最少术语。如果目标渲染器可用，验证实际渲染效果并根据人类真正看到的内容进行改进。
如果需要精确事实，在 docs/references/ 中创建或更新配套文档并链接。

默认文档结构（除非仓库已有强本地模式）：标题、2-4 句平实英文概览、Mermaid flowchart TD、主要部分/边界、主要流程、关键权衡或说明、必要时指向更深层参考的链接。更完整的模板见 references/00-doc-shape.md。

架构文档应回答：

架构文档通常不应回答：每个字段名、每个 API 参数、精确的环境变量列表、每个缓存键或模式细节、逐步运维手册。这些属于 docs/references/。