面向规范开发

qrlib 默认采用“规范 -> 设计 -> 实现 -> 验证”的工作流。

核心原则

先写规范

在写代码前，先明确：

• 这次改动到底要解决什么
• 哪些问题不在本次范围内
• 公开契约是什么
• 如何判断改动完成

这些内容写进 docs/developer/specs/<slug>.md。

再写设计

规范解决“做什么”，设计解决“怎么做”。 设计文档写进 docs/developer/design/<slug>.md，重点说明：

• 模块拆分
• 文件落点
• 关键数据流或调用流
• 备选方案与取舍
• 风险与验证计划

最后才实现

代码、测试和公开文档都应以规范与设计为准，而不是反过来让文档追着代码补写。

什么改动需要完整规范

以下情况默认需要：

• 新增公开能力
• 修改公开 API 或行为语义
• 调整目录结构、构建流程或文档结构
• 重要重构
• 任何你希望下一次 Codex 能准确续写的改动

对外文档为什么隐藏 developer

公开文档面向用户，应该优先展示：

• 快速开始
• 教程
• API
• 概念说明

维护者规范与设计仍然会被构建进站点，但默认不放进公开导航栏，避免把实现细节与用户说明混在一起。

如果你需要直接打开它们：

• 本地构建后打开仓库根目录的 open-docs.html
• 或直接访问 /developer/specs/ 与 /developer/design/