02-04 DD 更新体験。要件変更シナリオを受け、既存 DD の更新判断と実施を体験する。
要件変更シナリオを受け、既存 DD の更新判断と実施を体験する演習です。
所要時間: 約 45 分
前提: /learn-ce-dd（02-03）完了済み
スキル対応: Context Engineering（情報環境の設計）
list_deliverables(projectId) で紐付け先の成果物を確認するupsert_task(projectId, title: "02-04 DD 更新体験", deliverableId, description) でタスクを作成するstart_work(taskId) でタスクを開始する02-03 で作成した DD に対して、2 つの要件変更シナリオを提示する。それぞれについて、受講者に 更新方法を自分で判断してもらう。
「クライアントから『ページネーションの件数を 20 → 50 に変更してほしい』と依頼がありました。
この変更は DD にどう反映しますか？」
受講者に問いかける: 「あなたならこの変更を DD にどう反映しますか？ 既存の DD を書き換えますか、それとも新版を作りますか？」
ガイド AI は受講者の 02-03 DD を読み、その内容に合わせた 構造変更を伴う変更シナリオ を1つ生成して提示する。
受講者に問いかける: 「この変更は DD にどう反映しますか？ 既存の更新で対応できますか、それとも新版を作るべきですか？」
受講者の回答を受けて、以下の判断基準を提示する:
| 変更の規模 | 方法 | 判断基準 |
|---|---|---|
| 小規模（数値変更、追記） | 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 に記録しないと、後から経緯を辿れなくなります。
受講者にシナリオ A と B の両方を実施してもらう。
まず、02-03 で作成した DD を get_dr で確認する。DD の内容を思い出し、現在の構成を把握してから変更作業に入る。
ツール名の補足: DD（設計ドキュメント）は内部的に DR エンティティとして管理されています。そのため作成は
add_design_doc、更新・取得はupsert_dr/get_drを使います。
get_dr で取得した DD の body から該当箇所を修正するupsert_dr(drId, body) で更新する補足:
upsert_drは body 全体を渡して上書きします。get_drで取得した body をベースに、該当箇所を修正したものを渡してください。
get_dr で旧版 DD の body を取得するガイド AI は変更テーマに応じて、書き換えるセクションとそのまま残すセクションを明示して指示する。DD 全体をゼロから書く必要はない。旧版をベースに該当箇所を更新する。
add_design_doc(supersedes: drId) で新版を作成する補足:
supersedesには旧版 DD のdrId（UUID）を渡します。get_drの返却値から取得できます。
superseded ステータスになったことを確認する「DD は『生きたドキュメント』です。コードと DD が乖離すると、
AI が古い設計を参照して間違った実装をします。
DD の更新は Context Engineering の重要な一部です:
- コードを変えたら DD も変える
- 変更の規模に応じて『更新 vs 新版作成』を判断する
- supersedes で履歴を残すことで、設計の進化を追跡できる
次の /learn-ce-session では、セッション管理を学びます。」
受講者のタスクを complete_work(taskId) で完了にする。