├── LICENSE ├── README.md ├── SAMPLE_adr-001-ADRの利用.md └── TEMPLATE.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 moomoo-ya 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # LADR-template 2 | 3 | Lightweight Architecture Decision Recordsテンプレート。 4 | 5 | ## LADRとは 6 | 7 | **L**ightweight **A**rchitecture **D**ecision **R**ecordsの略。 8 | 9 | 「なぜそのアーキテクチャ選択を行ったのか」という意思決定（ADR）を簡潔（軽量、Lightweight）に記録を残すこと。 10 | 11 | ## 記録方法 12 | 13 | - [TEMPLATE.md](TEMPLATE.md)の書式にしたがって記述 14 | - 1アーキテクチャ1ファイル 15 | - ファイル名の接頭辞に`adr-001-`などとつけると決定の順に並ぶのでいいかもしれない 16 | - できる限り対象アプリケーションのソースコードレポジトリに格納 17 | - 原則、一度確定したADRは更新しない 18 | - 関連する意思決定を行う場合は既存の関連ADRを参照しつつ新しいADRを記録 19 | -------------------------------------------------------------------------------- /SAMPLE_adr-001-ADRの利用.md: -------------------------------------------------------------------------------- 1 | # Architecture Decision Records: ADRの利用 2 | 3 | ## Date - 日付 4 | 5 | 2018-04-24 6 | 7 | ## Context - 文脈 8 | 9 | 既存の商材についてアーキテクチャ選定の記録がなく、当時の開発者からの口伝でのみ伝わってきている状況だった。そのため、「正当な理由があって採用しているアーキテクチャ」と「仕方がなく（将来的に改修を望まれて）採用しているアーキテクチャ」の判断が困難だった。また当時は正当な理由があった場合でも、利用ソフトウェアのアップデートや、参画メンバーの変化に伴い採用している理由がなくなる場合はさらに判断が困難だった。 10 | 11 | アーキテクチャ決定の記録を残すことで保守運用の助けになることと、今後の新規システムのアーキテクチャ決定の参考になることを期待する。 12 | 13 | [Technology Radar - ThoughtWorks](https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records) にてADOPTに格上げされており（有用性があると評価されている）、採用にもそれほど手間がかからないため試験的に導入してみたい。 14 | 15 | ## Status - 状況 16 | 17 | Accepted 18 | 19 | ## Decision - 決定事項 20 | 21 | モノは試しで記録を残してみる。 22 | 23 | ## Consequences - 結果 24 | 25 | 後日別プロジェクトのアーキテクチャ検討の機会があった際に本ADRの内容をベースに議論することができた。 26 | -------------------------------------------------------------------------------- /TEMPLATE.md: -------------------------------------------------------------------------------- 1 | # Architecture Decision Records:（タイトル） 2 | 3 | > 「何」に対しての意思決定を行ったのかがわかるタイトルにする。 4 | > 5 | > 「マイクロサービスアーキテクチャ」といった概念であったり、「Kubernetes」といったプロダクト名であったり、「スクラムにおけるタイムボックスの長さ」といったプロジェクトにおける設定値であってもよい。 6 | > 7 | > 大事なことはあとから「このプロジェクトでこういう進め方をしているのはなぜだろうか」と見直したときに該当するADRがどれかわかることである。 8 | > 9 | > 複数の内容を含めると内容がブレるので簡潔なタイトルが決まらない場合は記述しようとしている単位を見直すと良いかもしれない。 10 | 11 | ## Date - 日付 12 | 13 | YYYY-MM-DD 14 | 15 | > 意思決定を行った日付。 16 | > 意思決定の開始日なのか、完了日なのかは統一されていればどちらでも良い。 17 | > 18 | > 日単位の正確さよりも「何年何月ごろに行われた意思決定なのか」ということが重要。 19 | 20 | ## Context - 文脈 21 | 22 | > - 経緯：なぜこの意思決定が生まれたのか 23 | > - 現状の課題 24 | > - 期待している効果 25 | > - など 26 | > - 観点：良し悪しを判断した観点 27 | > - 採用した場合のメリット／デメリット 28 | > - 開発スケジュールとの兼ね合い 29 | > - 社内関連部署との関係性 30 | > - 業界のトレンド 31 | > - など 32 | > - 事情：採用状況を判断するために検討した事情 33 | > - 経験者がいた 34 | > - リモートワークによってコミュニケーションに変化がある 35 | > - 経験の浅いメンバーが多い 36 | > - メンバーの入れ替わりが激しい 37 | > - など 38 | > - 参考情報：参考文献やWebサイトのURL 39 | > 40 | > といった情報を記録する。もちろん網羅する必要はなく、各意思決定ごとに記録に残すべき内容は上記になくても記録するべきである。 41 | > 記録内容は箇条書きで残すよりも文章として残したほうがよい。 42 | > 43 | > 建前を記録する必要はなく、意思決定に影響した雑多な事実を記述する。そうしなければ後から見返したときに「結局わからない」という状況になる。 44 | > たとえば「メンバーの学習が追いつかないため採用を見送った」といった対外的には格好がつかない理由であっても意思決定に影響しているのであれば記録するべき。 45 | > 46 | > ※組織文化的に対外的な体裁の整った記録を求められるようであれば、実施しても効果が出ないのでADRの記録をやめることを検討する。 47 | 48 | ## Status - 採用状況 49 | 50 | Accepted / Rejected / On holding 51 | 52 | > 採用（Accepted）したのか、不採用（Rejected）だったのかを記録。 53 | > 54 | > 採用の場合は**現在の**開発に反映されているので詳細な情報はいらないが、不採用だった場合には不採用に至った理由を併記する。 55 | > 56 | > 決定を後回しにする場合は保留（On holding）として別の意思決定に移ると良い。 57 | 58 | ## Decision - 決定事項 59 | 60 | > Acceptedになった場合の想定している運用や制約、再評価となる条件、想定している製品、採用時の温度感などを記述しておく。 61 | > 62 | > 「デプロイプロセスに初期から組み込む」「当初見積もり規模から2倍に膨れ上がった場合は再評価を行う」「テストランナーは○○の利用を想定」「試しに採用する」など。 63 | 64 | ## Consequences - 結果 65 | 66 | > 意思決定の結果を評価したタイミングで追記する。 67 | > 68 | > - 期待した効果が得られたか得られなかったか 69 | > - 今後の採用に向けての注意点 70 | > - など 71 | --------------------------------------------------------------------------------