Codebase Primitive Reimplementation

手順

Step 1: スコープと安全境界を確定する

1. 解析対象リポジトリのパス、解析する既存機能または既存モジュール、新しい要求、再実装先モジュールのパス、触ってはいけないパスを確認する。
2. 具体的な解析スコープと実装スコープが得られるまで作業を進めない。ファイルパス、モジュール名、コマンド、パッケージ名で範囲を指定する。「コードベース全体」のような指定は作業スコープとして受け入れない。
3. ファイルを読んだり編集したりする前に、許可された操作を明示する。
4. ファイル削除、依存追加、対象モジュール外の公開API変更、DBスキーマ変更、マイグレーション変更、広範囲リファクタの前には停止して確認する。
5. 作業が長くなる場合は、解析済みファイル、観察された振る舞い、推定要件、実装判断、検証結果を記録するタスク台帳を作成または更新する。

Step 2: 既存の振る舞いを棚卸しする

1. 対象の振る舞いに関係する実装、呼び出し元、テスト、フィクスチャ、型定義、設定、ドキュメント、実行エントリポイントを特定する。
2. コメントや記憶よりも、コード、テスト、スキーマ、ログ、コマンド出力から得られる直接証拠を優先する。
3. 発見事項を次の3種類に分ける。
   • 観察: コード、テスト、コマンド出力で直接裏づけられる振る舞い。
   • 推定: 利用箇所や制御フローから妥当に導かれる振る舞い。
   • 未確認: ユーザー確認、欠けているデータ、実行環境が必要な振る舞い。
4. 仕様マップが必要な場合は assets/spec-mapping-template.md を読む。
5. 重要な発見事項ごとに、根拠となるファイルパスとシンボルを記録する。

Step 3: プリミティブ能力へ分解する

1. 既存の振る舞いをプリミティブ能力へ分類するために references/primitive-analysis.md を読む。
2. 機能を、解析、検証、認可チェック、状態遷移、データ参照、変換、永続化、副作用、エラーマッピング、表示などの小さなプリミティブへ分割する。
3. 各プリミティブについて、入力、出力、不変条件、失敗モード、副作用、依存、証拠を記録する。
4. 結合が強い振る舞いや曖昧な振る舞いは、推測で補わず 未確認 として扱う。
5. 新しい要求に対して、どのプリミティブが必須、任意、除外、変更対象なのかを特定する。

Step 4: 置き換えモジュールを設計する

1. レガシー構造をコピーするのではなく、選択したプリミティブを中心に新しいモジュールを設計する。
2. 外部から要求される振る舞いだけを、証拠またはユーザー要求に基づいて保持する。
3. 再実装先モジュールの境界を定義する。公開関数やクラス、入力契約、出力契約、エラー挙動、統合点を明確にする。
4. 要求が明示しない限り、無関係な抽象化、フレームワーク接着層、グローバル状態、隠れた副作用、歴史的互換コードを移植しない。
5. 変更が複数ファイルに及ぶ場合は、編集前に短い実装計画を提示する。

Step 5: 外科的に再実装する

1. 承認された対象ファイルと、直接必要なテストファイルだけを編集する。
2. プリミティブを、契約が明確な小さな名前付き単位として実装する。
3. 互換性が必要な場合は、互換シムをコアロジックから分離する。
4. 選択したプリミティブが新要求を満たし、必要な既存振る舞いを保持することを示すテストを追加または更新する。
5. 機能追加、依存追加、抽象化追加、フォーマット一括変更、無関係な整理を行わない。

Step 6: 振る舞いを検証し、対応関係を記録する

1. 変更対象に対して利用可能な最小のテスト、型チェック、lint、ビルドコマンドを実行する。
2. テストコマンドが存在しない場合は、最小限の手動検証計画を作成し、実行されるまでは not run と記録する。
3. 仕様マップ成果物を作成した場合は python scripts/check-spec-map.py <path-to-spec-map> を実行する。
4. 新モジュールをプリミティブマップと比較し、各プリミティブを 実装済み、意図的に変更、除外、blocked、未確認 のいずれかとして記録する。
5. 最終応答前にdiffを確認し、禁止パスや無関係なリファクタが含まれていないことを確認する。
6. 完了したファイル、検証コマンドと出力、残った 未確認 項目、追加確認事項を報告する。

成果物

• スコープと安全境界の要約。
• 観察、推定、未確認 を分けた仕様マップ。
• プリミティブ能力表。
• 置き換えモジュールの実装。
• テストまたは手動検証計画。
• プリミティブと新実装シンボルの対応メモ。

完了条件

• ソースの振る舞いが、証拠付きの観察としてマッピングされている。
• 新しい要求に必要なプリミティブが選択され、その理由が示されている。
• 対象モジュールが承認済みスコープだけを実装している。
• テスト、型チェック、lint、ビルド、または文書化された手動確認が実行済み、または理由付きで not run と明記されている。
• 最終diffに禁止パスや無関係なリファクタが含まれていない。
• 根拠のない仮定がすべて 未確認 として扱われている。

エラー処理

• ソースの振る舞いを特定できない場合は、エントリポイント、呼び出し箇所、ルート、コマンド、UIフロー、またはそれを実行するテストを確認する。
• 変更前からテストが失敗する場合は、ベースライン失敗を記録し、証拠なしに新実装が原因または修正済みだと主張しない。
• 実行環境をインストールできない場合やコマンドを実行できない場合は、該当コマンドを正確に記録し、成果物を blocked として部分作成する。
• ユーザー要求と観察された既存振る舞いが衝突する場合は、衝突を提示し、既存振る舞いを保持するか新要求を優先するか確認する。
• プリミティブマップが大きくなりすぎる場合は、応答には要約を残し、詳細な証拠は別成果物へ保存する。