コードベース収束 (Codebase Convergence) は何をしますか？
リポジトリを再設計することなく、理解しやすく変更しやすくします。推測による抽象化よりも、証拠、小さなインターフェース、局所的な修正を優先します。
ガードレール
- マルチステップの変更を行う前に、スコープ、前提条件、保護対象コンテンツ、成功条件を明示します。
- アーキテクチャを判断する前に、リポジトリの説明書、ドメイン用語集、関連するADRを読みます。リポジトリのドメイン名を使用します。
- リクエストに役立つファイルのみに触れます。無関係なユーザー変更は保持し、この作業によって不要になったインポート、コード、ドキュメントのみを削除します。
- 明示的に保護されたドメインテキスト、タイトル、データ定義、ユーザー指定のコピーはロックされたものとして扱います。そのまま維持します。ステータスが不明な場合は、編集する代わりに判断パケットに含めます。
- 明示的な承認なしに、数値またはその表現（設定、しきい値、バランス、レート、制限、または文書化された値）を変更しないでください。
- 明示的に承認なしに、ビジネスルール、状態遷移、インタラクション動作、パブリックインターフェース、またはビジュアルコントラクトを黙って変更しないでください。修正が直接的に暗示され、動作を保持するものでない限り、判断を要するものとして扱います。
- 各事実について、単一の情報源を維持します。別のドキュメントを単に繰り返すだけのドキュメントを作成しないでください。
ワークフロー
1. ベースラインの確立
- ワークツリーを検査し、要求された領域のみを特定します。無関係な変更に注意してください。ステージングしたり、変更したりしないでください。
- 関連するコードパス、状態/データの所有権、UIフロー、テスト、Markdownファイルをマッピングします。ドメインと判断を定義しているドキュメントを、それらを実装するファイルよりも先に読みます。
- 各発見事項を証拠とともに記録します。ファイル、矛盾する記述やパス、ユーザーへの影響、直接解決しても安全かどうか。
- 発見事項を分類します:
- 直接収束: 重複、古いリンク、矛盾するロックされていない散文、または動作を保持する修正が可能な局所的な実装/UIの欠陥。
- 判断が必要: あらゆる数値、ルール、動作、保護コンテンツ、パブリックインターフェース、またはあいまいな情報源。
- アーキテクチャ候補: より深いモジュール、またはシーム（変更箇所）がまだ合意されていない変更。
2. 重要な判断を一度に依頼する
質問する前に発見を完了させます。未解決のすべての項目を含む1つの判断パケットを送信します。ターンをまたいで質問を小出しにしないでください。
数値項目ごとに、その識別子とファイル、現在の値、矛盾の証拠、影響、および推奨事項を含めるか、値が提案されていないことを明確に述べます。ユーザーが明示的に承認するまで、影響を受ける数値表現を編集、正規化、移動、または削除しないでください。
同じパケットに他の重要な不確実性（ロックされたコンテンツのステータス、動作の選択、所有権の競合、アーキテクチャの選択）を含めます。承認を待っている間も、独立した直接収束を続けます。
3. 直接収束の適用
各変更は外科的で、発見事項にトレース可能なものにします。
ドキュメント
- 各ドキュメントに1つの責任を与えます。既存の規則を尊重します。それ以外の場合は、最小限のセット（エントリーポイントの概要、アーキテクチャ/システムマップ、ドメインまたは製品ルール、判断、現在の作業/ステータス）を維持します。
- 重複するPRD、計画、作業ログは、信頼できるコンテンツを1回保持することでマージします。耐久性のある根拠はプロジェクトの判断記録に移動し、運用ステータスは簡潔に保ちます。
- ロックされたブロックを移動する際は、そのまま維持します。マージによってロックされたブロックや数値表現が変更される場合は、その塊を承認のために残します。
- 繰り返し、古い参照、矛盾するロックされていない説明を削除します。移動後にリンクを更新し、仕様を複製するサマリードキュメントは避けます。
コードとUI
- UIコードを編集する前に、状態の所有権を通じてユーザーアクションをレンダリング結果までトレースします。
- 具体的な不整合を修正します。重複したプレゼンテーション状態、イベント/データ名の不一致、無効な条件フロー、この変更によって作成されたデッドコード、または局所的な修正を妨げるコンポーネント責任。
- ユーザーが製品またはビジュアルの変更を承認しない限り、レイアウト、インタラクション、アクセシビリティ、レスポンシブ動作を安定させます。
- 状態遷移の明確な所有者を1つ、データの正規表現を1つ優先します。実証された必要性なしに、抽象化、設定、またはエラーハンドリングを導入しないでください。
4. アーキテクチャ候補を個別に評価する
これらの用語を一貫して使用します:
- モジュール: インターフェースと実装を持つユニット。
- インターフェース: 呼び出し元が知っておくべきすべて。不変条件とエラーモードを含みます。
- シーム: 呼び出し元を編集せずに動作を変更できる場所。
- 深さ: 小さなインターフェースの背後にある実質的な振る舞いからのレバレッジ。局所性: 関連する知識と変更が一緒に留まること。
削除テストを適用します。モジュールを削除しても複雑さが呼び出し元に移動するだけなら、存在価値があります。複雑さが消えるなら、おそらく浅いです。1つのアダプターだけのためのシームを作成しないでください。
インターフェース、動作、または所有権を変更する候補については、すぐに実装しないでください。ビジュアル比較が役立つ場合にのみ、OSの一時ディレクトリに簡潔で自己完結型のHTMLレポートを作成します。ファイル、証拠、変更前/変更後の図、期待される局所性とレバレッジ、ADRの競合（ある場合）、推奨強度を含めます。インターフェースを設計する前に、ユーザーに候補を選択するよう依頼します。
5. 検証と引き継ぎ
- 最終的な差分を、スコープ、保護コンテンツの保持、重複した情報源、意図しない値や動作の変更について検査します。
- 関連する既存のフォーマッター、lint、型チェック、テスト、ビルド、UI検証を実行します。このタスクのみのためにツールや広範なテストスイートを追加しないでください。既存の失敗と導入された失敗を区別します。
- 統合後にMarkdownのリンクと見出しを確認し、変更された各ステートメントをその正規ソースに対して検証します。
- 直接の変更、未解決の判断項目、検証結果、リスクを簡潔に報告します。変更された各行は、要求された収束にトレース可能でなければなりません。