| name | modification-design |
| description | 実装前に、既存コードや仕様を根拠として、変更後のシステム構造を Modification Design に整理するときに使う。ユーザーが「変更後の設計」「実装前の設計」「何をどう変えるか」「責務、interface、contract、依存関係、影響、リスクを整理して」などを求めた場合は必ず使う。Plan のような実装手順やタスクリストではなく、変更対象となるモジュール、コンポーネント、API、型、データの変更後の責務と境界をレビュー可能な自然言語で定義する。コード、擬似コード、diff は出力しない。 |
Modification Design
目的
コードを書き始める前に、「何をどの順番で実施するか」ではなく、「変更後のシステムがどのような構造になるか」を自然言語で設計する。
Modification Design は、実装者が構造を推測せず、レビュー担当者が責務、公開 contract、依存方向、影響とリスクを実装前に検証できる具体性を持たせる。
適用範囲
次の成果物を求められた場合に使う。
- 既存システムの機能追加、仕様変更、置き換えに対する変更後設計
- モジュール、コンポーネント、ライブラリ、API、クラス、型の責務変更
- API、DTO、Entity、Event、Message などの contract 変更
- モジュール間の依存方向やデータフローの変更
実装手順、タスクリスト、Definition of Done が主目的の場合は role-planner を優先する。React UI の詳細な component tree、props、hooks、状態管理が主目的の場合は component-design を優先する。実装済み差分の欠陥検出は code-review を優先する。
作成前の確認
指定されたコード、仕様、issue、設計文書、公開 interface を先に確認する。現在の責務や contract を推測で断定しない。
設計を確定できない情報がある場合は、次のいずれかとして扱う。
- 設計を左右する不明点は、作成前にユーザーへ確認する。
- 設計全体を止めない不明点は、仮定または未解決事項として明示し、影響する変更対象と risk を示す。
- 入力から確認できない「現在」の説明は書かず、確認できた範囲を明記する。
設計原則
- 変更点だけを記述し、既存システム全体の説明へ広げない。
- 変更対象を高凝集・疎結合なレゴとして整理する。レゴの境界判断には
lego-programming を併用する。
- 各レゴには一つの変更理由を持たせ、入力、出力、所有する状態、副作用、依存先が分かるようにする。
- 公開 interface と data contract は実装詳細から分離する。
- 追加、削除、変更、変更なしを区別する。特に contract に変更がない場合も「変更なし」と明記する。
- 後方互換性や migration が必要な場合は、移行期間中の旧 contract と新 contract の扱いを明示する。
- 実装手段を一意に縛る必要がない箇所は、構造と責務だけを定義する。
出力形式
以下の順序と見出しで出力する。該当項目がない章も省略せず、「変更なし」または「該当なし」と記載する。
1. 変更概要
- 何を変更するか
- なぜ変更するか
- 変更後に成立させる構造または振る舞い
2. 変更対象
変更するレゴを列挙する。ファイル一覧ではなく、責務を持つモジュール、コンポーネント、ライブラリ、API、クラス、型、データストアなどの単位で書く。
各対象には、可能な範囲で既存コード上の名称を使う。新規対象は新規であることを明記する。
3. Modification Design
変更対象ごとに次を記述する。
- 現在: 今回の変更に関係する現在の責務と境界
- 変更後: 追加、削除、変更する責務
- 所有する状態と副作用: 変更がある場合のみ
- 依存関係: 依存先、呼び出し元、委譲する責務、依存方向
現在と変更後の差分が分かる表現にする。責務を別レゴへ移す場合は、移動元の削除と移動先の追加を両方に記載する。
4. Interface Changes
変更される公開 interface を種類ごとにまとめる。
- HTTP / RPC / GraphQL API
- CLI command と option
- 公開関数、method、class、component props
- library export、plugin interface
各 interface について、追加、削除、変更、変更なし、互換性を明記する。request / response の例が必要な場合もコードブロックは使わず、field 名、型、必須性、意味を自然言語または表で示す。
5. Data / Contract Changes
次の contract の追加、削除、変更、変更なしを整理する。
- Request / Response Payload
- DTO / Value Object / Entity
- Database schema / persistence format
- Event / Message
- 設定形式、file format、serialization format
変更する field ごとに名称、型、必須性、意味、default、制約、互換性を必要な範囲で示す。contract の producer と consumer も明記する。
6. Dependency Changes
変更前と変更後の依存方向を自然言語またはテキスト図で示す。新規依存、削除する依存、責務の委譲先、外部 I/O 境界を明記する。
循環依存を作らず、上位レゴが下位レゴの内部実装へ依存しない構造になっているか確認する。
7. Impact
変更による直接影響と波及影響を列挙する。
- API と利用者
- Database と既存データ
- Tests
- Frontend / Backend / CLI
- 他モジュール、外部サービス、運用
- observability、security、performance（関係する場合）
影響なしと判断した領域は、根拠を短く添える。
8. Risks
設計に起因するリスクと、そのリスクが成立する条件を列挙する。
- 後方互換性と段階移行
- contract の不整合
- data migration と rollback
- performance と可用性
- security と権限境界
- 循環依存、責務漏れ、二重管理
- 未解決事項や仮定が外れた場合の影響
一般論を並べず、今回の変更対象と結びつけて記述する。
出力制約
- コード、擬似コード、diff、具体的な実装手順を書かない。
- タスクの順番、工数、担当者、Definition of Done を書かない。
- 自然言語を中心にし、構造整理に必要な箇条書き、表、テキスト図だけを使う。
- 未確認の現状や存在しない名称を事実として書かない。
- 変更対象ごとに責務と依存関係を分けて記述する。
- contract の変更有無を必ず明記する。
- 実装開始前に設計レビューで承認または修正判断ができる具体性を持たせる。
完了前チェック
- 変更概要から変更理由と変更後の状態を説明できる。
- 変更対象がファイル列挙ではなく、責務を持つレゴとして整理されている。
- 各レゴの追加、削除、変更する責務と依存方向が分かる。
- interface と data contract の変更有無、互換性、producer / consumer が明記されている。
- 責務移動の移動元と移動先が対応している。
- 影響と risk が具体的な変更対象に結びついている。
- 実装手順やコードが混入していない。
