✅
[ADR][GitHub] Any Decision RecordsをGitHub Discussionsで運用する際の日本語テンプレート

2024/10/05に公開
GitHub
 はじめに現在、数名のチームで CLIツールの開発プロジェクトを1から進めています。

その際に、詳細な形式の日本語版ADR[1] のGitHub Discussions作成フォームテンプレートができたので、誰かの参考になればという思いでこの記事を書きました。

 TL;DR作成したテンプレートは以下のリポジトリに配置しています。
https://github.com/masamallow/adr-form-template-jp

 前提ドキュメントやタスク管理など、なるべくGitHubだけで完結させるようにプロジェクトを進めています。
決定に至るまでの議論や結果の記録(ADR)は GitHub Discussions を用いるのが良いと考え、Discussions用のテンプレートを作成します。[2]
プロジェクトには、ゆくゆく新人・若手が入ってくることを考え、作成の元ネタの英語テンプレートは日本語に直し、そのほか後述の特徴を付け加えて加筆します。[3]
本記事では、ADRについてがっつり説明することは本筋ではないので、簡単に説明する程度とします。
次にプロジェクトで用いる ADR についての定義を説明します。

 作成するADRについて
 (おまけ) ADR (Architecture Decision Record) とは？簡単ですが、参考になりそうな記事から引用しておきます。
ADR プロセス - AWS 規範ガイダンス (2024/09/22時点) より
アーキテクチャ決定レコード (ADR) は、構築計画中のソフトウェアアーキテクチャの重要な側面に関してチームが取った選択について説明する文書のことです。

各 ADR には、アーキテクチャの決定、その背景、およびその結果が記載されています。
よくある質問 - AWS 規範ガイダンス (2024/09/22時点) より
ADR プロセスを作成するメリットは何ですか?

プロジェクトチームは ADR プロセスを作成して、アーキテクチャに関する意思決定を効率化し、同じアーキテクチャのトピックについての繰り返しの議論を回避し、アーキテクチャに関する決定を効果的に伝達すべきです。
その他、より詳しく知りたい場合はWeb検索だったり、Zennの記事(adrの記事一覧 | Zenn) だったり、ご自身で調べてみてください。

 Any Decision Recordアーキテクチャに限らず、特にプロジェクトの動き出しに決まった諸々のことは、まだ文書化が成熟していないことも多々あり、忘れられがちな印象があります。

"Architecture" に捉われずに大事な決定事項はとにかく理由とともに文書化しておきましょう、ということで "Any" Decision Record として、運用することにしました。
参考事例:

組織が記憶喪失になるのをどうすれば ～ ryuzee技術顧問にきいてみた - NTT Communications Engineers' Blog
まず、テンプレート全文と特徴をお伝えし、その後に導入手順について簡単に記載します。

 テンプレート全文リポジトリ内のファイル:

https://github.com/masamallow/adr-form-template-jp/blob/main/.github/DISCUSSION_TEMPLATE/adr-any-decision-record.yml
本記事内で確認したい場合、中身の閲覧はこちらをCLICKsample-repository/.github/DISCUSSION_TEMPLATE/adr-any-decision-record.yml
title: "(ADR Template)"
labels: [ "ADR-proposed" ]
body:
  - type: markdown
    attributes:
      value: |
        ### ADR (Any Decision Record) - 任意の決定記録 の入力フォーム
        #### ADRとは
        ADR（Any Decision Record）は、プロジェクトや組織内で行われる重要な意思決定を文書化したものです。  
        これには、意思決定の背景、検討された選択肢、最終的な決定、その決定がなされた理由、及び決定に伴う結果や影響が記録されます。  
        ADRは、プロジェクトの透明性を高め、未来の意思決定の参考になるような知識の蓄積を目的としています。

        (※元々は、アーキテクチャ上の意思決定を記録するためのもの(Architecture Decision Record)ですが、ここではあらゆるものの決定を記録するためのものとして転用します。)

        #### ADRを書く理由
        - 透明性の確保：
          - ADRを用いることで、意思決定過程が全チームメンバーにとって透明になります。これにより、意思決定に対する理解と信頼が深まります。
        - 学習と改善：
          - 過去の意思決定を記録しておくことで、何がうまく行ったのか、何がうまく行かなかったのかを振り返ることが可能です。この知見を基に、今後のプロジェクトでの意思決定プロセスを改善することができます。
        - 一貫性の維持：
          - ADRは同じ問題に対して繰り返し同じような議論を避け、一貫性のある意思決定を支援します。これにより、時間の節約と効率的なリソース利用が可能となります。
        - 将来の指針として：
          - 新しいチームメンバーや将来のプロジェクトで同様の問題が発生した場合、過去のADRを参照することで迅速かつ効果的な意思決定が行えます。

        #### 本テンプレートについて
        - ADR用のlabelの設定
          - 一覧
            - `ADR-proposed`: 提案中のADR
            - `ADR-accepted`: 承認済みのADR
            - `ADR-deprecated`: 非推奨のADR
            - `ADR-rejected`: 却下されたADR
            - `ADR-superseded`: 後続で更新済みのADR
          - ライフサイクル
            ```plaintext
            ADR-proposed -> ADR-accepted -> ADR-superseded
                         └> ADR-rejected └> ADR-deprecated
            ```
        - それ以外の項目はフォームの説明を参照のこと。
        - 参考元
          - [MADRのテンプレートファイル](https://github.com/adr/madr/blob/d376c6fdf553d8cc958fb4dd54fb226784711682/template/adr-template.md)
          - [About MADR (ドキュメント)](https://adr.github.io/madr/)

        #### 参考
        - [Architectural Decision Records - Homepage of the ADR GitHub organization](https://adr.github.io/)
        - [peter\-evans/lightweight\-architecture\-decision\-records: Lightweight Architecture Decision Records](https://github.com/peter-evans/lightweight-architecture-decision-records)
        - [LADR\-template/TEMPLATE\.md at master · moomoo\-ya/LADR\-template](https://github.com/moomoo-ya/LADR-template/blob/master/TEMPLATE.md)
  - type: textarea
    id: context-and-problem-statement
    attributes:
      label: Context and Problem Statement - コンテキストと問題の説明
      description: 決めるべき事項や変更の動機となっている問題はどのようなものか、コンテクストや説明を記述してください。例えば、自由形式で2〜3文を使用するか、イラストやストーリー形式で表現します。問題を質問形式で表現し、projectのitemやissue、PRへのリンクを追加してもよいです。
      value: |
        <!--
        決めるべき事項や変更の動機となっている問題はどのようなものか、コンテクストや説明を記述してください。
        例えば、自由形式で2〜3文を使用するか、イラストやストーリー形式で表現します。
        問題を質問形式で表現し、projectのitemやissue、PRへのリンクを追加してもよいです。

        例：
        See: #99

        上記issue進める上で...の解決のため、どのツールを使用すべきか決める必要がある。
        -->
    validations:
      required: true
  - type: input
    id: decision-date
    attributes:
      label: Decision Date - 決定日付
      description: 結論が出た日付を入力する項目です。yyyy/MM/dd or TBD (To Be Determined の意)
      placeholder: yyyy/MM/dd or TBD (To Be Determined の意)
      value: TBD
    validations:
      required: true
  - type: input
    id: decision-makers
    attributes:
      label: Decision Makers - 意思決定者
      description: 決定に関わる全員をメンションしてください。
      placeholder: "@user1 @user2 ..."
      value: <!-- 決定に関わる全員をメンションしてください。 例： @user1 @user2 ... -->
    validations:
      required: true
  - type: textarea
    id: decision-drivers
    attributes:
      label: Decision Drivers - 決定要因
      description: (簡易に記載する場合は省略可能) 決定に影響を与えた要因を記述してください。
      value: |
        ―

        <!--
        (簡易に記載する場合は省略可能)
        決定に影響を与えた要因を記述してください。

        例：
        - 直面する懸念事項
        - 対処すべき課題
        - ...
        -->
  - type: textarea
    id: considered-options
    attributes:
      label: Considered Options - 検討した選択肢
      description: (簡易に記載する場合は省略可能) 検討した選択肢のタイトルやリンクを箇条書きで記述してください。
      value: |
        ―

        <!--
        (簡易に記載する場合は省略可能)
        検討した選択肢のタイトルやリンクを箇条書きで記述してください。

        例：
        - 検討した選択肢1のタイトルやリンク
        - 検討した選択肢2のタイトルやリンク
        - ...
        -->
  - type: textarea
    id: decision
    attributes:
      label: Decision - 決定
      description: 決定事項、理由、補足を箇条書きでまとめてください。
      value: |
        #### 内容

        #### 理由

        <!--
        決定事項、理由、補足を箇条書きでまとめてください。
        決定内容や、選ばれた選択肢のタイトルやリンク

        例：
        #### 内容
        - 選ばれた選択肢のタイトルやリンク
          or
        - (具体的内容) ...を使用する。
        - ただし、...の場合は...を使用する。

        #### 理由
        - 決定要因を満たす唯一の選択肢であるため
        - 補足に記載されている結果を得られるため

        #### 補足
        - (任意)
        -->
    validations:
      required: true
  - type: textarea
    id: consequences
    attributes:
      label: Consequences - 結果
      description: (簡易に記載する場合は省略可能) この決定により、Goodな点、Badな点、何かしら影響がある点など、理由とともに記載してください。
      value: |
        ―

        <!--
        (簡易に記載する場合は省略可能)
        この決定により、Goodな点、Badな点、何かしら影響がある点など、理由とともに記載してください。

        例：
        - Good
          - 1つ以上の望ましい特性が改善される。なぜならば...
        - Bad
          - 1つ以上の望ましい特性が損なわれる。なぜならば...
        -->
  - type: textarea
    id: confirmation
    attributes:
      label: Confirmation - 確認
      description: (簡易に記載する場合は省略可能) ADRの実装/遵守がどのように確認されるかを記述してください。この要素は任意ですが、多くのADRに含まれています。
      value: |
        ―

        <!--
        (簡易に記載する場合は省略可能)
        ADRの実装/遵守がどのように確認されるかを記述してください。
        決定したことで、何を実施したか、何をする必要があるか、を記載してください。
        例として、決定された設計とその実装が決定に合致しているかについては、設計/コードレビューまたはArchUnitのようなライブラリを使用するテストがこれを検証するのに役立ちます。
        この要素は任意ですが、多くのADRに含まれています。

        例：
        - [x] ...ドキュメントに記載
          - link
        - [ ] 実装の修正
        -->
  - type: textarea
    id: pros-and-cons-of-the-options
    attributes:
      label: Pros and Cons of the Options - 選択肢の長所と短所
      description: (簡易に記載する場合は省略可能) 検討した選択肢の長所と短所を記述してください。
      value: |
        ―

        <!--
        (簡易に記載する場合は省略可能)
        検討した選択肢の長所と短所を記述してください。

        例：
        #### 選択肢1
        説明 と 参照リンク の記載

        - Good
          - ... なぜならば...
        - Neutral
          - ... なぜならば...
        - Bad
          - ... なぜならば...

        #### 選択肢2
        説明 と 参照リンク の記載

        - Bad
          - ... なぜならば...
        -->
  - type: textarea
    id: more-information
    attributes:
      label: More Information - 詳細情報
      description: (省略可能) 決定の結果に対する追加的な証拠/信頼性を提供するか、チームの決定に対する同意を文書化するか、この決定がいつ/どのように実現されるか、いつ/どのように見直されるかを定義してもよいです。他の決定やリソースへのリンクもここに記載します。
      value: |
        ―

        <!--
        (省略可能)
        決定の結果に対する追加的な証拠/信頼性を提供するか、チームの決定に対する同意を文書化するか、この決定がいつ/どのように実現されるか、いつ/どのように見直されるかを定義してもよいです。
        他の決定やリソースへのリンクもここに記載します。

        例：
        - yyyy/MM/ddから運用開始予定
        - 今後進める上で...を考慮する必要が出た場合など、また見直しが必要になったら再度議論する。
        - ...を修正する必要があるかどうかは未検討。
        - 後続の議論 #999
        -->
次に本テンプレート作成時に、意識した部分を特徴としてご紹介します。

 特徴
 日本語化GitHub Discussionsのカテゴリ フォームのテンプレートで、かつ 日本語のものはなさそうだったので、日本語化されたものとして用意しています。

 GitHub Discussionsカテゴリフォームの利用GitHubでプロジェクトを完結させようとすると、必要になると思います。

ADR用のカテゴリを作成して、フォームテンプレートを用意することで、作成負荷を減らしています。

 ADRの説明の記載カテゴリフォームのテンプレートに、ADRの説明・意義などを記載しています。

プロジェクトに途中から参加してきた方や、久しぶりにADRを記載する方向けに、いつでも意図・意義を伝えられます。

 必須/非必須項目の表現必須が多いとやはり負荷があがるので、最低限記載すべきものを絞り、フォーム入力時の必須項目として表現しています。

非必須項目には入れなくてもOKという意味で、デフォルトで「―」にしています。
(LADR なる、ミニマムなADRテンプレートを参考に必須/非必須を判断)

 例を豊富に用意こちらも、プロジェクトに途中から参加してきた方や、久しぶりにADRを記載する方向けに、負荷下げるため用意しています。

後で記載する場合に、例を残しておきたいが邪魔にならないように、例はコメントアウトにしています。
テンプレートと特徴を紹介できたので、自身のリポジトリに導入していきます。

 導入手順
 カテゴリを作成するDiscussionsでADR用のカテゴリを作成します。

フォームテンプレートのファイル名と、カテゴリのスラッグ(URLの末尾)が対応するようにする必要があります。
テンプレートファイルが adr-any-decision-record.yml なので、スラッグが adr-any-decision-record となるようなカテゴリ名であれば何でも良いです。

(私は、ADR (Any Decision Record) にしています。)

 ラベルを作成するテンプレートファイルのADRの説明箇所に記載してあるステータスのラベルを追加します。

テンプレートファイルで初期値は、ADR-proposed にしています。

 テンプレートを適用する.github/DISCUSSION_TEMPLATE/adr-any-decision-record.yml を追加します。
✅ DONE ✅

これで導入は終わりです。次に作成した結果について記載します。

 作成してみた結果🎉 個人的にADR作成の障壁がだいぶ下がりました！ 🎉
!チーム全体としての評価をするまではまだ運用しきれていないので、そのうち追記するかもしれません。

 Future Work
 ADRのstatus label付け外しを自動化する現状、ADRのstatusはGitHubのlabelでまかなっており、以下の問題があります。

ぱっと思いつく解決策あれば併記しています。
labelの仕様上、複数のstatusが設定できてしまう。
案) GitHub Actionsでlabelの付け外しを自動で行うようにする。

何をトリガーにするか、考えどころ・・・

まず初めにlabelを作成しないといけない。
案) labelの作成の段階から自動化に組み込む。

Discussionsをもっと有効活用するのに、何かアイディア・知見あれば気軽にコメント頂けるとありがたいです。

(GitHub Actionsで上手いこと連携しての運用も考えてみてもいいですね。)

 参考文献https://docs.aws.amazon.com/ja_jp/prescriptive-guidance/latest/architectural-decision-records/welcome.html
https://cloud.google.com/architecture/architecture-decision-records?hl=ja
https://adr.github.io/
https://adr.github.io/madr/

↑無駄のなく効率的に記録するため、Markdownで構造化されたテンプレートが用意されていました。
https://docs.github.com/ja/discussions/managing-discussions-for-your-community/creating-discussion-category-forms

脚注
今回は Any Decision Record の意 ↩︎
いくつかの企業の前例を見て判断しました。(新しい順)
GitHub Projects を利用したタスク管理 - 一休.com Developers Blog
モブプログラミング開発に ADR を導入した話 - Gunosy Tech Blog
継続的ドキュメンテーション: Github DiscussionsとADRのすすめ - LIFULL Creators Blog
↩︎
翻訳機能や英語に早いうちに慣れておくべきとは思いますが、障壁はなるべく減らすためプロジェクト全体で日本語に統一されています。いっそのこと日本語化に加えて、この際に今のチームに沿うようなドキュメントを作成しようという思いになりました。 ↩︎