見出し画像

なぜその選択をしたのか?コープさっぽろにADR(Architecture Decision Records)を導入した話

これはコープさっぽろアドベントカレンダー12/20記事です

こんにちは。こもりです。


気がついたら入協して1年が経ち、現在は組合員管理チームというCRMからポイントまで事業横断系システムを扱うチームリーダーをやっております。今のお仕事の話もしたいですが、それはまた今度。

さて、タイトルの件ですが「ADR」とは「Architecture Decision Records」の略称で「なぜその選択をしたのか?」の情報を選択時の状況を含めて記録するためのものです。

「Why」を残すって「Why」?

たとえ話です。大事な意思決定が過去に行われている。

それは自分の入社前だった。「なぜ」その意思決定が行われたか当事者や正確な情報は失われている。決定事項を記録した議事録はあったが、「なぜ」決定されたのかは記載されていない。

次の自分の仕事はその意思決定に沿って行ってくれと指示を受けている。「なぜ」沿う必要があるのかは誰も正しくわからない。

当時の意思決定は今の時代に合っていないかもしれない。でも「なぜ」当時そう決定したかはわからないので合っていないと言い切ることもできない。

このような状況を打開すべくアーキテクチャ(構造)上の変更をしていくものがADRだと思っています。

上のたとえ話だと少し曖昧かつ壮大に見えるため、自分ごとで有用性が見いだせず響きにくいかもしれません。

情シスで布教していくためにチャンクをあわせ、実際にコープさっぽろADRの入門書に記載た文章を転記します。

---

コープさっぽろADRの入門書の文章(一部)

コメントがなくtmpAのような不明瞭な変数名からなるソースコード、自動テストがないプログラムを思い浮かべて下さい。

短期的に見ればコストをかけず素早く作れていたと思います。

改修や再テストに関しても当事者の記憶が鮮明なうちは問題はなかったかもしれません。

しかし時が経ち、当時の開発者や有識者は既にいない現場を思い浮かべてください。

見返したときに誰がどんな思いで作ったかわからず触れるのに勇気がいる。もしくは怖くて触れられなく途方に暮れた経験はないでしょうか。

諦めて蓋をし、似ている別のコードを書き始めたことはないでしょうか。

現行を正しく理解できないため現新テストを諦めたことはないでしょうか。

ADRは意思決定における

  • 「なぜ作ったかがわかるコメント」

  • 「正しく伝わる変数の命名」

  • 「同じことを繰り返さないための自動テスト」

と思ってください。

そのためにコープさっぽろにADRが必要だと考えました。


公開します

なんとなく、「なるほど。ADRってよさそうだな!」って思って頂けたでしょうか?

本記事ではDXNoteらしくコープさっぽろのADRテンプレートを、100%公開しちゃい思います。

コープさっぽろでは記録ツールとしてGoogle Docsを採用しました。NotionやGitHubでMarkDown記法も検討しましたが、Google Workspaceにフルコミットしている弊組合では作成ハードルが一番低く、またアカウントを全員もっているか問題が起こらないため民主化されるスピードが一番早いのではと予測しGoogle Docsを選びました。布教されてきたら再検討の余地があると思っています。

運用方法については成熟したころに需要がありそうだったらまた今度。

これを見て皆様、各社様が「お、ADR使おうか」「もうコレ、まるパクりしちゃおうぜ」とか思って頂ければ幸いです。

では。

文:小森


コープさっぽろのADRテンプレート

コンテキスト

このセクションには技術的、政治的、社会的、プロジェクト固有のものを含む力学を記述します。 これらはおそらく緊張状態にあるでしょうし、そのように記述すべきです。このセクションを構成する文章は、中立でなくてはなりません。 事実だけを書き下すようにしてください。

決定(Decision)

このセクションにはこれらの力学への対応を書きます。能動的な調子で完全な文章で記述してください。「私たちは〜する」のように。

影響

決定がもたらした「プラス」の影響、「マイナス」の影響、「影響なし」問わず、すべての影響は、ここに記されます。

「プラス」と「マイナス」という観点から、ただ決定を説明するのではなく、"YではなくXをする必要がある。とするとよりよい「影響」になるでしょう。

関連ドキュメント

リンクなどがあれば載せます

決定プロセス(いつ、だれが、どうやって)

経緯を簡単簡潔に。みえる化されていることで疑問やトラブルを未然に防ぐでしょう。

破棄した理由

ADRが別のADRに置き換わるなど破棄が発生することもあるでしょう。「ADR XX に伴い」など、なぜ破棄したかわかるように。








この記事が参加している募集