用于记录架构替代方案和决策的模板

Question

我们正在建立一个必须记录所有架构变更的流程。

是否有任何标准模板可用于记录替代方案和决策？

Answer 1

取决于您想要的详细/正式程度。就决策注册而言，我们通常每个区域/决定使用一个文档，尽管最近我们一直在试验OneNote。

至少你想要记录（对于每个选项）：

• 选项说明
• 优点和缺点
• 风险和问题
• 假设和约束
• 注意事项

简明扼要的专业清单缺点（等）通常就足够了 - 它不需要是一个大文档。

对于更深入/正式/复杂的场景，您希望更进一步，这是我们在这种情况下使用的格式：

<强>摘要

• 问题定义
• 解决方案背景
• 假设
• 约束

评估标准

（这很重要，因为它列出了您用于评分可用选项的标准，包括权重等。）

建议摘要

• 摘要
• 高级别比较表（这对于不想阅读长文档的人提供“一目了然”比较是有益的;并且无论如何进行并排比较是一个好主意）。

[选项1 ... N]

• 选项说明
• 优点和缺点
• 风险和问题
• 假设和约束
• 注意事项

<强>建议

Answer 2

github:npryce/adr-tools使用此simple template

• 标题
• • 日期
• 状态
• 上下文
• 决策
• 后果

Answer 3

这取决于您是否使用特定的体系结构框架 - 其中大多数都带有某种模板。如果你不使用任何，我会推荐SPAMMED Architecture Framework - 它非常轻巧。即使您不会发现此框架可用，您仍然可以从它提供的模板中受益。

Answer 4

在我的公司，我们发现使用以下格式对我们很有用：

• 背景（我们看到的问题是什么促使此决定或变更）
• 决定（我们实际做的改变是什么）
• 后果（由于此更改，更容易或更难做到的事情）

它类似于我们构建测试的方式：

给出一个场景，当我做X时，我希望Y是结果，

所以我认为这使我们写作和阅读更自然。 YMMV。

Michael Nygard的博客文章做了类似的事情：http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

Answer 5

我们在https://adr.github.io/收集有关架构决策记录的信息。

MADR - 降价架构决策记录

MADR为架构决策建立了一种简单的降价格式。

模板内容如下：

# [short title of solved problem and solution]

User Story: [ticket/issue-number] <!-- optional -->

[context and problem statement]
[decision drivers | forces | facing] <!-- optional -->

## Considered Options

* [option 1]
* [option 2]
* [option 3]
* ... <!-- numbers of options can vary -->

## Decision Outcome

Chosen option: [option 1], because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | ... | comes out best (see below)].

Positive Consequences: <!-- optional -->
  - [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...]
  - ...

Negative consequences: <!-- optional -->
  - [e.g., compromising quality attribute, follow-up decisions required, ...]
  - ...

## Pros and Cons of the Options <!-- optional -->

### [option 1]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* ... <!-- numbers of pros and cons can vary -->

### [option 2]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* ... <!-- numbers of pros and cons can vary -->

### [option 3]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* ... <!-- numbers of pros and cons can vary -->

该模板位于https://github.com/adr/madr/blob/master/docs/adr/template.md。

可持续建筑决策

博文Sustainable Architectural Design Decisions建议使用以下文字：

  

在<use case/user story u>的上下文中，面对<concern c>，我们决定<option o>实现<quality q>，接受<downside d>。

在某些项目中，我们使用以下扩展名：

  

在<use case/user story u>的背景下，   面对<concern c>   我们决定<option o>   并忽略了<other options>，   实现<system qualities/desired consequences>，   接受<downside d/undesired consequences>，   因为<additional rationale>。

其他解决方案

https://adr.github.io/列出了其他解决方案，包括降价模板。

Answer 6

即使有思维导图，我也会很高兴，并在必要时附上详细的文件。