System design docs

System design docs 指仓库把系统级设计文档本身当成长期真相源，而不是把关键决策散落在 PR 讨论、Issue 评论或脑内记忆里。这里的“系统设计”不只指架构图，也包括硬件行为文档、质量门禁、控制面边界、设计取舍和后续实现必须服从的 current truth（projects/mains-aegis.md、projects/style-playbook-skills.md）。

它和普通 README、API reference 或产品文案不同。命中这个 Topic 的仓库里，文档不是附属品，而是 firmware、服务、Web UI 或生成链路要主动回读和对齐的主契约。

当仓库的关键设计决定被正式写进 docs/、spec、ADR、quality-gate 文档或知识库 contract 中，而且后续改动必须先校对这些文档再落代码时使用。凡是改动会影响系统边界、设备行为、控制面职责、知识库真相源或设计门禁，都应命中本 Topic。

如果文档只是一些零散笔记、临时迁移记录，或仓库主要靠代码自解释，不应提升到这里。System design docs 只适用于那些“文档本身就是系统的一部分”的项目。

• 文档应按系统边界组织，而不是按作者思路堆积。像 projects/mains-aegis.md 那样把 BMS、charger、UPS output、quality gates 分开写，后续才能知道某个固件或 UI 变更应回读哪一份设计真相。
• 代码实现和文档真相要形成单向约束：先有明确文档边界，再让 firmware、Web、脚本或生成器去对齐；若实现已经改了但文档还停在旧世界，Topic 回答里必须把这种漂移当成风险而不是默认忽略。
• 当文档直接驱动生成链路或知识库消费面时，解析器、audit 和导出数据都要算进验证范围。projects/style-playbook-skills.md 说明了这种情况：Markdown 不是静态说明，而会被 read-model、group Skill 和网站直接消费。
• 质量门禁和设计文档应互相引用，而不是各自孤立。若 docs/quality-gates.md 或 spec 里定义了某条限制，CI、生成器或 review policy 最好能找到对应实现入口，否则文档会很快失信。
• 对这类仓库，文档改动本身就是产品/系统改动。审查时不能因为“只改 docs”就放松要求，尤其是当文档会改变人类理解、自动生成或硬件行为判断时。

• projects/mains-aegis.md：代表“文档先行的设备系统”形态。这里的设计文档直接决定硬件行为、只读运维控制台边界和质量门禁，最能说明为什么 docs 本身就是系统真相的一部分。
• projects/style-playbook-skills.md：代表“知识库/生成链路把 Markdown 当输入”的形态。它说明系统设计文档不一定只服务硬件或架构图，也可以直接驱动 read-model、topic taxonomy 和 Agent 分发面。
• skills/style-system-design-docs/SKILL.md：group Skill 让后续 Agent 回到 docs contract、read-model 和 current truth，而不是把本 Topic 误解成“仓库文档很多”。

• 把任何“文档比较多”的仓库都算进来，会稀释掉这个 Topic 真正的约束力。关键在于文档是否定义系统，而不是文件数量。
• 代码和文档发生分叉时默认“以后再补”，会让 current truth 消失，最终谁也不知道该信实现还是信文档。
• 只改文档不跑门禁，尤其在 Markdown 会被 read-model、catalog.py audit --fail 或网站消费的仓库里，很容易造成机器解析与人工理解同时漂移。
• 把 spec、ADR、质量门禁和产品文档分开维护却没有互相链接，后续维护者会不断在不同文档里重复决策甚至互相矛盾。

• projects/mains-aegis.md
• projects/style-playbook-skills.md
• skills/style-system-design-docs/SKILL.md
• skills/style-playbook/references/data/topics/system-design-docs.json