背景 / Why
Uzabase Agile Journeyの記事「リファクタリングは、なぜ必要なのか？」では、リファクタリングを単なるコード整理ではなく、開発で更新されたチームの理解と、コードが表現する過去の理解との差分を同期する活動として捉えている。
参考:
AI駆動開発では実装速度が上がる一方、以下の問題が拡大しやすい。
- 新しく得た要求・ドメイン知識が、名前・責務・境界へ反映されない
- 振る舞い変更と構造変更が同一タスク・同一diffへ混在する
- AIが将来予測に基づく過剰な抽象化を追加する
- テストが十分でない状態で広範囲なリファクタリングを始める
- 「なぜ構造を変えたか」がPlan、PR、Trust Ledgerに残らない
PlanGateは、実装前に目的・制約・検証方法を確定し、実行と完了判定をゲートする仕組みである。そのため、リファクタリングを独立した美化作業ではなく、Knowledge Deltaを検出し、安全にコードへ反映する計画・実行パターンとして組み込む価値がある。
目的 / What
PlanGateのPlan作成、タスク分割、セルフレビュー、完了ゲートに以下を導入する。
- 今回新しく得た知識と、既存コードが表現する理解との差分を明示する
- 振る舞い変更と構造変更を分離して計画する
- 必要に応じてCharacterization Test / Preparatory Refactoringを先行する
- 現在の要求に不要な投機的抽象化を検出する
- 構造変更前後で振る舞いが維持されたことを検証する
- 変更理由と検証結果をTrust Ledgerへ残す
提案する設計
1. Planに Knowledge Delta セクションを追加
## Knowledge Delta
### Newly learned
- 今回の要求、調査、実装、テスト、運用から新しく分かったこと
### Existing representation
- 現在のコードが表現している名前・責務・境界・前提
### Delta
- 現在の理解とコード表現の不一致
### Required structural response
- 差分を解消するために必要な構造変更
- 今回は変更しない範囲と理由
適用条件は全タスク必須ではなく、以下に該当する場合に要求する。
- 既存コードの責務・境界・命名を変更する
- ドメインルールの理解が更新された
- 変更前の構造が新しい要件を不自然にしている
- リファクタリングを含む、または含む可能性が高い
2. タスク分割パターンを追加
必要に応じて以下の順序へ分解する。
A. Characterization / Safety Net
B. Preparatory Refactoring
C. Behavior Change
D. Post-change Refactoring
E. Independent Verification
原則:
- テストがRedの状態で構造変更を進めない
- 振る舞い変更と構造変更を可能な限り別コミットまたは識別可能な単位へ分ける
- Preparatory Refactoringは後続変更を安全・単純にする最小範囲に限定する
- 広範囲な負債解消は通常タスクへ隠さず、別Issue/Epic候補として報告する
3. Planレビューに過剰設計チェックを追加
- [ ] この抽象化は現在の要求・複数の実例から必要と判断できる
- [ ] 将来予測だけを根拠にした汎用化ではない
- [ ] 後から安全に変更可能な箇所を先回りして複雑化していない
- [ ] 今回触る必要のない範囲まで変更していない
- [ ] 新しい名前・責務・境界がKnowledge Deltaを正しく表現する
4. 完了ゲートにBehavior Preservationを追加
構造変更を含む場合、完了判定で以下を確認する。
- 既存テストと追加テストが通る
- 型チェック・静的解析が通る
- 外部API、永続化形式、イベント、CLI、公開インターフェースの互換性が維持される
- 振る舞い変更がある場合は、構造変更と区別して説明されている
- rollback可能、または不可逆性がPlanで承認されている
5. Trust Ledgerへ記録項目を追加
knowledge_delta:
previous_understanding: ""
new_understanding: ""
source: []
refactoring:
included: false
behavior_change_separated: true
structural_changes: []
verification: []
rollback_available: true
decision:
reason: ""
speculative_abstraction_added: false
既存スキーマとの重複を確認し、必要最小限のフィールドへ統合する。
想定する組み込み箇所
/spec、Plan作成テンプレート、または同等のIntake/Planフロー- C-1セルフレビュー
- C-4前後の実行前・PR前セルフレビュー
- verifier / gate の完了判定
- Trust Ledgerの記録スキーマ
- ドキュメント、サンプルPlan、テストfixture
具体的な名称・ステージ番号は、現行リポジトリ構造を確認して調整する。
受け入れ条件 / Acceptance Criteria
検証シナリオ
Case 1: 小さな機能追加
- 新しい知識差分がない
- Knowledge Deltaは簡潔または省略可能
- 通常フローの負荷を増やさない
Case 2: ドメイン理解が更新された既存機能変更
- 古い名前・責務・境界を特定
- Safety Net → Preparatory Refactoring → Behavior Changeへ分割
- 完了ゲートで外部挙動維持を確認
Case 3: 通常タスクに収まらない構造的負債
- 変更範囲・リスク・不足テストを検出
- 現タスクへ隠して実施せず、別Issue/Epic候補として出力
非目標 / Non-goals
- すべてのタスクでリファクタリングを必須にすること
- コードスメルを網羅的に自動修正すること
- 将来利用を想定した抽象化を一律禁止すること
- テストがない状態でAIに大規模変更を許可すること
- River Reviewの詳細なdiffレビュー観点をPlanGate側へ重複実装すること
River Reviewとの責務分担
- PlanGate: Knowledge Deltaの明示、変更順序、Safety Net、実行条件、完了ゲート
- River Review: 実際のdiffがKnowledge Deltaを適切に表現し、振る舞い維持・単純性・変更範囲を満たすかのレビュー
両者で用語と判定形式は揃えるが、同じチェックを二重実装しない。
背景 / Why
Uzabase Agile Journeyの記事「リファクタリングは、なぜ必要なのか？」では、リファクタリングを単なるコード整理ではなく、開発で更新されたチームの理解と、コードが表現する過去の理解との差分を同期する活動として捉えている。
参考:
AI駆動開発では実装速度が上がる一方、以下の問題が拡大しやすい。
PlanGateは、実装前に目的・制約・検証方法を確定し、実行と完了判定をゲートする仕組みである。そのため、リファクタリングを独立した美化作業ではなく、Knowledge Deltaを検出し、安全にコードへ反映する計画・実行パターンとして組み込む価値がある。
目的 / What
PlanGateのPlan作成、タスク分割、セルフレビュー、完了ゲートに以下を導入する。
提案する設計
1. Planに
Knowledge Deltaセクションを追加適用条件は全タスク必須ではなく、以下に該当する場合に要求する。
2. タスク分割パターンを追加
必要に応じて以下の順序へ分解する。
原則:
3. Planレビューに過剰設計チェックを追加
4. 完了ゲートにBehavior Preservationを追加
構造変更を含む場合、完了判定で以下を確認する。
5. Trust Ledgerへ記録項目を追加
既存スキーマとの重複を確認し、必要最小限のフィールドへ統合する。
想定する組み込み箇所
/spec、Plan作成テンプレート、または同等のIntake/Planフロー具体的な名称・ステージ番号は、現行リポジトリ構造を確認して調整する。
受け入れ条件 / Acceptance Criteria
検証シナリオ
Case 1: 小さな機能追加
Case 2: ドメイン理解が更新された既存機能変更
Case 3: 通常タスクに収まらない構造的負債
非目標 / Non-goals
River Reviewとの責務分担
両者で用語と判定形式は揃えるが、同じチェックを二重実装しない。