simplify-codebase

コードベースをシンプルにする

コードベースで一貫性を保つ必要のある概念や義務を減らします。行数の削減は裏付けとなる証拠であり、目的ではありません。調査した範囲がすでに妥当だと結論づけることも、適切な結果です。

モードと対象範囲を選択する

まず、権限モードを選択します。

• 調査：シンプル化の監査、調査、候補の特定を求められた場合に選択します。読み取り専用を維持し、根拠を順位付けして提示します。
• 変更：明示的にシンプル化、削除、統合、リファクタリング、またはリポジトリのドキュメント編集を求められた場合に選択します。変更を一つずつ根拠づけ、許可された範囲内で実施し、維持される契約を検証します。

次に、調査範囲を選択します。

• 限定的：ユーザーがサブシステム、シンボル、状態機械、依存関係、または重複の疑いを指定した場合に選択します。範囲を外に広げる前に、その境界を徹底的に調査します。
• 広範：リポジトリ全体にわたる依頼、または複数の候補を求められた場合に選択します。システムを区分し、対象となるすべての領域を網羅します。

到達可能な機能、サポート対象のインターフェース、保存形式、または互換性維持のための経路を削除することは、製品上の判断です。その影響を説明し、ユーザーがすでに選択している場合を除いて、方針の指示を得てください。

契約を把握する

1. リポジトリの指示、アーキテクチャと意思決定の記録、マニフェスト、テストガイダンス、生成ファイルの規約を確認します。
2. バージョン管理の状態を調べ、無関係な作業を保持します。分類を始める前に、ベンダー提供、生成、マイグレーション、フィクスチャ、公開パッケージに関わる範囲を特定します。
3. エントリーポイントから設定、登録、ディスパッチ、永続化、プロセス、ワイヤー境界まで、実行時の経路をたどります。公開、動的、永続化、生成、および互換性に影響する契約を記録します。
4. 変更モードでは、リポジトリで実際に使われている検証コマンドを特定し、可能な場合は規模に応じたベースラインを取得します。ベースラインで失敗がある場合、最終確認で立証できる範囲が限られます。

認可、信頼境界の検証、セキュリティ分離、アクセシビリティの必須要件、データ損失の防止、保存形式の互換性、静止状態を確立するクリーンアップを維持します。これらの保護への変更は、それ自体を明示的に許可された目的として扱い、付随的なシンプル化として行わないでください。

契約マップが完成したと言えるのは、対象範囲内のすべてのエントリーポイントと権限境界を列挙し、それぞれの所有者と観測可能な契約を特定できるところまで追跡し、未調査または外部から把握できない範囲をすべて死角として記録したときです。

関連範囲を網羅する

「広範」な作業すべて、および動的なアーキテクチャや依存関係の置き換えを含む「限定的」な作業では、investigation.md を読んでください。候補を順位付けする前に網羅性マップを作成します。最初に見つかったもっともらしい削除候補だけで調査を終えてはいけません。

並行処理、キャンセル、準備完了状態、クリーンアップ、防御的コピー、検証、認可、セキュリティ分離、アクセシビリティ、データ損失の防止、またはプロセス間データを扱う場合は、boundaries-and-lifecycle.md も読んでください。

リポジトリ固有の検索、コンパイラーやリンターの出力、依存関係のメタデータ、履歴を調査の手がかりとして利用します。実行時の利用箇所と契約を確認するまでは、それらから得た情報を手がかりとして扱ってください。

証明記録を作成する

対象範囲内のリードのうち、利用側マップの証拠に到達したもの、または意味のある契約を解消できる可能性があるものすべてについて、次を記録します。

Finding ID: a stable report-local identifier such as S1 or S2
Candidate: the exact contract, representation, or layer to remove or merge
Locus: the ownership boundary, symbols, and exact paths or lines when verified
Topology: confirmed node and relationship IDs, primary locus, related nodes, route, and cut set when useful; otherwise not applicable
Burden: the concepts, synchronization, publication, or testing cost it creates
Reachability: production, non-production, dynamic, external, and persisted consumers
Rationale: why it exists and whether that reason remains current
Cut: declarations, implementations, branches, artifacts, docs, and dependencies affected
Consequence: observable capability or compatibility behavior surrendered
Confidence / risk: evidence strength, uncertainty, blast radius, and reversibility
Proof: the smallest check that would expose an incorrect cut
Net effect: maintenance concepts removed minus replacement or migration machinery added

実行中は調査 ID を一貫して維持し、サマリー、証明記録、ソースリンク、視覚的な補足資料が同じ候補を参照するようにします。場所の項目を埋めるために、行番号、所有者、関係、経路を捏造しないでください。不明な事実は未解決として記載します。

候補が存続する利用者とアーティファクトを共有している場合は、ファイル単位より細かい粒度で切り分けの境界を証明します。存続する所有者に影響を与えずに、候補専用のセレクター、メンバー、フィールド、キー、レジストリエントリ、生成された断片、フィクスチャをすべて考慮します。

実際の利用者が存在する場合、動的な到達可能性が未解決のままの場合、現在の決定が引き続き設計を所有している場合、変更によって複雑さが移動するだけの場合、結果が対象範囲外であるか意味のある義務を解消しない場合、または利用可能なチェックでは成功と偶発的な破損を区別できない場合は、候補を維持するか、評価を引き下げます。

確信度とメリットは別々に評価します。価値の高い推測が、規模の小さい証明済みの切り分けより優先されることはありません。

すべての該当するリードが、順位付け済み、却下、または未解決のいずれかに分類され、すべての未解決のリードについて判断に必要な事実が明記された時点で、候補の証明は完了です。

判断して実行する

Survey モードでは、順位付けした証拠を報告した時点で終了します。却下の理由から学びが得られる場合、または具体的に不足している事実が明らかになる場合は、重要な却下候補も含めます。

Change モードでは、execution-and-recovery.md を読み、許可された中で最も確実な切り分けを選択します。1つの所有境界がデフォルトのバッチサイズですが、実行回数の上限ではありません。複数の切り分けが明示的に依頼されている場合は、次の境界に着手する前に、各境界を完了して検証します。

ユーザーが簡素化の提案、ローカルなクリーンアップ注釈、または設計記録の統合を依頼した場合、あるいは選択した変更によって ADR、RFC、設計ノート、またはアーキテクチャインベントリが無効になる場合は、decision-records.md を読みます。通常のコード監査を、リポジトリ全体にわたるドキュメント削除に広げないでください。

ユーザーが別のブランチ、プルリクエスト、タスク、またはエージェントの実行結果からの調査結果を統合するよう依頼した場合は、integrating-findings.md を読みます。調査結果の件数ではなく、証拠を保持してください。

視覚的な補足資料は、ユーザーが明示的に依頼するか、提案を承認した場合にのみ生成します。確認済みの関係を示すことで候補が分かりやすくなる場合は、マップで何が明確になるかを説明し、生成前に確認を求めます。承認がない場合は、マップなしでテキストレポートを完成させます。監査を終えるために視覚資料の提供を待たないでください。視覚資料の提供が許可された場合は、visual-reporting.md を読み、同梱のクリーンアップマップレンダラーを使用します。マップは証明記録を補足する任意の資料であり、それ自体は証拠ではありません。ユーザーがリポジトリ内のファイルを依頼していない限り、Survey の成果物を対象リポジトリに書き込まないでください。

結果を提示する

調査では、対象範囲、確度の高い順に並べた根拠記録、却下または未解決の重要度の高い手がかり、それぞれの不確実性を解消するために次に必要な事実を報告します。視覚的な補足資料が依頼または確認されている場合は、その状況とクリーンアップマップのFindingへのディープリンクを分けて報告します。

引き継ぎ内容は、ひと目で確認できるようにします。結果を最初に示し、ユーザーが必要とする根拠記録、意思決定に関わる不確実性、視覚的なリンク、検証だけを記載します。検索プロセスを詳しく述べたり、同じ根拠を複数の見出しで繰り返したり、一般的な助言を追加したり、空のセクションを残したりしないでください。簡潔にしても、必要な根拠のフィールドは省略できません。対象、根拠の確度、影響、限界が保たれる最短の形式で、各フィールドを一度だけ記載してください。

変更の場合は、execution-and-recovery.mdで定義されている検証と運用レシートを完了してください。Before／Cut／After／Verifyのクリーンアップマップで構造上の変更を説明できますが、運用レシートの代わりにはなりません。検証の各レイヤーを分けて報告してください。範囲の狭いチェックが成功しても、より広範なランタイム、デプロイ、ユーザー受け入れが確認されたことにはなりません。