AIコーディングエージェントの不要コード残留を防ぐクリーンアップ・スキル

目的

AIコーディングエージェントが実装・修正・デバッグを行う過程で作成した、最終成果に不要なコード、ファイル、設定、依存関係、ログ、コメント、分岐、互換処理を残さないようにする。

単に動作する状態で終了せず、最終要件を満たす最小かつ説明可能な変更だけが残った状態を完了条件とする。

適用場面

• 新機能の実装
• バグ修正
• リファクタリング
• ライブラリ移行
• 複数案を試した後の実装
• 一時的なデバッグコードを追加した作業
• AIエージェントが複数ファイルを変更した作業
• テストを通すために例外処理や回避策を追加した作業

基本原則

1. 試行過程と最終成果を分離する

   • 調査用コード、仮実装、比較案、デバッグ出力は作業途中の資産であり、最終成果ではない。

2. 追加したものは必ず使用箇所を確認する

   • 変数、関数、クラス、ファイル、依存関係、環境変数、設定値を追加した場合、最終的に参照されているか確認する。

3. 古い実装を残したまま新実装を追加しない

   • 新旧両方を保持する明確な要件がない限り、置き換え対象は削除する。

4. 「念のため残す」を禁止する

   • 将来使うかもしれないコードは、現在の要件に必要でなければ残さない。必要になった時点で履歴から復元する。

5. 差分全体を成果物としてレビューする

   • 正しく動く箇所だけでなく、変更差分に不要物が含まれていないことを確認する。

実行手順

1. 最終要件を一文で固定する

作業完了前に、今回残すべき成果を一文で定義する。

例:

APIレスポンスの形式を変更し、既存テストと新規テストが通る状態にする。

この一文に直接寄与しない変更は削除候補とする。

2. 変更一覧を取得する

可能な範囲で以下を確認する。

git status --short
git diff --stat
git diff

ステージ済み変更がある場合は以下も確認する。

git diff --cached

新規ファイル、削除ファイル、変更ファイルをすべて把握する。

3. 不要物候補を機械的に探索する

以下を重点的に探す。

デバッグ用途

• print
• console.log
• debugger
• pdb
• 一時的なログ出力
• 固定値による強制分岐
• コメントアウトされた旧コード
• TODO: temporary
• FIXME

未使用要素

• 未使用import
• 未使用変数
• 未使用関数
• 未使用クラス
• 参照されない設定値
• 読み込まれない環境変数
• 呼び出されないAPI
• 利用されないコンポーネント

試行の残骸

• tmp、test2、new、old、backupなどの仮名ファイル
• 同じ目的を持つ複数実装
• 旧方式との不要な互換処理
• 実験用スクリプト
• 一時データ
• 生成されたログ
• 手動確認用のHTMLやJSON

不要な依存関係

• 最終コードから使われていない追加パッケージ
• 不要になったimport
• 使用されないDockerサービス
• 不要なCIステップ
• 不要な環境変数

検索例:

rg "console\.log|print\(|debugger|pdb|TODO|FIXME|temporary|tmp|backup|old|test2"

利用可能な場合は、言語ごとのlint、型検査、未使用コード検査を実行する。

4. 各変更を4分類する

変更した各要素を次のいずれかに分類する。

• 必須: 最終要件に直接必要
• 補助: 必須コードのテスト、型、安全性、可読性に必要
• 偶発: フォーマッタや自動生成による無関係な変更
• 残骸: 試行、デバッグ、旧実装、不要な回避策

残すのは原則として「必須」と「補助」だけとする。

「偶発」と「残骸」は削除または差し戻す。

5. 新旧実装の重複を解消する

新しい実装を追加した場合、旧実装について次を確認する。

• 呼び出し元が残っていないか
• 古い関数やクラスが残っていないか
• 古い設定値が残っていないか
• 古いテストが誤った仕様を固定していないか
• 旧APIとの互換処理が本当に必要か

互換性が要件として明示されていない場合、旧実装を削除する。

6. 回避策を再評価する

作業中に追加した以下の処理は特に疑う。

• 広すぎる例外処理
• 失敗を握りつぶす処理
• 不要なリトライ
• 固定sleep
• 強制的なデフォルト値
• 条件分岐によるテスト専用挙動
• 型チェックの無効化
• lint無効化コメント
• セキュリティ検査の除外

各回避策について、次を説明できない場合は削除する。

1. どの具体的な失敗を防ぐのか
2. なぜ根本修正ではなく回避策が必要なのか
3. どのテストで必要性を確認できるのか

7. テストと静的検査を実行する

プロジェクトに応じて以下を実行する。

# Python例
pytest
ruff check .
mypy .

# JavaScript / TypeScript例
npm test
npm run lint
npm run typecheck
npm run build

すべてを実行できない場合は、実行できなかった項目と理由を明示する。

8. 削除後に再度差分を確認する

git status --short
git diff --stat
git diff

次の観点で最終確認する。

• 変更ファイル数は妥当か
• 新規ファイルはすべて必要か
• 無関係な整形変更が混ざっていないか
• 一時コードが残っていないか
• 旧実装と新実装が併存していないか
• 依存関係の追加は本当に必要か
• コメントが過程ではなく現在の仕様を説明しているか

完了判定

以下をすべて満たした場合のみ作業完了とする。

• 最終要件を満たしている
• 関連テストが通る
• ビルドまたは型検査が通る
• 未使用コードがない
• デバッグ出力がない
• コメントアウトされた旧コードがない
• 仮ファイルや一時データがない
• 不要な依存関係がない
• 旧実装が不要に残っていない
• 差分内のすべての変更理由を説明できる

エージェントへの禁止事項

• 動作した時点で即終了しない
• テスト通過だけを完了条件にしない
• 失敗した実装案をコメントアウトして残さない
• 使っていないファイルを将来用として残さない
• 無関係なファイルをまとめて整形しない
• エラーを握りつぶしてテストだけ通さない
• 削除が怖いという理由だけで旧コードを残さない
• ユーザーの許可なく広範囲なリファクタリングを混ぜない

最終報告形式

作業終了時は、次の形式で簡潔に報告する。

## 実装結果
- 実装した内容:
- 変更した主要ファイル:

## クリーンアップ
- 削除した不要コード・ファイル:
- 削除した依存関係・設定:
- 残した互換処理と理由:

## 検証
- 実行したテスト:
- lint / 型検査 / build:
- 未実行項目と理由:

## 最終差分
- 最終要件に直接必要な変更のみであることを確認済み

判断基準

迷った場合は、次の問いを使う。

この行、ファイル、依存関係、設定が存在しなければ、現在の要件または検証は失敗するか？

「失敗しない」のであれば、原則として削除する。