メインコンテンツまでスキップ

ADR（設計判断の記録）教育コンテンツ：12章アウトライン 🧭📒✨

第1章：ADRってなに？未来の自分を助ける「設計メモ」じゃないよ😊📌​

  • 🎯 ゴール：ADRの目的と効果（なぜ必要か）を理解する

  • 📌 学ぶこと

    • ADR＝「重要な判断」と「理由」を残す“設計の履歴書”📝
    • ありがちな事故：「なんでこうしたっけ？」問題😵‍💫
    • ADRが効く場面（技術選定、例外方針、層/境界、データ設計など）

  • 🧪 ミニ演習

    • 最近の迷いを1つ思い出して「判断＋理由」を3行で書く✍️

  • 🤖 AI活用

    • 「その判断、メリット/デメリット何？」をAIに質問して視点を増やす✨

第2章：ADRの基本テンプレを覚えよう（型があると最強）🧩📄​

  • 🎯 ゴール：ADRの“定番フォーマット”を使って書けるようになる

  • 📌 学ぶこと

    • 基本セット：Context / Decision / Consequences ✅
    • 追加しがちな項目：Status（提案中/採用/置き換え）・Date・Links 🔗
    • 「1判断＝1ファイル」「短く」ルール📌

  • 🧪 ミニ演習

    • サンプルADRを読んで、3要素に色分けする🖍️

  • 🤖 AI活用

    • “文章をテンプレに当てはめる”変換をAIにやらせる🪄

第3章：いつADRを書く？「書きどき判定」スキル🔍✅​

  • 🎯 ゴール：ADRにすべき判断／しなくていい判断を見分ける

  • 📌 学ぶこと

    • ADR向き：後戻りコスト大💥／長期間効く🕰️／他人に影響👥
    • ADR不要：細かい命名、軽いUI、すぐ捨てる試作など🙅‍♀️
    • “大きすぎる判断”の分割の考え方✂️

  • 🧪 ミニ演習

    • 判断ネタを10個仕分け（ADR必要/不要）🗂️

  • 🤖 AI活用

    • ネタを投げて「ADR向き度」を採点してもらう📊

第4章：設計判断の作り方（比較軸と選択肢を作る）🎛️🧠​

  • 🎯 ゴール：「決め方」を型にして、迷いを減らす

  • 📌 学ぶこと

    • 選択肢（Options）を最低2〜3個出す🌱
    • 比較軸の定番：開発速度⚡／保守性🧹／学習コスト📚／運用💡／性能🚀／テスト容易性🧪
    • 制約（期限、既存資産、チームスキル）を先に固定📌

  • 🧪 ミニ演習

    • 1つのテーマで「選択肢3つ＋比較軸5つ」を作る🧾

  • 🤖 AI活用

    • AIに「比較軸の漏れチェック」「反対意見（悪魔の代弁者😈）」をやらせる

第5章：ADRの書き方① Context（背景）が弱いと読まれない🥺➡️😊​

  • 🎯 ゴール：Contextを“短く強く”書けるようになる

  • 📌 学ぶこと

    • Contextに入れるべきもの：問題・痛み😣／制約📌／現状の仕組み⚙️
    • NG例：ふわっとしたお気持ち文章☁️
    • OK例：誰が読んでも同じ状況が思い浮かぶ文章🗺️

  • 🧪 ミニ演習

    • 悪いContextを“良いContext”に直すゲーム🎮

  • 🤖 AI活用

    • 「このContext、足りない情報ある？」をAIに聞く🔎

第6章：ADRの書き方② Decision＆Consequences（結論と言い切り＋トレードオフ）⚖️✨​

  • 🎯 ゴール：Decisionを明確に書き、Consequencesで“痛み”も伝えられる

  • 📌 学ぶこと

    • Decisionは一文で言い切る✅（曖昧にしない）
    • Consequencesは“良い点”だけじゃなく“困る点”も書く💦（ここ超大事！）
    • リスク・保留事項・将来の見直し条件も軽く触れる🧷

  • 🧪 ミニ演習

    • 同じDecisionで「良い結果/悪い結果」を3つずつ書く✍️

  • 🤖 AI活用

    • 「デメリット言語化」「運用の困りごと予測」をAIに手伝ってもらう🤖

第7章：リポジトリにADRを置く（迷子にならない仕組み）📁🧭​

  • 🎯 ゴール：ADRが“探せて育つ”置き方を作る

  • 📌 学ぶこと

    • 置き場所例：docs/adr/（MarkdownでOK）🗂️
    • 命名：連番＋短いタイトル（例：0001-xxx）🔢
    • テンプレを用意して、毎回の負担を減らす🧩
    • Visual StudioのGit機能でコミットまでできるよ👍

  • 🧪 ミニ演習

    • docs/adr/0001-...md を作ってコミットする📌

  • 🤖 AI活用

    • テンプレ生成、タイトル案、要約をAIに作らせる🪄

第8章：開発フローに組み込む（PRとレビューで“後回し”を防ぐ）🔁✅​

  • 🎯 ゴール：ADRが「書いたら終わり」じゃなく、チーム作法になる

  • 📌 学ぶこと

    • ルール例：「重要な判断はPRにADRを添付」📎
    • レビュー観点：Context足りてる？選択肢は？デメリット書けてる？👀
    • “合意の取り方”の軽い型（コメント→修正→Accepted）🗳️

  • 🧪 ミニ演習

    • ADR付きPRを作って、自分でレビュー観点チェック✅

  • 🤖 AI活用

    • AIに「レビューコメント案」を出してもらう💬🤖（優しめで！）

第9章：ADRを腐らせない（Supersededと棚卸し）🌿🛠️​

  • 🎯 ゴール：古い判断を“価値ある履歴”として残し続ける

  • 📌 学ぶこと

    • ADRは基本「書き換え」より「置き換え」✨
    • 新ADRで置き換え、旧ADRはStatusをSupersededにする🔁
    • 見直しタイミング：半年、障害後、技術刷新、運用で困った時🕰️

  • 🧪 ミニ演習

    • 0001を置き換える0002を作る（リンクも付ける）🔗

  • 🤖 AI活用

    • AIに「いまの前提とズレてない？」チェックをさせる🔎

第10章：ミニプロジェクト① 題材選び＆スコープ決め（1本に絞る！）🎯🍀​

  • 🎯 ゴール：ミニプロジェクトの題材を1つに決めて、やることを小さくする

  • 📌 学ぶこと

    • 題材例（どれか1つ！）

      • ログ方針どうする？🪵
      • 例外方針どうする？⚠️
      • DBアクセス方針どうする？🗄️

    • “決める範囲”を絞る（大きすぎると死ぬ😂）

    • 比較軸＆制約を確定する📌

  • 🧪 成果物

    • 「判断テーマ」「選択肢」「比較軸」「制約」の1枚メモ🧾

  • 🤖 AI活用

    • 比較表のたたき台作成、選択肢の追加提案🤖📊

第11章：ミニプロジェクト② ADRを書いてPRに乗せる（実戦！）🧑‍💻📦​

  • 🎯 ゴール：ADRを1本完成させ、PRで回せるようにする

  • 📌 学ぶこと

    • ADR 0001 を完成させる（Context/Decision/Consequences）📝
    • Issue/PR/設計メモへのリンクを貼る🔗
    • 変更が入ったらConsequencesやLinksも更新する🧷

  • 🧪 成果物

    • ADR 0001（完成）＋PR（レビュー可能状態）✅

  • 🤖 AI活用

    • AIに「文章の明確化」「デメリット追加」「読みやすさ改善」を頼む✂️✨

第12章：ミニプロジェクト③ レビュー反映＆“自分の型”を作って卒業🎓🌸​

  • 🎯 ゴール：ADR運用を“習慣化できる形”に落とし込む

  • 📌 学ぶこと

    • レビューを反映してADRを磨く💎
    • “置き換えが必要になったら？”の想定を1回やってみる🔁
    • 自分専用の「ADRチェックリスト」を作る🧾✨
    • 次に扱うと強い判断の例（運用・障害対応・監視など）📈

  • 🧪 成果物

    • 完成ADR（レビュー反映済み）＋個人チェックリスト✅

  • 🤖 AI活用

    • AIに「最終レビュー」「反対意見」「抜け漏れチェック」をやらせる🤖🧠