ADR (architecture decision records)
議論を記錄する
仕樣書ではない
仕樣書よりは書き易く
當時に何を考慮したか記錄が殘る
An Architectural Decision (AD) is a justified software design choice addressing a functional or non-functional requirement that is architecturally significant. アーキテクチャ上の決定とは、アーキテクチャとして重要な機能要件や非機能要件について、ソフトウェアを設計する上でなされた選擇です。
An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. アーキテクチャとして重要な要件とは、ソフトウェアやハードウェアのシステムに對して、アーキテクチャや品質に測定可能な影響を與へるものを言ひます。
MADR (Markdown ADR) template
https://gyazo.com/7aca146674f38e0bc97f9b7cda351330
MADR light
https://gyazo.com/0ffda271cdc2c9328b3a380da096e9ae
title
問題の本質 + 選擇された解決策
metadata
status
proposed | rejected | accepted | deprecated | … | superseded by
date
最終更新日
deciders
決定者
consulted
相談を受けた人
informed
context and problem statement
狀況と問題
決定によって解決する問題
決定に關係する現狀
decision drivers
要求
選擇肢を制約する要求
considered options
選擇肢
title 狀のものを列擧するに留める
詳細は "chosen option" と "pros and cons of the option" で書く
chosen option
決定
decision outcome (with justification)
理由
consequences (good, bad)
狀況と問題がどう變はるか
validation (review, test)
どうやって決定を遂行するか
どうやって決定の遂行を保證するか
pros and cons of the option
利點と缺點
代替案との比較
more information
Y-statement
短
In the context of <use case/user story>, facing <concern> we decided for <option> to achieve <quality>, accepting <downside>.
〈use case/user story〉の狀況では、〈懸念〉に直面して、〈品質〉を達成するために〈選擇肢〉を決定し、〈惡い側面〉を受け入れました。
長
In the context of <use case/user story>, facing <concern>, we decided for <option> and neglected <other options>, to achieve <system qualities/desired consequences>, accepting <downside/undesired consequences>, because <additional rationale>.
〈se case/user story〉の狀況では、〈懸念〉に直面して、〈system の品質/望ましい結果〉を達成するため〈選擇肢〉を決定し、〈他の選擇肢〉を顧みない事とし、〈惡い側面/望ましくない結果〉を受け入れました。なぜなら〈追加の理論的根據〉だからです。
user story は
〈主體〉として〈よき事〉を達成したい、それは〈理由〉だからだ
Title
Context
Decision
Status
proposed | accepted | deprecated (superseded)
Consequences
良い結果、惡い結果、中立的な結果等、決定した事を行った時の全ての結果
ISO/IEC 42010:2011 Systems and software engineering - Architecture description
長え
anti-pattern
閒違った選擇をすることを恐れて、何も決定しない
正當な理由もなく決定が下され、team member はなぜその決定が下されたのか理解できないその結果、同じ topic が何度も議論される
決定が architecture 決定 repository に保管されないため、team member は決定が行われたことを忘れ、またそもそも知らない
business outcomes
現在および將來の team member を調整できる
project や製品の戰略的方向性を設定できる
architecture 上の決定を適切に文書化して傳達する過程を定義することで、意思決定の anti-pattern を囘避できる
ADR の內容
依存關係 (component の協働）
interface (API および公開された契約)
開發に使ふ技術 (library、framework、tool、process)
過程
ADR を作成する過程
https://gyazo.com/e5f793085d25e3bd8d553480fe86ef11
code:mmd
flowchart TD
accepted? -->|no| rejected?{"ADRはteamから否決されたか?"}
code の變更を檢證し ADR を適用する過程
https://gyazo.com/6d5e5d284c1a319b01cbfb05276b2e12
code:mmd
flowchart TD
承認あるいは否決した ADR は變更しない。architecture を變へるに際して新しい ADR を作り、古い ADR を「破棄濟み」狀態にする
よい行ひ
ownership を促進する
ADR の履歷を保存する
定期的な review 會の豫定を確保する
特に architecture が安定する迄は、豫め時閒を確保しておくとよい
ADR は一箇所 (Git repository や Wiki 等の) に保管する
準據してゐない code を處置する
adr-tools
CALM (冷靜さ)
Collaborative content creation is enabled. 協働
Accountability is supported. 責任
Learning opportunities are provided, both for newcomers and for the experienced. 學習の機會
Management likes them too because it is used to making and executing decisions. 經營
Good
Select by priority and significance. 優先度と重要度で選ぶ
Do not defer making and capturing high-impact decisions for too long (in the name of flexibility). 柔軟性の名の下に、影響力の大きい事項を把握し決斷を下す事を餘りに長く先延ばしてはならない。
prioritize meta-qualities such as observability and ability to react. 可觀測性 (o11y)や反應能力などの meta 品質を優先する。 Root and justify decision in actual requirements and personal experience. 實際の要件や個人的な經驗に根差し、決定を正當化する。
Split decisions into stages if no simple answer exist. 單純な答へが無い場合は、決定を段階に分ける。
Disclose your confidence level. 自信の度合ひを開示する。
Bad
subjectivity creeping in 忍び寄る主觀
Fairy Tale (a.k.a. Wishful Thinking) 御伽話 (別名 : 希望的觀測）
Sales Pitch 賣り込み
Free Lunch Coupon (a.k.a. Candy Bar) 晝⻝無料券 (別名 : キャンディーバー)
Dummy Alternative 僞物の代替品
the time dimension of architecting アーキテクトの時間次元
Sprint (a.k.a. Rush) スプリント (別名 : ラッシュ)
Tunnel Vision トンネル・ビジョン
Maze 迷路
record size and content nature 記錄 size と內容の性質
Blueprint or Policy in Disguise 設計圖または僞裝 policy
Mega-ADR メガADR
Novel and epic 斬新かつ壯大
Magic Tricks ("AD wizardry") 魔法の trick (AD ウィザードリー)
Non-existing or misleading context information to create a false sense of urgency. 虛僞の危機感を煽るための、存在しない、または誤解を招く狀況情報
Problem-solution mismatch 問題と解決策の齟齬
Pseudo-accuracy 擬似的な正確さ
批判。批評
Good
scope
Deliver what is asked for. 求められたものを提供する
Prioritize comments by urgency and importance 緊急度と重要度によって comment に優先順位をつける
Document the scope and the goals of the review レビューの範圍と目標を文書化する
content
Justify comments and calls to actions by referencing desired qualities 望ましい資質を參照することで、コメントや行動喚起を正當化する
Acknowledge context and requirements 狀況と要件を認識する
Be concrete and factual in option judgments 選擇肢の判斷は具體的かつ事實に基づいて行ふ
commenting style
Comment in a problem- and solution-oriented way. 問題や解決策を見据えたコメントをする
Report your perception/impressions, but do not interpret or guess. 自分の認識・印象を報吿するが、解釋や推測はしない
Criticize as strongly as needed, but also be motivating. 必要なだけ強く批判するが、やる氣を起こさせる
Be fair and polite. 公正かつ丁寧に
actionability
Make the feedback resolvable 解決可能なフィードバックにする
Offer help with comment resolution. コメント解決の手助けをする
Review the review comments レビューコメントを見直す
Bad
Pass Through パススルー
Copy Edit コピー編輯
Siding, Dead End (aka Excursion) サイディング、デッドエンド (別名 : エクスカージョン)
Self Promotion, Conflict of Interest 自己宣傳、利益相反
Power Game パワーゲーム
Offended Reaction 不快な反應
Groundhog Day グラウンドホッグ・デイ