architecture-md-writer

ARCHITECTURE.md 编写指南

编写架构文档，帮助贡献者快速了解系统结构、入手位置和不可妥协的约束。优先保持结构稳定，而非罗列实现细节；除非现有 ARCHITECTURE.md 的范围不合适，否则优先编辑现有文档，而不是新建文档。

工作流

1. 确定范围和文档结构。

• 检查任务针对的是仓库根目录、某个子系统，还是两者。
• 将根目录的 ARCHITECTURE.md 视为系统地图，而非百科全书。
• 仅当某个子树有足够独立的结构、生命周期或约束，值得单独成文时，才添加嵌套的 ARCHITECTURE.md 文件。
• 添加嵌套文档时，更新父级文档，链接到该文档，并用一句话说明其范围。
• 决定拆分、合并、添加或删除架构文档时，先阅读 guides/document-topology.md，再更改文档结构。

2. 根据稳定的代码结构构建上下文。

• 阅读现有文档，仅用于了解边界、术语和决策历史。
• 检查入口点、包边界、长期存在的目录、接口、后台作业、存储边界和外部集成。
• 端到端跟踪一两个重要流程，确保文档反映系统的实际运作方式。
• 在起草正文前，梳理各部分的职责、交互和不变量。

3. 起草最精简且实用的文档。

• 说明系统或模块的用途、主要组成部分及其交互方式。
• 优先提供具体的文件和目录作为入手点，而不是详尽罗列所有内容。
• 仅在能缩短说明时使用简短的 ASCII 图示；不要使用 Mermaid。
• 选择适合系统的章节名称，不要强行套用固定模板。
• 起草新文档、重组章节，或决定如何呈现组件、运行时流程、代码路径或不变量时，先阅读 guides/section-patterns.md，再开始起草。

4. 保持文档高层次且经久耐用。

• 不要逐个罗列类或函数。
• 不要包含设置步骤、编码规范、操作手册和教程，除非设计约束依赖于这些内容。
• 对于决策依据和权衡历史，链接到 ADR，而不是在文档中嵌入冗长的决策记录。
• 如果某个领域尚不明确，就少写一些，并指出最适合入手的文件，而不要猜测。

5. 检查文档是否对贡献者有用。

• 确保新工程师能够回答：主要组成部分有哪些、应该从哪里开始追踪行为，以及哪些内容绝不能破坏？
• 删除普通重构后就可能过时的陈述。
• 更新现有文档时，逐条核对所有保留的陈述是否符合当前代码；不再成立的内容要修正或删除。
• 验证链接、文件路径以及父子架构文档之间的引用。
• 保留仓库术语，让读者无需翻译就能从文档定位到代码。

写作规则

• 优先使用简短段落和平铺列表。
• 由外向内撰写：先说明系统结构，再介绍最重要的流程和文件。
• 明确指出 start here 文件。
• 将不变量表述为可执行的规则，而非含糊的价值观。
• 如果存在模块文档，说明它在父级架构中的位置，并提供向上的链接。
• 缺少 ADR 是值得简要说明的事实，不是编造决策依据的理由。
• 使用便于搜索的标题和具体路径，避免叙述性填充。