架构与系统设计 / 系统课时

搭好架构设计工作台

搭好架构设计工作台

架构信息如果散落在聊天记录、白板和个人文档里,几周后就很难判断“当前系统长什么样、为什么这样设计、还有哪些风险”。本篇搭建一个最小工作台,把系统图、决策记录、风险清单和评审资料放到可持续维护的结构中。

学习目标

  • 建立包含系统图、决策记录、风险清单和评审资料的最小目录
  • 明确四类架构工件分别解决什么问题,以及它们之间如何互相引用
  • 用固定维护节奏保证架构资料可查、可审、可追踪

先建立最小目录

工作台不需要一开始就引入复杂平台。对大多数团队,一个与代码仓库同版本管理的 architecture/ 目录就足够起步。下面的命令创建四类核心工件的位置。

bash
cd "<PATH>/project"
mkdir -p architecture/{system,decisions,risks,reviews}
touch architecture/system/context.md
touch architecture/decisions/0001-template.md
touch architecture/risks/register.md
touch architecture/reviews/checklist.md
find architecture -maxdepth 2 -type f | sort

预期输出

text
architecture/decisions/0001-template.md
architecture/reviews/checklist.md
architecture/risks/register.md
architecture/system/context.md

<PATH> 替换为本机项目所在目录,实际绝对路径可能不同。这个目录结构的价值不在于名字本身,而在于把“系统现状、关键决定、未解决风险、评审证据”分开管理,避免一份大文档不断膨胀后无人维护。

四类工件各自回答一个问题

system/ 回答“系统现在是什么样”,适合保存系统上下文图、容器或服务关系、关键数据流和外部依赖。它描述当前事实,不负责记录所有历史讨论。

decisions/ 回答“为什么这样设计”。每个重要选择单独保存一条决策记录,最少包含背景、约束、候选方案、最终选择、后果和重新评估条件。这样未来看到一个看似奇怪的结构时,不必依赖原参与者口述。

risks/ 回答“我们现在最担心什么”。风险项至少记录影响、发生可能性、触发信号、缓解措施和负责人。尚未验证的关键假设也应进入这里,而不是藏在设计说明里。

reviews/ 回答“这次评审看过什么、结论是什么”。评审清单、会议材料、容量验证结果、安全检查和遗留行动项都放在这里,让一次架构评审能留下可复核证据。

架构设计工作台的四类工件与维护关系

给文件设定最低内容标准

工作台能长期运行的关键,是每类文件都保持“够用但不过度”。系统图只保留当前结构和必要说明;决策记录一条文件只处理一个重要选择;风险清单聚焦尚未关闭的问题;评审材料只保存能支持结论的证据和行动项。

可以用下面的最小字段作为团队约定:

工件 最少要有的内容 更新触发
系统图 边界、主要组件、外部依赖、关键数据流 结构或依赖发生变化
决策记录 背景、约束、候选、决定、后果 形成或替换重要选择
风险清单 风险、影响、信号、缓解、负责人 新风险出现或状态变化
评审资料 范围、证据、结论、行动项 每次正式评审

把维护动作嵌入日常流程

不要把架构资料维护成季度补作业。设计讨论形成长期约束时,当场新增或更新决策记录;系统边界、依赖或关键数据流变化时,与代码变更一起更新系统图;发现高影响假设时立即进入风险清单;正式评审结束后,把结论和行动项落到对应文件。

评审前只需要做一次简单检查:系统图是否反映当前结构,最近的重要决策是否有记录,最高风险是否有负责人和下一步,评审材料中的结论是否能指回证据。四项都能回答,工作台就已经具备可维护性和追踪性。

最小工作台的目标不是“文档齐全”,而是任何新加入的工程师都能在有限时间内回答四个问题:系统现在怎样、关键选择为何如此、主要风险在哪里、最近一次评审决定了什么。能稳定回答这四个问题,架构信息就真正成为团队资产。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

搭好架构设计工作台

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通