組織が記憶喪失になるのをどうすれば～ ryuzee技術顧問にきいてみた

何か決定した事実は実装や規則の形で残っているものの、決定までの経緯をチームメンバーが覚えていない――。この記事では、そうした組織が記憶喪失になることにどう対処していけばよいか、NTT Comの技術顧問である吉羽龍太郎 (@ryuzee) さんにふらっと相談してみたら一瞬で突破口が見つかった＆話に奥行きが出た話を共有します。

軽く自己紹介

イノベーションセンターの小林 (@ppyv) です。開発・検証用PCの開発に一段落つけた後、社会人学生としてたっぷり2年間学習を積んでいました。いまはイノベーションセンターで働く社員のみなさんに、よりよく働ける環境を提供するための仕事をしています。

事の発端

最近、同じチームで働いているmahitoからこんな質問がありました。

なんでこのアプリケーションは社内プラットフォームとしてモバイル対応していないんだっけ？

他の組織から、してないならしてない理由があるんですよねって言われたので

その理由はSlackの過去ログを遡って確認できたものの、こうしたちょっとした経緯を調べることに対して30分以上にわたる議論が巻き起こってしまいました。正直言ってもったいない時間ですし、調べがつくうちはまだいいもののどこを調べたらいいか分からないとか、そもそも間違った経緯が「発見」される恐れもあります。

ではどうやってその経緯を記録しておくのがいいのか、との積年の疑問がここで再度噴出したため、ryuzeeさんに相談しに行くことにしました。

ryuzeeさんの油セール

NTT Comの技術顧問でありアジャイルコーチでもあるryuzeeさんは、毎週火曜日をNTT Com向けの支援日として空けてくださっています。

特に社員からのアポイントメントがなければ、「油セール」と称してNTT ComのオンラインコミュニケーションツールであるNeWorkにおいでくださいます。

実際に聞いてみた

その機会を使ってさっそく質問してみることにしました。

新たなる概念：ADR

小林）……とこういうエピソードがあって、自分は「組織が記憶喪失になる」と呼んでいるんですが、ほかではどうなんでしょうかね。

ryuzee) それはめっちゃあるあるですね。どこ行っても悩んでいると思います。ただこの問題に対しては、ソフトウェア開発で使われているADR: Architectural Decision Recordsっていう手法が役に立つと思います。

ジャブを打ったらいきなりストレート＝新しいキーワードが飛んできました。ここでADRについて、GitHubのorganization "ADR" がメンテナンスしているサイト adr.github.io から語釈を引きます。

An Architectural Decision (AD) is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on a software system’s architecture and quality. An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitute its decision log. All these are within the topic of Architectural Knowledge Management (AKM), but ADR usage can be extended to design and other decisions (“any decision record”).

（拙訳）アーキテクチャ上の決定 (AD) とは、アーキテクチャ的に重要な機能要件または非機能要件に対処する、合理的なソフトウェア設計上の選択のことです。アーキテクチャ的に重要な要件 (ASR) とは、ソフトウェアシステムのアーキテクチャと質に大きな影響を与える要件のことです。アーキテクチャ決定記録 (ADR) は、単一のADとその理論的根拠を記録するためのものです。プロジェクトで作成・維持されるADRの集合は、意思決定のログを構成します。これらはすべてアーキテクチャナレッジマネジメント (AKM) に含まれる話題ですが、ADRはany decision recordすなわちあらゆる決定の記録として、設計やそのほかの決定にも応用できます。

平たく言ってしまえば、アーキテクチャ上重要な決定そのものと、どういう理由があってその決定をしたのかをまとめた記録がADRということになります。悩みに対するずばりの回答が10秒で返ってきて面食らいました。

ADRの実践：その1 何を書くか

そしてADRの簡単な説明を受けて、思い出したのがこの話でした。

小林）これってコードコメントとかコミットログにはWhyを書けっていうのと同じですか？

ryuzee) あーまさにそうです。HOWはコード見れば分かるので、なんでそれを書いたの？というのを残しておく必要がありますね。

ソフトウェアエンジニアの方は、コードコメントの書き方について指導を受けたことはありませんか？

やってしまいがちなコードコメントとして何が起きているかを書くというのがありますが、何が起きるかはコードを読めば理解できるので、一般にはコメントとして適当でないとされます。代わりに、なぜそのコードにしたのかであるとか、一見して意味・目的がわかりにくいロジックを解説するコメントを書くべきと言われます。それとこの話は似た構造をしています。

ADRの実践：その2 どこに書くか

次に、ADRを書くにしてもどこに書いておくべきかの話になりました。

ryuzee) ソフトウェア開発に関係していれば、GitHubでいうところのpull request (PR) にWhyを書くのは合理的です。あとはWebサービス系の会社が規程とかの管理をGitHubで行っている例がありますが、親和性が高いやり方だと思います。その変更をするに至った背景、なぜ必要と思った、などなど書くべきとされることは会社によってさまざま考えられますが、そういったことをPRに書いておく。そしてADRのテンプレートを作ってしまえばある程度定型にできるので、ADRテンプレートを満たしていないPRは突っ返すといった対応も容易です。

小林）確かにバージョン管理システムを使えば、変化したところを起点にどのコミットで編集されたかは即座に分かりますね。ではソフトウェアや、プレーンテキストでなんとかできるものに関連しない分野だとどうしましょう？

ryuzee) 身も蓋もないですが、やっぱりどこかにまとめて書き残しておくしかないです。

ADRを書く先としては、簡単に書けることと簡単に検索できること、この2点を満たすことがとても重要です。これらのいずれかが欠けるとうまく行きません。書いてなければ探せないですし、探せなければ書いていないのと同じなので、結果として問題を蒸し返したり、過去の経験をリスペクトしない決定をしてしまったりする。適切なところはプロジェクトによってさまざまだと思いますので、まずチームでやり方を合意してやってみるのがいいと思います。

アンチパターンとして、例えばこれをWordファイルでやってしまうと書き始めるまでのハードルが高いですし、書いたファイルが散逸しやすい問題があります。そういった点は注意した方がいいですね。

それからADRが書きつけてあるファイルの保存先が複数箇所になると、これもうまくいきません。結局検索性がないのと同じになってしまいます。 2カ所以上を探すのは大変です。

その点やはりPRは合理的だと思います。自動的に一カ所に固まりますから。記憶喪失にもバージョン管理システムの力を借りるのがいいのではないかと思います。

Slackの「地層」を探しに行って考古学者になったり、あっちもこっちもと掘り返したりしていると骨が折れます。「ここを見ればわかる」状態にしておくのが大事だと感じました。

ADRの実践：その3 どう書くか

ではどうやってADRを書き始めるか、その点も尋ねてみました。

小林）ではどうやってADRを書き始めたらいいでしょうか。

ryuzee) 例えば今日のこの相談をADRに起こすことを考えるとしましょう。それなら、「なぜこの話をここに持ち込もうとしたか」をアウトプットするのが重要になります。

小林）確かに今日ここまで会話した内容はすべてHowの話で、Whyの話ではないですね。なぜと言われると、「なんとなくryuzeeさんならなんか知ってそうだったから」となってしまいますが（笑

ryuzee) よく「Issueから始めろ、Howから始めるな」といいます。実はHowに詳しい人っていっぱいいるんですよ。だけど、その人が直面しているIssueに詳しい人って、そんなにたくさんはいません。なんならその人が一番詳しいかもしれない。

なんらかまず書いてみるのをおすすめします。試してみて振り返って、それでいける or いけないを見るのは王道パターンですよね。

最後の話は目からうろこでした。問題解決なのだからHowを考えるのは当たり前だと思っていましたが、確かにIssueがあるからHowを考えているわけです。今回で言えば、組織が記憶喪失になってしまうことがIssueなわけで、それに対する一つのHowがADRだといえます。

相談を受けて試しに書いてみたADR

アドバイスを受けて、さっそくこの相談をADRにしてみることにしました。例えば次のようになるでしょう。

タイトル： エンジニアリング組織を運営するための知恵が必要な際の問い合わせ先
背景： 次の通り
- 「何か決定した事実」は残るが「なぜそう決定したか」の記録が損なわれる事象が連続して発生し、これを仕組みで防止するための手段が何かあるのではと考えた
- こういった話はryuzeeさんが最も詳しいと思われた（開発組織を動かすプロセスに関するスライドや、発表を見聞きしていたため）
- 油セールがあるために、ふらっと会話しやすいと思われた
- もし人違いなら他の人に転送してくれるだろうと思われた
- 当初課題への対策としてADRを提示してもらえた
決定： まずryuzeeさんに相談し、なんらか回答いただくか、適切な転送先を指南してもらう
状態： 運用中。ryuzeeさんへの相談がしづらい状況（一例として、油セールの中止、技術顧問からの引退）になった際は更新を要する。

これは非常にシンプルな例ですが、もっと込み入った内容を記録しておくことももちろんできます。こちらのリポジトリでADRのテンプレートがいくつか紹介されており、ほかにどんな項目を書いておくべきか参考になります。

例えば自らのプロジェクトに適用するADRテンプレートをこれらを参考に作ったとして、その制作経緯・過程をADRとして記録しておくのもよさそうです。

まとめ

同僚のmahitoは、千葉市動物公園に長いこと肉食獣が存在しなかったことに実は理由がなかったことを引き合いに、今回の話を関連付けて次のように述べています。

定期的に見直す話

なぜこうなってるかが残されておらず、現状から誤った類推がされてきたが、調べると理由などなかったと。

組織にもこういう事が多くあり、どうすればという話を @ryuzee さんに先日したら、Architectural Decision Records という話を教えてもらった。https://t.co/6qMtNRQOBC https://t.co/mUHQKD8pKf
— Mahito / まひと (@Mahito) 2024年2月1日