Untangle（整理）
からまったコードベースは、誰も決断しなかった決定の山です。AIは次のプロンプトが求めるものを何でも書き、決して拒否せず、再考を提案しなかったため、リポジトリには各機能を実現する3つの方法と、その理由の記録がありません。整理するということは、それらの決定をそれぞれ一度だけ行い、それを文書化し、コードとそのチェックがそれと一致するようにすることを意味します。
あなたがマッピング、証拠収集、編集を行います。人間が決定を下します。
目標状態
以下の5つすべてが満たされた時点で作業は完了です。
- 各機能に対して一つの方法：認証、データアクセス、エラー、設定、ロギング。
- テストは、振る舞いが間違っている場合に失敗する。
- 残ったすべてのコードには、誰かが説明できる理由がある。
- 決定事項は、次の人やエージェントが読む場所に文書化されている。
- 自動チェックにより、からまりの再発を防ぐ。
コードベースがすでにこれらを満たしている場合は、その旨を伝えて停止します。作業をでっち上げることは監査の失敗です。
全フェーズ共通のルール
- 台帳が状態です。 リポジトリルートの
UNTANGLE.mdに、カバレッジ、発見事項、決定事項、進捗が記録されます。まずそれを読み、自分のターンが終わる前に更新します。長いクリーンアップはコンテキストウィンドウを超えて存続します。台帳が引き継ぐものです。台帳が存在する場合は、再監査する代わりにそこから再開します。 - 証拠がないものは発見事項ではありません。 各発見事項には
file:lineと、それを示すコマンドまたは観測結果が含まれます。「臭いがする」は発見事項ではありません。 - あなたが提案し、人間が決定します。 承認された台帳の行がなければ、何も削除、マージ、または勝者として宣言されません。すべての決定に対してデフォルトを推奨し、承認を容易にします。
- 構造変更と振る舞い変更は別々のコミットにします。 バグ修正も同時に行うリファクタリングは、どちらの検証もできません。
- 実行したことのみ報告します。 実際の結果とともにコマンドを記録します。詳細に読んだもの、マッピングのみ行ったもの、一度も開かなかったものを記録します。
- 減らします。 書き換えなし、新しい依存関係なし、新しい抽象化レイヤーなし、互換性シムなし。コード行数は減るべきです。
- シークレット。 有効な認証情報を見つけたら、停止し、人間にローテーションするよう伝えます。その値を絶対に出力しないでください。自分で履歴を書き換えないでください。
フェーズ
監査 → トリアージ → リファクタリング → 持続可能性、この順序で行います。台帳がない場合は監査から開始します。台帳がある場合は、台帳に記録されたフェーズから続行します。フェーズ名またはパスを指定する引数は作業を絞り込みますが、監査をスキップすることはありません。リファクタリングは承認された発見事項にのみ作用するためです。
1. 監査：読み取り専用
UNTANGLE.md以外は変更しません。templates.mdのテンプレートから開始します。
- ベースライン。 実際のインストール、ビルド、テスト、リンター、型チェックのコマンドを見つけて実行します。結果をそのまま記録します。READMEからビルドできないリポジトリは発見事項その1です。
- 読む前にマッピング。 ファイル一覧、サイズ、エントリポイント、インポートの方向、git履歴からの変更頻度。次に、どこを詳細に読むかを選択します。リスクの高い順に、認証、金融、データ書き込み、インフラとします。パスごとのカバレッジを記録します。
- 探索 は
catalog.mdを使用して行います。分析ツールは一時的に実行します（npx、uvx、go run）。プロジェクトの依存関係を変更しないようにします。 - テストをテストします。 3つのビジネスルールを選びます。それぞれについて、ルールを変更してエラーを出さずに間違った答えを返すようにし、スイートを実行し、
git restoreでファイルを復元し、git statusがクリーンであることを確認します。いずれかのテストが気づいたかを記録します。 - スコアカード を
templates.mdを使用してスコアリングします。各チェックは、合格、不合格、または「リポジトリから検証不可」（人間が答えなければならない質問付き）です。 - 報告して停止します。 リスクの高い順に上位の発見事項、問題のないもの、カバーされなかったものを報告します。
2. トリアージ：決定
- 修正を一つずつリストアップする前に、複数の発見事項を解決できる単一の決定を探します。要件が最初からわかっていた場合、このコードはどのように見えるかを尋ねます。
- 競合する実装がある懸念事項ごとに、勝者を推薦し、その理由を述べます：最も多くの呼び出しサイト、最もテストされている、フレームワークの慣例に一致する。
- 各発見事項を「保持」、「修正」、または「削除」にマークします。リスク（危害の可能性 × それに依存する度合い）でランク付けします。
- スライスを順序付けます。まずセーフティネット、次に削除（安価で、それ以降のすべてを縮小する）、次に統合、最後に再構築です。
- 1つのテーブルを提示し、1回のパスで承認を得て、承認が得られるまで停止します。拒否されたものは、理由とともに
wontfixとして記録します。
3. リファクタリング：一度に1スライス
untangle/<トピック>という名前のブランチで作業します。決してプッシュしません。承認された各スライスについて：
- ネット。 テストはこのスライスが触れる振る舞いをカバーし、意図的な破損でテストが失敗するのを確認済みです。カバーされていない場合は、まず特性テストを作成します：今日のコードが行うことを（バグも含めて）固定します。各バグは、黙って修正する代わりに新しい発見事項として記録します。
- 変更 は1つの関心事に対してのみ行います。
- 確認 は完全なベースラインコマンドを使用して行います。赤になった場合は、変更を修正するかスライスを元に戻します。
- コミット は発見事項IDを含めて行い、台帳を更新し、尋ねることなく次のスライスに進みます。
スライスに台帳に含まれていない決定が必要な場合は、停止して尋ねます。
「デッド」とは、静的ツールの判定と、文字列ルックアップ、リフレクション、ルート、DI名、設定、cron、テンプレート、公開API、リポジトリ外部の呼び出し元を介した動的な到達可能性の検索の両方によって、到達不能であることが証明されたものを意味します。証明されていないものはsuspect（疑わしい）とマークされ、人間に回されます。
4. 持続可能性：定着させる
- 各決定について、機械がそれを強制できるかどうかを尋ねます。できる場合は、リントルール、インポート境界、CIステップ、またはテストを追加します。散文ルールは、機械がチェックできないもののためのものです。
- 決定事項から
AGENTS.mdを作成します：コマンド、関心事ごとの一つの方法とサンプルファイルへのポインタ、新しいコードを置く場所。すべてのセッションで読まれるように十分短く保ちます。CLAUDE.md、.cursorrules、または類似のファイルが存在する場合は、1つをソースにし、残りはそれを参照するようにします。 - 勝者を選んだ各決定に対してADR（アーキテクチャ決定記録）を作成します。
- READMEのクリーンチェックアウトからのセットアップが真であることを確認し、envテンプレートをコミットします。
- CIはベースラインコマンドを実行し、赤の場合は失敗します。ブランチ保護とアラートルーティングはリポジトリ外にあるため、それらを人間のためにリストアップします。
- 再スコアリングを行い、前後の状態を記録し、未完了の項目を台帳にリストします。
誘惑にかられたとき
| 考え | 代わりにすること |
|---|---|
| 「ついでにこれも直しておこう」 | 発見事項を追加します。承認されていない変更が、からまりを作ったのです。 |
| 「テストが古いから、アサーションを調整しよう」 | 構造変更後の赤いテストは、変更が振る舞いを変えたことを意味します。変更を修正するか、元に戻します。 |
| 「これを参照しているものはない、デッドだ」 | 動的な到達可能性に対して証明するか、suspectとマークします。 |
| 「ラッパーを使えば古い呼び出し元はそのまま動く」 | 呼び出し元を更新します。シムは新しい名前の付いた余剰品です。 |
| 「これは書き直すべきだ」 | スライス。書き直しは、テストがカバーしていないすべての振る舞いを破棄します。 |
| 「コードベースはカバーした」 | カバレッジとは、台帳があなたが読んだと述べているものです。 |
| 「コンテキストが長くなってきた、早く終わらせよう」 | 台帳を書き、残っていることを述べ、停止します。 |
| 「スイートが通ったから、動作する」 | 合格が証明するのは、監査ステップ4が示したテストが捕捉できるものだけです。 |