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

ADR（設計判断の記録）教材アウトライン（TypeScript版・12章）📝✨

前提：Windows + VS Code 💻 / TypeScript初級〜中級 / ADR初めて / 設計超入門者 / CopilotやCodexなどAI導入済み🤖💕

第1章：ADRってなに？「設計の理由」を未来に残すノート📒🌸​

  • 🎯 ねらい：ADRが「メモ」じゃなくて「判断の証拠＆説明書」だと理解する

  • 📌 学ぶこと：

    • ADRが必要になる“あるある”😵‍💫（数ヶ月後の自分が困る）
    • TypeScript開発で判断が増える場面（ライブラリ選定、型方針、API方針、境界など）

  • 🧪 ワーク：最近の「迷った判断」を1つ書き出す（1分✍️）

  • 🤖 AI活用：その判断の「メリ/デメ」をAIに箇条書きで出してもらう✨

第2章：ADRの基本テンプレ（型）を手に入れよう🧩📝​

  • 🎯 ねらい：書ける形（テンプレ）を覚えて、迷いを減らす

  • 📌 学ぶこと：

    • 最小構成：Context / Decision / Consequences ✅
    • あると便利：Status（Proposed/Accepted/Superseded）・日付・リンク🔗
    • 「短く」「1判断＝1ファイル」が基本💡

  • 🧪 ワーク：短いサンプルADRを読んで3要素を色分け🖍️

  • 🤖 AI活用：テンプレに沿って“整形”してもらう🪄

第3章：いつADRを書く？“書きどき判定”ルール🎯✅​

  • 🎯 ねらい：何でもADRにせず、重要な判断だけ拾えるようになる

  • 📌 学ぶこと：

    • ADR向き：後戻りコスト大💥 / 長く効く🕰️ / チーム影響👥
    • ADR不要：小さな修正、軽いリネーム、すぐ捨てる試作など🙅‍♀️
    • 「判断が大きすぎる」時の分割の考え方✂️

  • 🧪 ワーク：判断ネタ10個を「ADR必要/不要」に仕分け🗂️

  • 🤖 AI活用：AIに“ADR向き度”を採点させて理由も聞く📊

第4章：TypeScript向け「判断の作り方」— 比較軸と選択肢の出し方⚖️✨​

  • 🎯 ねらい：「なんとなく決めた」を卒業して、筋の良い決め方を身につける

  • 📌 学ぶこと：

    • 選択肢（Options）を2〜3個は必ず出す🌱
    • TS開発で多い比較軸：DX（開発体験）🧁 / 型安全🧷 / 学習コスト📚 / 運用💼 / パフォーマンス🚀 / 保守性🧹
    • “制約”を先に固定（納期・既存・チームスキル）📌

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

  • 🤖 AI活用：AIに「比較軸の漏れ」「反対意見（悪魔の代弁者😈）」を出させる

第5章：書き方① Context（背景）を短く強く！📌🗺️​

  • 🎯 ねらい：読んだ人が“状況を再現できる”Contextを書く

  • 📌 学ぶこと：

    • Contextに入れるべき：問題・痛み😣 / 現状 / 制約 / 何を優先するか
    • TSならではの背景例：型と実行時のズレ、依存パッケージ、ビルド/実行環境など

  • 🧪 ワーク：悪いContext→良いContextに直す（3パターン）🎮

  • 🤖 AI活用：「足りない情報ある？」をAIに指摘させる🔎

第6章：書き方② Decision（結論）は“一文で言い切る”✨🧠​

  • 🎯 ねらい：Decisionがブレない書き方を身につける

  • 📌 学ぶこと：

    • Decisionは一文で確定させる✅（曖昧な “〜するかも” を減らす）
    • スコープ（どこまで適用？いつから？例外は？）を添える🧷
    • 受け入れ条件（これが満たされたらOK）を軽く書く🎯

  • 🧪 ワーク：同じ内容で「弱いDecision」と「強いDecision」を書き比べ✍️

  • 🤖 AI活用：Decision文を“短く明確に”リライトしてもらう✂️

第7章：書き方③ Consequences（結果）— “痛み”もちゃんと書く💦💎​

  • 🎯 ねらい：メリットだけの作文を卒業して、判断の価値を上げる

  • 📌 学ぶこと：

    • 良い点👍 / 悪い点👎 / リスク⚠️ / 運用の手間🧹
    • TSらしい結果例：型の厳しさ、runtime validationの必要性、依存更新コストなど
    • 「どう検証する？」（PoC/計測/手戻り条件）を一言入れると強い🔍

  • 🧪 ワーク：Consequencesを「良い3つ＋悪い3つ」で必ず書く✍️

  • 🤖 AI活用：「想定デメリット」をAIに追加提案してもらう🧠

第8章：置き場所と管理（VS Codeで迷子にならないADR運用）📁🧭​

  • 🎯 ねらい：ADRを“探せる・育てられる”形でリポジトリに置ける

  • 📌 学ぶこと：

    • 置き場所例：docs/adr/（Markdown）🗂️
    • 命名：0001-xxx.md のように連番＋短い題名🔢
    • テンプレ固定で“書くハードル”を下げる🧩
    • VS CodeでのMarkdown運用（プレビュー、リンク、検索）🔎

  • 🧪 ワーク：docs/adr/0001-...md を作ってコミット📌

  • 🤖 AI活用：テンプレ自動生成、タイトル案、要約案を出させる🤖✨

第9章：開発フローに組み込む（PRとレビューで文化にする）🔁✅​

  • 🎯 ねらい：「あとで書く」を防いで、ADRが“自然に増える”状態にする

  • 📌 学ぶこと：

    • ルール例：「重要な判断はPRにADRを添付」📎
    • レビュー観点：背景OK？選択肢ある？トレードオフ書けてる？👀
    • “合意の作法”を軽く（Proposed→Accepted）🗳️

  • 🧪 ワーク：ADR付きPRを想定してセルフレビュー✅

  • 🤖 AI活用：AIに「レビューコメント案」を作らせる（優しめ口調で💬😊）

ここから最終エクササイズ（3章）🎓🚀💕​

第10章：最終課題① テーマ決め＆比較表づくり（1テーマに絞る！）🎯🍀​

  • 🎯 ねらい：最後にやることを“小さく確実に”する（ここ超大事！）

  • 📌 テーマ例（どれか1つだけでOK）：

    • 🧩 例A：runtime validation をどうする？（zod等 vs 自前）
    • 🧱 例B：状態管理 をどうする？（Reactなら軽量方針など）
    • 🔌 例C：API呼び出し層 をどう分ける？（fetch直書き vs ラッパ）
    • 🧹 例D：エラー方針（例外で投げる/Result風/統一エラー型）

  • 🧪 成果物：選択肢3つ＋比較軸5つ＋制約＋ざっくり結論案🧾

  • 🤖 AI活用：比較軸の漏れチェック＆反対意見😈

第11章：最終課題② ADRを書いて、実装に反映する📝🧑‍💻​

  • 🎯 ねらい：ADRが「紙だけ」にならず、コードとセットで動く経験をする

  • 📌 学ぶこと：

    • ADR 0001を完成（Context/Decision/Consequences）✅
    • Issue/PR/メモへのリンク🔗
    • 実装側にも“判断が反映された場所”を残す（READMEやコメントの軽いリンク）📍

  • 🧪 成果物：ADR 0001（完成）＋対応する変更コミット📦

  • 🤖 AI活用：文章の明確化、デメリット補強、読みやすさ改善✂️✨

第12章：最終課題③ レビュー反映＆置き換え体験（Superseded）で卒業🎓🌸​

  • 🎯 ねらい：ADRを「育てる」運用を体験して、習慣化の型を作る

  • 📌 学ぶこと：

    • レビューを反映してADRを磨く💎
    • “前提が変わった”想定で 0002で置き換え → 0001をSuperseded🔁
    • 自分用の「ADRチェックリスト」を作って完成🧾✨

  • 🧪 成果物：ADR 0002（置き換え）＋個人チェックリスト✅

  • 🤖 AI活用：最終レビュー、抜け漏れチェック、反対意見で強化🤖🧠