tt-a1i/simplify-codebase

コードベースの簡素化 – 安全なコードベースのクリーンアップのためのAIエージェントスキル

何であるか

• AIコーディングエージェント（例：Codex、OpenAIベースのボット）向けの スキル（プラグイン）であり、既存のリポジトリを監査し、コードの削除が安全であることを証明し、削除を適用する際に完全な証拠記録を保持する機能を提供します。
• 一般的なリンターまたは不要コード削除ツールではありません。誤って生じた複雑さ（例：古くなったAPI、孤立した状態、重複した抽象化、互換性用のシャイム）に焦点を当てており、保守コストが削減効果を上回る場合にのみ削除を行います。

動作方法

モード	範囲	機能
調査（読み取り専用）	限定的 – 単一のサブシステム、または 広範囲 – 全リポジトリ	ファイル、実行時登録、データフォーマット、外部コンシューマーをスキャンし、証拠記録付きの「簡素化候補」のランク付きリストを生成します。
変更（承認済み編集）	同じ範囲	候補が安全であることが証明された後、削除を実行し、最小限の検証スイートを実行し、ロールバック計画を出力します。

各候補には 証拠記録 が付随し、以下の内容をリストアップします：

• 所有権境界、ファイルおよび行番号
• 保守負担の程度
• どの（テスト、実行時、外部サービス）が利用しているか
• 削除の正確な境界（共有ファイルメンバーも含む）
• 消失する互換性または観察可能な振る舞い
• 不正な削除を検出する最小限のテスト
• 移行コストに対するネット複雑性の削減量

主要なセーフティ機構

• 公開API、プラグイン登録、データ移行パス、並行処理プリミティブ、または依然として検証済みのコンシューマーを持つアーティファクトには一切手を出しません。
• 実際のコンシューマーが特定できない場合、推測ではなくコードの保持を推奨します。

インストール

# Codex互換エージェント向けに推奨
git clone https://github.com/tt-a1i/simplify-codebase.git ~/.codex/skills/simplify-codebase

• SKILL.md メタデータを尊重する任意のエージェントプラットフォームでもロード可能です。
• 軽量なHTMLレンダラー（Node ≥ 18、追加npmパッケージ不要）をバンドルしており、オプションの視覚的レポートが可能。

一般的な使用パターン

# 1️⃣ リポジトリ全体を監査、変更なし
$simplify-codebase audit --scope broad --dry-run

# 2️⃣ 特定のフラグや状態を調査
$simplify-codebase survey --focus readiness-flags

# 3️⃣ 証明された簡素化を適用
$simplify-codebase change --candidate 42 --apply

# 4️⃣ PRからの調査結果を統合
$simplify-codebase integrate --pr 123

# 5️⃣ インタラクティブなクリーンアップマップ（HTML）を生成
$simplify-codebase report --visual

• コマンドはデフォルトでテキスト形式の証拠レポートを返します。--visual を追加すると、検証済みのコンポーネントとその関係を表示する自己完結型のHTMLマップが生成されます。

出力内容

• 調査レポート – カバレッジの説明、ランク付き証拠記録、反例、未解決の質問、次に必要な証拠
• 変更レポート – 実際のファイル差分、階層的な検証結果、残存リスク評価、操作受領証、元に戻せる「元に戻す」スクリプト
• オプションの視覚的レポート – バンドルされた Archify レンダラーで構築されたインタラクティブなデスクトップ対応HTMLページ。検証済みの結果のみを表示し、推測された実行時影響は一切表示しません。

成熟度

• 973ファイルの混合Python/TypeScriptプロジェクト（変更、広範囲、統合、決定記録のシナリオをカバー）で検証済み。
• テストスイートと契約ファイルは visualization/test/ および docs/validation.md に配置。

貢献について

• 問題報告やPRを歓迎します。特に、見逃されたコンシューマー、誤検出の削除、検証フローのギャップに関するもの。

ライセンス

• MIT（LICENSE を参照）。

---

Simplify Codebase は、大規模なレガシーコードベースに形式的で証拠に基づく削除をもたらす専門的なAIエージェント拡張であり、チームが長期的な保守負荷を削減しつつ、隠れた破綻のリスクを回避できるように支援します。