tech-debt-audit

技術的負債の監査プロトコル

oh-my-openagent（OMO）向けの、モデルに依存しない技術的負債の監査です。OMO に組み込まれたツール（grep、glob、bash と sg、read、lsp_diagnostics、task）を使用します。根拠を示し、引用可能な TECH_DEBT_AUDIT.md 成果物を作成します。

出力

リポジトリのルートにある TECH_DEBT_AUDIT.md に、次の結果を書き出します。

1. エグゼクティブサマリー — 全体的な健全性、最も深刻な項目、すぐに対応できる改善項目の数を3〜5文で記述します
2. メンタルモデル — リポジトリのアーキテクチャを1段落で記述します（何をするのか、技術スタック、モジュールの境界）
3. 指摘事項の表 — 列：ID、カテゴリ、ファイル:行、重大度（Critical/High/Medium/Low）、工数（時間）、説明、推奨事項
4. 優先度トップ5 — 影響度と工数の比率で順位付けします
5. すぐにできる改善のチェックリスト — それぞれ30分未満で対応できる項目
6. 「問題に見えるが問題ではないもの」 — 技術的負債のように見えるものの、意図的に採用されているパターン
7. 未解決の質問 — メンテナーに確認してもらう事項

フェーズ0：状況を把握する

標準（常に実行）

1. glob("**/*.ts") / glob("**/*.py") / など — 言語スタックを把握します
2. glob("**/package.json") + read() — 依存関係とビルドツールを確認します
3. bash("git log --oneline -200") — 変更頻度を調べ、変更の多いファイルを特定します
4. glob("**/*") + 基本的な計算 — 最大のファイルを特定します（300 LOC 超は候補です）
5. 変更頻度が高く、かつサイズの大きいファイルを照合し、負債が集中する領域を特定します
6. 作業コンテキスト内で、メンタルモデルの段落を作成します

フェーズ1：9つの観点で監査する

各観点で OMO ツールを使用します。各観点の中では、ツール呼び出しを並行して実行します。すべての指摘事項に file:line:col を必ず記載してください。

1. アーキテクチャの劣化

標準（常に実行）

• bash("sg -p \"import { $$$ } from '$SRC'\" -l ts .") — モジュールグラフを把握し、循環しているパターンを確認します
• bash("sg -p \"class $NAME { $$$ }\" -l ts .") — 巨大クラスがないか確認します
• grep("TODO|FIXME|HACK|XXX|WORKAROUND|TEMP") — タグ付きの負債マーカーを検索します
• 同期処理に見えるファイルで grep("async|await") を実行します — 不適切な非同期処理の境界を探します
• フェーズ0で見つかった各大規模ファイルに対して bash("wc -l <file>") を実行します

指摘対象

• 500 LOC 超のファイル（巨大ファイル）
• 80 LOC 超の関数、またはネストが4階層を超える関数
• 15個を超えるメソッド、または400 LOCを超えるクラス
• インポートの循環（A → B → A）
• デッドエクスポート：関数／クラスが定義されているものの、ほかの場所から一度もインポートされていないもの（lsp_find_references で確認します）
• コメントアウトされたコードブロック（3行を超えて連続するもの）

2. 一貫性の劣化

標準（常に実行）

• bash("sg -p \"import $CLIENT from '$PKG'\" -l ts .") — 複数の HTTP クライアントがないか確認します
• grep("console.log|console.error|console.warn") — ロガーではなくコンソールを直接使用していないか確認します
• bash("sg -p \"try { $$$ } catch ($$$) { $$$ }\" -l ts .") — エラー処理のパターンを確認します
• grep("as any|@ts-ignore|@ts-expect-error|as unknown") — 型の回避を検索します
• grep("eslint-disable|prettier-ignore") — リント抑制を検索します

指摘対象

• 同じ処理の方法が3種類以上ある（HTTP、ロギング、バリデーション、設定）
• 命名規則の混在（camelCase、snake_case、PascalCase）
• 日付／時刻処理ライブラリの複数使用
• モジュール間でのエラーレスポンス形式の混在

3. 型と契約の負債

標準（常に実行）

• bash("sg -p \"$VALUE as any\" -l ts .") — 実行時の型回避を検索します
• grep("@ts-expect-error") — 抑制されたエラーを検索します
• grep("@ts-ignore") — 抑制されたエラー（レガシー）を検索します
• bash("sg -p \"$NAME: any\" -l ts .") — any として型付けされた箇所を検索します
• lsp_diagnostics(filePath="<src-dir>") — 現在の型エラーを確認します

指摘対象

• 公開 API およびエクスポートされたインターフェースでの any 型
• 型指定のない関数パラメーター
• API／IO 境界でのスキーマ検証の欠如
• ファイルごとにまとめた LSP の型エラー

4. テストの負債

標準（常に実行）

• glob("**/*.test.ts") — すべてのテストファイルを検索します
• bash("bun test 2>&1 | grep -E '(fail|skip|todo)'") — 現在のテストの健全性を確認します
• フェーズ0で変更頻度が高いファイルと、テストの有無を照合します

指摘対象

• 重要な処理経路にある、テストが一切ないファイル
• スキップされたテスト（test.skip、describe.skip）
• 動作ではなく実装の詳細を検証しているテスト
• 遅いテスト（各テストに1秒超）

5. 依存関係と設定の負債

標準（必ず実行）

• bash("npm audit --omit=dev 2>&1 | head -40") — 既知の CVE（node_modules が存在する場合）
• read("package.json") — 依存関係の数と古い依存関係を確認します
• grep(".env|process.env|Bun.env") — 環境変数の使用状況
• 設定ファイル以外で grep("API_KEY|SECRET|PASSWORD|TOKEN") — ハードコードされた設定

指摘対象

• メジャーバージョンが古い依存関係
• 同じ機能を持つ依存関係（ライブラリの重複）
• README に記載されていない、参照されている環境変数
• 環境固有の値のハードコード

6. パフォーマンスとリソース管理

標準（必ず実行）

• bash("sg -p \"for ($$$ of $$$) { $$$ await $$$ }\" -l ts .") — ループ内の非同期処理
• grep("await.*map|await.*filter|await.*forEach") — 順次実行される非同期イテレーション
• grep("Promise\\.all|Promise\\.allSettled") — 既存の並列処理パターン（良い兆候）
• 近くに removeEventListener|off\\(|unsubscribe がない状態での grep("addEventListener|on\\(|subscribe") — リスナーの適切な管理

指摘対象

• for/of ループ内の await（並列実行が可能なのに順次実行）
• N+1 クエリのパターン
• イベントリスナー、インターバル、ハンドルのクリーンアップ漏れ
• 不要なシリアライズ／デシリアライズ

7. エラー処理と可観測性

標準（必ず実行）

• bash("sg -p \"catch ($$$) { $$$ }\" -l ts .") — catch ブロック
• grep("catch.*{}|catch.*{\\s*}") — 空の catch ブロック
• grep("console.error|logger\\.error|log\\.error") — 実際のエラーログ出力
• bash("sg -p \"throw new $ERR($$$)\" -l ts .") — 使用されているエラー型

指摘対象

• 空の catch ブロック（最も重大な問題）
• リカバリー処理のない汎用的な catch (e) { console.error(e) }
• モジュール間で一貫性のないエラー形式
• 重要な処理経路での構造化ログの不足
• Promise チェーン内で握りつぶされるエラー（.catch(() => {})）

8. セキュリティ管理

標準（必ず実行）

• 設定ファイルや環境変数ファイルを除くソースファイルで grep("api[Kk]ey|api_secret|password|secret|token|credential")
• grep("SELECT .* FROM|INSERT INTO|UPDATE.*SET|DELETE FROM") — SQL の構築
• grep("innerHTML|dangerouslySetInnerHTML") — XSS の脆弱性につながる箇所
• grep("eval\\(|Function\\(|setTimeout\\(.*string|setInterval\\(.*string") — コードインジェクション

指摘対象

• ソースコード内にハードコードされたシークレット
• 文字列連結による SQL の構築
• innerHTML / dangerouslySetInnerHTML の使用
• eval() または文字列を使用した setTimeout / setInterval
• 許容範囲が広すぎる CORS または認証ミドルウェア

9. ドキュメントとの乖離

標準（必ず実行）

• read("README.md") — 記載内容が実際の仕様と一致しているか確認します
• grep("@param|@returns|@throws") — docstring の記述状況
• grep("FIXME|TODO|HACK|XXX|WORKAROUND") — 修正メモの密度
• README の API 使用例と実際のシグネチャを比較します

指摘対象

• README に実装されていない機能が記載されている
• 公開関数にドキュメントコメントがない
• コードと矛盾するコメント
• 存在する場合、古くなったアーキテクチャ決定記録（ADR）

フェーズ 2：詳細調査（並列サブエージェント）

大規模なコードベース（>50k LOC）では、負荷の高い調査項目を並列サブエージェントに委任します。各サブエージェントは担当項目について標準のツール実行を行います。

task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 1 (Architecture) and 2 (Consistency). [REQUEST] Run ast_grep and grep searches for dimensions 1-2 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity: Critical/High/Medium/Low.")
task(category="unspecified-low", run_in_background=true, load_skills=[], prompt="[CONTEXT] Tech debt audit. [GOAL] Audit dimensions 3 (Type debt) and 7 (Error handling). [REQUEST] Run searches for dimensions 3 and 7 from the tech-debt-audit skill. Report every finding with file:line:col. Tag severity.")

負荷の高い項目を担当するサブエージェントを 2～3 個起動し、結果を並列で集めてから統合します。

フェーズ 3：統合と報告

1. 直接のツール呼び出しとサブエージェントの結果から、すべての調査結果を集めます
2. 重複を除きます（複数の調査項目で指摘された同じ問題）
3. 重大度を分類します：
   • Critical — 不正な動作、データ損失、またはセキュリティ脆弱性を引き起こす
   • High — 本番環境で問題を引き起こす、または保守を妨げる
   • Medium — 保守性を低下させる、または規約に違反する
   • Low — 表面的な問題。該当箇所を変更する際に修正すべき
4. 各指摘事項の作業時間を保守的に見積もります
5. 必要なセクションをすべて含む TECH_DEBT_AUDIT.md を作成します
6. ユーザーに概要を報告します

重大度の基準

Critical = actively causing bugs or security holes
High     = will cause problems under normal operation; blocks changes
Medium   = reduces maintainability; inconsistent; violates team conventions
Low      = cosmetic; would be nice to fix when nearby

完了前のクイックチェック

• 具体的な指摘すべてに file:line:col の引用を記載している
• 根拠のない一般的な主張がない
• 「問題に見えるが問題ない」セクションで、少なくとも2～3個のパターンを説明している
• 優先度の高い上位5項目を、影響度と作業量で順位付けしている
• クイックウィンは、それぞれ30分未満で修正できる項目になっている