novel-jp/learn-ie-write

/learn-ie-write — DR 作成（03-02）

技術選定テーマで DR を作成する演習です。

所要時間: 約 60 分 前提: /learn-ie-analyze（03-01）完了済み スキル対応: Intent Engineering（目的と判断基準）

---

Step 1: テーマ選択

以下から選択してもらう（または自分のプロジェクトから）:

| テーマ | 選択肢の例 | | ------------------------------- | ------------------------- | | A: 状態管理ライブラリの選定 | Redux vs Zustand vs Jotai | | B: API 設計方針 | REST vs GraphQL | | C: テスト戦略 | ユニット重視 vs E2E 重視 | | D: データベース選定 | RDB vs NoSQL | | E: 自由テーマ | 受講者のプロジェクトから |

「03-01 で良い DR と悪い DR の違いを学びました。
今度は自分で DR を書いてみましょう。

テーマは技術選定がおすすめです。
なじみのある技術でも、改めて『なぜそれを選ぶのか』を言語化してみてください。」

テーマを選んだら、選択肢の技術について 5 分程度リサーチする時間 を取る。選んだ技術をよく知っている場合はリサーチをスキップして Step 2 へ進んでもよい。知らない技術がある場合は、ブラウザで調べるか、AI に「各技術の特徴を教えて」と聞いても OK。

---

Step 2: DR 作成ガイド

以下のフィールドを必須として誘導する:

| フィールド | 説明 | 注意点 | | ---------------- | ---------------------------- | ------------------------------ | | context | なぜこの判断が必要になったか | 「〜が必要」だけでなく背景まで | | decision | 何を選んだか、なぜか | 結論 + 理由をセットで | | alternatives | 2 つ以上の代替案 | 各案に却下理由を記載 | | consequences | ポジティブ・ネガティブ両方 | ネガティブを省略しない | | 制約条件 | 技術的・ビジネス的制約 | 判断の前提となる条件 |

DR テンプレート

upsert_dr の body に渡す Markdown は、以下の構成で書く。各セクション 3〜5 行程度 が目安。03-01 で読んだ「良い DR」の構成を思い出しながら書いてみよう。

## Context

<!-- なぜこの判断が必要になったか。プロジェクトの状況・課題を書く -->

既存プロジェクトの CI/CD パイプラインを刷新する必要がある。
現在は手動デプロイで月2回のリリースだが、週次リリースに移行したい。
チーム4名、AWS 上で動作する Node.js アプリケーション。

## Decision

<!-- 何を選んだか + なぜその結論に至ったか -->

GitHub Actions を採用する。リポジトリと同一プラットフォームで完結し、
YAML ベースの設定がチーム全員にとって学習コストが低いため。
AWS へのデプロイも公式アクションで容易に実現できる。

## Alternatives

<!-- 2つ以上の代替案。各案に却下理由を必ず書く -->

### CircleCI

並列実行性能は優れるが、外部サービス契約が追加で必要。
現在のビルド規模では GitHub Actions の無料枠で十分であり、
コスト面のメリットがない。

### AWS CodePipeline

AWS ネイティブで IAM 統合が容易だが、設定が CloudFormation 前提で
パイプラインの変更・デバッグに時間がかかる。
チームに CloudFormation の経験者がいない。

## Consequences

<!-- ポジティブ・ネガティブ両方を書く -->

**ポジティブ**: リポジトリ内で完結、PR との連携が自然、コミュニティのアクションが豊富
**ネガティブ**: 複雑なワークフローでは YAML が肥大化しやすい、GitHub 障害時にデプロイ不可

## Constraints

<!-- 判断の前提となる技術的・ビジネス的制約 -->

- AWS 上の Node.js アプリケーション（ECS Fargate）
- 追加の SaaS 契約は承認プロセスが必要で時間がかかる
- チームに CI/CD ツールの深い経験者がいない

「ヒント: 『なんとなく良さそうだから』は却下理由になりません。
具体的なメリット/デメリットの比較で判断してください。」

DR の内容が書けたら、チャットに DR の内容を貼り付けて 「この内容で DR を登録して」 と AI に伝えてください。次の Step 3 で登録されます。

---

Step 3: upsert_dr で登録

受講者が DR を書き終えたら、ProjSight に登録する。

AI に 「この内容で DR を登録して」 と伝えてください。AI が upsert_dr を実行します。

• type は architecture を使う（技術選定 DR のため。他に requirements, process, design が使用可能）
• タイトルは AI が DR の内容から適切に設定します。自分で指定したい場合は「タイトルは〜にして」と伝えてください
• DR は学習用プロジェクトに登録されます。本番プロジェクトには影響しません

---

Step 4: /review-dr でセルフレビュー

/review-dr と入力して、作成した DR をレビューする。直前に登録した DR が自動的にレビュー対象になる。

• スコアは 10 点満点 で表示される
• スコアを確認し、8 点未満なら改善を提案する
• 特に以下の点を重点チェック:
  • 代替案が 2 つ以上あるか
  • 却下理由が具体的か
  • ネガティブな影響が記載されているか

改善が必要な場合は、レビュー指摘を確認し、AI に 「〈指摘内容〉を修正して」 と伝えてください。AI が upsert_dr で DR の body を更新します。修正後、再度 /review-dr でスコアを確認してください。

改善ループの目安: 2 回改善しても 8 点未満の場合は、レビュー指摘のうち最も重要な 1 点を修正して先に進んでください。完璧を目指すより、振り返りで学びを定着させることが大切です。

---

Step 5: 振り返り

「DR を書くことで、『なんとなく選んだ』を『根拠を持って選んだ』に変えられます。

ポイント:
- DR は自分の判断力を証明するドキュメント
- 半年後に『なぜこうしたんだっけ？』と迷わなくなる
- AI にも DR を渡すことで、一貫性のある判断をしてもらえる
- 03-01 で見た悪い DR のパターンを、自分では書かないよう意識する」

振り返りの問いかけ（チャットで回答してもらう）:

「03-01 で分析した『悪い DR』のパターン（代替案なし、却下理由が曖昧、ネガティブ影響の省略など）を、
自分の DR では避けられましたか？ どの点が難しかったですか？」

受講者のタスクを complete_work(taskId) で完了にする。