novel-jp/learn-ce-maintain

/learn-ce-maintain — DD 更新体験（02-04）

要件変更シナリオを受け、既存 DD の更新判断と実施を体験する演習です。

所要時間: 約 45 分 前提: /learn-ce-dd（02-03）完了済み スキル対応: Context Engineering（情報環境の設計）

---

Step 1: 演習タスクの開始

1. list_deliverables(projectId) で紐付け先の成果物を確認する
2. upsert_task(projectId, title: "02-04 DD 更新体験", deliverableId, description) でタスクを作成する
3. start_work(taskId) でタスクを開始する

---

Step 2: シナリオ提示と判断

02-03 で作成した DD に対して、2 つの要件変更シナリオを提示する。それぞれについて、受講者に 更新方法を自分で判断してもらう。

シナリオ A（小規模変更）

「クライアントから『ページネーションの件数を 20 → 50 に変更してほしい』と依頼がありました。
この変更は DD にどう反映しますか？」

受講者に問いかける: 「あなたならこの変更を DD にどう反映しますか？ 既存の DD を書き換えますか、それとも新版を作りますか？」

シナリオ B（大規模変更）

<!-- guide-only: シナリオ B は受講者の DD 内容に合わせて動的に生成する。 以下の手順で生成すること: 1. `get_dr` で受講者の 02-03 DD を取得する 2. DD の内容を読み、構造変更を伴う変更シナリオを1つ生成する - DD に認証方式の記述がある場合: 「認証方式を JWT → セッション Cookie に変更」のようなシナリオ - DD に認証方式の記述がない場合: DD に実際に含まれるセクションの中から、構造変更を伴うテーマを選ぶ 3. 「セキュリティレビューの結果、〇〇を△△に変更することになりました。この変更は DD にどう反映しますか？」の形式で提示する 要件: 受講者の DD に存在するセクションをテーマにすること。DD にないトピックでシナリオを作ると演習が破綻する。 -->

ガイド AI は受講者の 02-03 DD を読み、その内容に合わせた 構造変更を伴う変更シナリオ を1つ生成して提示する。

受講者に問いかける: 「この変更は DD にどう反映しますか？ 既存の更新で対応できますか、それとも新版を作るべきですか？」

<!-- guide-only: 期待する判断 - シナリオ A → `upsert_dr(body)` で既存 DD を更新（設計の骨格は変わらない） - シナリオ B → `add_design_doc(supersedes)` で新版を作成（構造変更） 受講者の回答が上記と異なる場合は、Step 3 の判断基準テーブルで理由を解説する。 -->

---

Step 3: 判断基準の解説

受講者の回答を受けて、以下の判断基準を提示する:

| 変更の規模 | 方法 | 判断基準 | | ---------------------------- | --------------------------------------- | ----------------------------- | | 小規模（数値変更、追記） | upsert_dr(body) で既存更新 | 設計の骨格は変わらない | | 大規模（構造変更） | add_design_doc(supersedes) で新版作成 | セクション追加/削除、方針転換 | | 根本変更 | 新 DR + add_design_doc(supersedes) | なぜ変えたかの記録も必要 |

DD と DR の役割分担: supersedes は「何が変わったか」を記録しますが、「なぜ変えたか」の経緯までは残りません。根本変更では DR を別途作成し、意思決定の理由を記録します。DD = 現在の設計仕様、DR = 意思決定の経緯。この役割分担が、設計の「今」と「なぜ」の両方を追跡可能にします。

「小規模なら上書き、大規模なら新版。
根本変更なら『なぜ変えたか』の DR も一緒に残す。
これが DD メンテナンスの基本判断です。」

根本変更の具体例: たとえば「モノリスからマイクロサービスへのアーキテクチャ移行」「REST API から GraphQL への全面移行」など、設計思想そのものが変わるケースが根本変更に該当します。こうした変更では、新版 DD だけでなく「なぜ移行するのか」を DR に記録しないと、後から経緯を辿れなくなります。

---

Step 4: 実施

受講者にシナリオ A と B の両方を実施してもらう。

まず、02-03 で作成した DD を get_dr で確認する。DD の内容を思い出し、現在の構成を把握してから変更作業に入る。

ツール名の補足: DD（設計ドキュメント）は内部的に DR エンティティとして管理されています。そのため作成は add_design_doc、更新・取得は upsert_dr / get_dr を使います。

シナリオ A の実施

1. get_dr で取得した DD の body から該当箇所を修正する
2. upsert_dr(drId, body) で更新する

補足: upsert_dr は body 全体を渡して上書きします。get_dr で取得した body をベースに、該当箇所を修正したものを渡してください。

シナリオ B の実施

1. get_dr で旧版 DD の body を取得する
2. 旧版の構成をベースに、変更が必要なセクションを書き換える

<!-- guide-only: シナリオ B で生成した変更テーマに応じて、変更スコープを具体的に指示する。 例（認証方式変更の場合）: 「旧版の構成をベースに、以下のセクションを書き換えてください: - 認証方式（JWT → セッション Cookie） - セッション管理（新規追加） - セキュリティ考慮事項（トークン管理 → Cookie セキュリティ） それ以外のセクション（API エンドポイント、データモデル等）はそのまま残してください。」 変更テーマに合わせて、「書き換えるセクション」と「そのまま残すセクション」を明示すること。 DD 全体をゼロから書かせない。旧版をベースにした差分更新にフォーカスする。 -->

ガイド AI は変更テーマに応じて、書き換えるセクションとそのまま残すセクションを明示して指示する。DD 全体をゼロから書く必要はない。旧版をベースに該当箇所を更新する。

3. add_design_doc(supersedes: drId) で新版を作成する

補足: supersedes には旧版 DD の drId（UUID）を渡します。get_dr の返却値から取得できます。

4. 旧版が superseded ステータスになったことを確認する

---

Step 5: 振り返り

「DD は『生きたドキュメント』です。コードと DD が乖離すると、
AI が古い設計を参照して間違った実装をします。

DD の更新は Context Engineering の重要な一部です:
- コードを変えたら DD も変える
- 変更の規模に応じて『更新 vs 新版作成』を判断する
- supersedes で履歴を残すことで、設計の進化を追跡できる

次の /learn-ce-session では、セッション管理を学びます。」

---

Step 6: タスク完了

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