保存代码没有保存全部设计

上一讲我们决定了预约的数据模型、返回结果和规则位置。回到重叠检查,代码能说明检查放在哪里,却不能说明为什么没有使用数据库约束,也没有保存当时对并发风险的判断。会话结束以后,下一位维护者应该去哪里寻找这些理由?

设计文档的读者包括未来的自己、接手项目的同事和新启动的 Agent。仓库入口文档说明主要部分、职责以及构建与测试方法;重要决策则需要留下能够独立阅读的理由。

课程先回顾了作业一:隐藏 API 检查通过,不代表真人通过客户端操作也正常;事后让 Agent 用学生口吻补写计划,同样不能证明计划曾约束开发。从作业二开始,计划和过程记录要求随工作提交。这与设计文档的目的相同:保留当时的依据,而不是只为最终产物补一段解释。

赞助商

用 ADR 保存选择与代价

架构决策记录(Architecture Decision Record,ADR)围绕一项决策记录背景、选择、备选方案和后果。重点是为什么需要选择,以及放弃了什么。

课件示例选择在 BookingService.book() 中检查重叠,收益是规则集中、易于测试并且不依赖特定数据库;代价是两个并发请求仍可能竞争。记录下这个限制,后续讨论并发时就知道需要重新检查哪项假设。

另一个 SQLite 示例暴露了薄弱记录的问题:背景只介绍技术,没有说明规模和写入需求;备选方案只有不满足持久化要求的内存存储;后果又略过了部署和写入方面的约束。记录看起来完整,仍然可能没有解释真正的取舍。

存储决策示例需要继续审查背景、备选方案与后果

已经接受的记录不应被重写。决策变化时新增 ADR,并标记替代关系,保留从内存到 SQLite、再到其他存储方案的路径。接口抽象和具体引擎也可能有不同寿命,适合分别记录。

不是所有细节都要建立文件。难以逆转、跨模块、令人意外或经过争论的选择,通常更值得保存。设计文档、RFC 或充分的 PR 说明,也能承担相同功能。

一个简洁的 ADR 可以按课件示例写成下面这样,内容需由真实决策填写:

1
2
3
4
5
6
ADR 007:在领域服务中检查重复预约
状态:Accepted
背景:同一会议室的预约不得重叠,需要确定约束位置。
决定:BookingService.book() 在插入前检查已有区间。
备选:数据库排斥约束;当前阶段未选择,理由是存储可替换性。
后果:规则集中且便于测试,但并发检查与插入仍可能竞争。

读完这份记录,维护者应该知道什么时候需要重开讨论。出现多个并发写入者时,最后一项限制就不再是遥远的可能性。若改用数据库约束,应新增记录并把旧记录标为被替代,保留原来的背景。

作业二要求四类起始记录:数据模型及图示、能力设计、存储与技术栈。后续作业引用并确认或替代已有选择,使决策日志随同一个系统持续演进。ADR 只是其中一种格式,真正要保存的是能够独立理解的推理。

根据问题选择图示

数据模型图帮助理解实体关系,系统时序图把系统当作黑盒,展示用户请求与响应。课件先画第一次预约成功、第二次同房间同区间被拒绝的过程,每一行都能转成外部行为测试。

对象交互图再展开 BookingService、会议室与存储,检查谁调用谁、先后顺序是否符合规则。例如重叠查询必须在插入之前;如果存在重叠,也需要画出拒绝路径。架构草图则放大到子系统与依赖,回答哪些部分彼此连接。

数据流图还加入时序图不一定体现的存储。课件用实体、处理过程、数据存储与具名箭头,追踪请求如何经过校验、重叠检查和保存。数据跨入受信任区域的位置,也是后面安全分析要检查的边界。

预约数据经过验证、规则检查与存储,并跨越信任边界

这些图各自回答不同问题,不必一次引入完整 UML 符号。我们可以先用临时草图推理,确认需要长期保留的部分,再用 Mermaid 等文本形式放进仓库,与实现一起评审和更新。

对照契约检查候补晋升

课件给出六条契约:确认前不得重叠,冲突请求按到达顺序排队,取消后晋升最早且可用的请求,写入必须晚于检查,回复反映真实存储状态,并由 API 经服务访问存储。接着沿取消轨迹逐步对照:

取消预约与候补晋升的交互需要对照契约检查

图中的 API 直接删除预约,绕过了服务;晋升使用最新请求,没有遵循先到先得;插入又发生在重叠检查之前,客户端甚至在检查前就收到确认。若检查发现冲突,请求怎样返回队列,图中也没有交代。这样读图,就能把顺序与责任问题对应到具体契约,而不只是判断画得是否整齐。

文档同时也是 Agent 的输入

ARCHITECTURE.md 提供整体地图,决策记录解释历史选择,AGENTS.md 或同类文件保存约定、边界、不变量和运行命令。每次会话读取这些材料,就能少依赖一次口头交接。

Skill 则保存按需加载的流程。课件区分常驻指令和任务触发的技能,也提醒流程本身会消耗上下文。是否需要完整的设计访谈、测试与评审流程,应由任务的复杂度决定,不能把所有步骤固定套在所有改动上。

规则文件描述约定;必须始终成立的部分,还应转成测试、Hook 或权限控制。文档也应靠近代码,在同一次修改中更新;过时记录可能让人和 Agent 都作出错误判断。

Skill 的渐进加载也影响上下文成本。启动时先提供名称与描述,匹配任务后再加载正文,需要时才读取关联脚本与材料。课件用 Superpowers 展示头脑风暴、计划、测试与评审如何组合成流程,又用 grill-me 展示通过连续追问暴露设计假设。这里需要判断当前任务到底需要多少流程,避免每个小修改都带入整套设计访谈。

文档也有维护成本。代码已经表达的自增操作,不必再逐行翻译;令人意外的选择、被否决的直觉方案和跨模块约定,则应放在评审者找得到的位置。临时画图可以用于思考后丢弃,长期保存的图必须与实现一起更新。

模式提供共同语言

Strategy 表示通过统一接口替换算法,Observer 表示事件发生后通知订阅者,Adapter 负责接口适配,Factory 集中对象创建。名称能够简洁地传达角色和关系。

模式需要对应真实问题。发送一封确认邮件,未必需要策略、工厂、观察者和单例全部参与。共同词汇能够减少解释成本,也要求评审者指出什么时候不需要增加这些结构。

参考资料