code-overhaul-review

コードの全面見直し

保守性、モダナイゼーション、全面的な見直しの観点から、このコードベースを監査してください。問題ごとに具体的なトレードオフを示し、明確な推奨案を最初に提示したうえで、方針を決めつける前に意見を求めてください。

これは健全性チェックであり、機能のレビューではありません。信頼性、パフォーマンス、保守性、開発速度を大きく向上させる変更を特定し、規律ある順序で実行することが目的です。

スタックの検出： ステップ 0 の開始時に、言語を示すファイル（*.swift／Xcode プロジェクト、go.mod、package.json／tsconfig）をリポジトリ内で確認してください。検出したスタックごとに、以下の「言語固有の追加項目」から該当する追加項目を、汎用セクションに加えて適用してください。モノレポでは複数の追加項目を適用し、どの指摘がどのモジュール／パッケージに当てはまるかを記載してください。

優先順位

コンテキストが限られている場合は、ステップ 0 ＞ 影響度／工数マトリクス ＞ テスト図 ＞ 推奨事項 ＞ その他とします。ステップ 0 とマトリクスは決して省略しないでください。

エンジニアリングの方針

• DRY — 重複は積極的に指摘してください。
• 十分なテストは絶対条件です。少なすぎるより多すぎるほうがよいです。
• 「十分に設計する」— 壊れやすくせず、過度に抽象化もしないでください。
• エッジケースは少なくするのではなく、増やしてください。速さより熟慮を優先してください。
• 巧妙さより明示性を優先してください。
• 差分は最小限に — 新しい抽象化と変更するファイルを最小限に抑えてください。
• パフォーマンスは機能の一部です。変更の前後でプロファイリングしてください。
• 可能な場合は、サードパーティ製よりプラットフォーム／標準ライブラリを優先してください。
• 非推奨の警告はバグです。先回りして修正してください。
• ビルド時間は重要です。ビルドを遅くする変更には、理由を示してください。

図

データフロー、状態機械、依存関係グラフ、パイプライン、決定木を、計画とインラインコードコメントに ASCII アートで示してください。動作が自明でない箇所（モデル、サービス、ビュー／コントローラー、テスト）に埋め込んでください。

図の保守も変更の一部です。 古い図は、図がないよりも悪いものです。スコープ外であっても指摘してください。

開始前に

ステップ 0：スコープの評価

1. リポジトリの健全性： コンパイラー／リンターの警告、非推奨の警告、TODO／FIXME／HACK の密度、デッドコード、未使用のインポート、テスト合格率、ビルド時間。（追加項目にあるスタック固有のツールも使用してください。）
2. 依存関係の状況： サードパーティ製依存関係をすべて確認し、現行バージョンと最新バージョンを比較してください。以下に該当するものを指摘してください：メジャーバージョンが 1 つ以上遅れている、12 か月以上メンテナンスされていない、プラットフォーム API で代替可能。
3. プラットフォーム／言語の最低バージョン： 利用可能な最新 API と、不要になる回避策を判断します。
4. 技術的負債の集中： サイズ、変更頻度、結合度、バグ履歴に基づく上位 3～5 件のファイル／モジュール。
5. 複雑さの確認： ファイルが 15 個を超える場合、または新しい抽象化が 3 つを超える場合は、スコープを再検討してください。

3 つのモードを提示してください：

1. SURGICAL： 1 つのテーマに絞り、影響範囲を最小限にした 1 セッションでの対応。
2. SYSTEMATIC： セクションごとに対話しながら進め、各セクションは問題 4 件以下。
3. FULL AUDIT： すべてのセクションと問題を対象にし、段階的なロードマップを作成。

選択されたら、最後まで徹底してください。 方針を伝えずにスコープを縮小しないでください。

レビューのセクション

1. アーキテクチャ

モジュールの構造と境界（依存関係グラフを描く）、レイヤー違反、データフローと信頼できる情報源、並行性／スレッドセーフティ、ルーティング／ナビゲーションの一貫性、スケーリングのボトルネック、セキュリティ境界を評価してください。主要な境界ごとに、現実に起こりうる本番環境の障害を 1 つ挙げ、現在のコードが対処できるかどうかを示してください。ASCII 図をどこに配置すべきか特定してください。スタックの追加項目を適用してください。

停止してください。 AskUserQuestion を使用してください。ユーザーが応答するまで先に進まないでください。

2. コード品質

ファイル／フォルダーの整理、DRY 違反、エラー処理の不足（ファイル名と行番号を明記）、命名の一貫性、技術的負債の集中箇所、過剰な設計と設計不足、デッドコード、古くなった図、リンター／コンパイラーの警告を評価してください。スタックの追加項目を適用してください。

停止してください。 AskUserQuestion を使用してください。ユーザーが応答するまで先に進まないでください。

3. テスト

重要なフロー、パイプライン、状態遷移、分岐をすべて図示してください。それぞれについて、テストの有無、有意義な内容かどうか、エッジケースを網羅しているか、実行が速く安定しているかを確認してください。さらに、テストの分布、実行時間（遅いテストを指摘）、分離性、不足しているテストの種類、モック戦略も確認してください。スタックの追加項目を適用してください。

停止してください。 AskUserQuestion を使用してください。ユーザーが応答するまで先に進まないでください。

4. パフォーマンス

評価項目：起動時間、メモリ使用量とリーク、ホットパスの応答レイテンシー、I/O パターン、ネットワーク効率、ビルド時間、バイナリ／バンドルサイズ。スタック別の追加項目を適用してください。

停止。 AskUserQuestion。ユーザーの回答があるまで進めないでください。

5. 依存関係とモダナイゼーション

評価項目：古くなった依存関係、置き換え可能な依存関係、メンテナンスされていない依存関係、言語のモダナイゼーションの機会、ツールチェーンの健全性、CI/CD の健全性。スタック別の追加項目を適用してください。

停止。 AskUserQuestion。ユーザーの回答があるまで進めないでください。

各問題について

• ファイル／行番号の参照。
• 「延期」を含む2～3個の選択肢。
• 各選択肢について、労力、リスク、影響範囲、メンテナンス負担を1行で記載。
• 指示から始める：「Bを実施してください。その理由は次のとおりです：」
• エンジニアリング上の方針に対応付けることを1文で記載。
• AskUserQuestion：「[LETTER]を推奨します：[reason]」に続けて、A) ... B) ... C) ...。ラベル：NUMBER + LETTER（例：「3B」）。

必須の出力

影響度／労力マトリックス

                LOW EFFORT        HIGH EFFORT
           ┌─────────────────┬─────────────────┐
HIGH       │ DO FIRST         │ PLAN CAREFULLY   │
IMPACT     │ (quick wins)     │ (core overhaul)  │
           ├─────────────────┼─────────────────┤
LOW        │ IF TIME          │ SKIP / DEFER     │
IMPACT     │ (polish)         │ (not worth it)   │
           └─────────────────┴─────────────────┘

対象外

延期する作業と、それぞれの簡潔な理由。

既存のもの

コードベースにすでにある、十分に活用されていないユーティリティ、ヘルパー、パターン。

延期する作業 → Beads

bd create "<title>" -t <type> -p <priority> -d "<what, why, current state, where to start, prereqs>" -l "tech-debt,overhaul"

登録前に確認してください。bd dep add でリンクしてください。

図

変更前／変更後の依存関係グラフ、リファクタリング後のデータフロー、状態機械。インライン図が必要なファイルを特定してください。

障害モード

変更するコードパスごとに、現実的な障害を1つ挙げ、テストでカバーされているか、エラー処理があるか、ユーザーに見えるか、またはサイレントに発生するかを示してください。テストも処理もなく、サイレントに発生する場合は、重大なギャップです。

移行／ロールバック

段階的か、それとも一括実施か。ロールバック計画はあるか。旧版と新版を共存させるか。検証方法は何か。

実行順序

次の条件を守り、番号付きで示してください：（1）変更間の依存関係、（2）影響度／労力の優先順位、（3）リファクタリングより先にテストを実施、（4）各ステップを単独でリリース可能にする。

完了サマリー

╔════════════════════════════════════════════════╗
║           CODE OVERHAUL SUMMARY                ║
╠════════════════════════════════════════════════╣
║ Mode:                 ___                      ║
║ Stacks detected:      ___                      ║
║ Warnings:             ___ compiler, ___ deprec ║
║ Dead code:            ___                      ║
║────────────────────────────────────────────────║
║ Architecture:         ___ issues               ║
║ Code quality:         ___ issues               ║
║ Tests:                ___ gaps                 ║
║ Performance:          ___ issues               ║
║ Dependencies:         ___ outdated, ___ replace║
║────────────────────────────────────────────────║
║ Quick wins:           ___                      ║
║ Core overhaul:        ___                      ║
║ Beads filed:          ___                      ║
║ Critical gaps:        ___                      ║
║ Execution steps:      ___                      ║
╚════════════════════════════════════════════════╝

スタック別の追加項目の行も加えてください（例：force-unwrap の数、any の数、race-clean の状態）。

振り返りによる学習

Git のログを確認してください：変更頻度の高いファイル、取り消されたコミット、大規模な「修正」コミット、繰り返し現れるパターン（「…のクラッシュを修正」「…の回避策」など）。過去に問題が多かった領域には、積極的に対処してください。

書式

問題にはNUMBER、選択肢にはLETTERを付けてください。最初に推奨案を示してください。各選択肢は1文にしてください。各セクションの後で一時停止してください。

未解決の決定事項

最後に「後々問題になりかねない未解決の決定事項」を記載してください。暗黙のうちにデフォルトを選ばないでください。

アンチパターン

• 大規模な一括書き換え → 段階的に進める。
• テストなしのリファクタリング → まず特性テストを作成する。
• 過剰な作り込み → 完璧さではなく健全性を目指す。
• 新しい流行の追求 → 具体的な問題だけを解決する。
• ビルドの破壊 → すべてのコミットでコンパイルとテストを成功させる。

---

言語固有の追加項目

該当するスタックが検出された場合は、以下を適用してください。モノレポの場合は、該当する追加項目をすべて適用し、各指摘にモジュール名を付けてください。

---

追加項目：iOS／Swift

検出条件： .swift ファイル、.xcodeproj、*.xcworkspace、Apple プラットフォームをターゲットとする Package.swift。

ステップ0の追加項目

• 実行：Xcode の警告数、SwiftLint の違反数、デプロイメントターゲット（iOS の最小バージョン）。
• デプロイメントターゲットによって、SwiftUI API の範囲、構造化並行処理の利用可否、不要にできる UIKit の回避策が決まります。
• 依存関係の監査で確認するもの：SPM／CocoaPods／Carthage。置き換え可能なもの：Kingfisher→AsyncImage、Alamofire→URLSession async/await、SnapKit→最新の AutoLayout、RxSwift→Combine/async-await、KeychainAccess→ネイティブのキーチェーン、SwiftyJSON→Codable、IQKeyboardManager→ネイティブのキーボード回避機能。

アーキテクチャの追加項目

• 状態管理の一貫性：@Observable、ObservableObject、@State のうち、関心事ごとに1つを選び、混在させないでください。
• ナビゲーション：NavigationStack、コーディネーターパターン、または混在のいずれかで一貫していますか。
• 並行処理モデル：構造化並行処理への移行境界と、従来の GCD／完了ハンドラーを確認してください。移行の境界はどこですか。
• Core Data／SwiftData スタックの健全性。拡張ターゲット間でコードを正しく共有できていますか。

コード品質に関する追加項目

• 強制アンラップと暗黙的にアンラップされるオプショナル — クラッシュの原因となるため、すべて列挙してください。
• try? によるエラーの暗黙的な無視。空の catch ブロック。
• 保持サイクルのリスク：クロージャーで [weak self] がない、弱参照ではないデリゲートプロパティ。
• 不要な @objc の公開、古くなった Storyboard／XIB の接続、使われていない IBOutlets／IBActions。
• 肥大化した ViewController／View（300 行超）。
• プロトコル指向設計の過剰な適用：準拠型が 1 つだけのプロトコル、不要な関連型。

テストに関する追加項目

• XCTest と Swift Testing の採用状況。UI テストの信頼性（UI テスト 1 件あたり 10 秒超なら指摘）。
• テストホストアプリへの依存 — アプリを起動せずにユニットテストを実行できますか？
• Core Data のテストでインメモリストアを使用していますか？ネットワークテストで URLProtocol のモックを使用していますか？
• テスト数が多い場合はスイート全体の実行時間が重要です — 60 秒超なら指摘。
• 不足しているテスト：複雑なレイアウトのスナップショットテスト、アクセシビリティ監査テスト。

パフォーマンスに関する追加項目

• 起動： main 前（dylib の読み込み、+load、静的初期化子）と main 後。didFinishLaunching でメインスレッド上に同期処理がありますか？
• メインスレッド： メイン上でのファイル I/O、JSON 解析、画像デコード、Core Data のフェッチ。
• スクロール： セルの再利用、非同期画像読み込み、Auto Layout の曖昧さ、オフスクリーンレンダリング（cornerRadius と clipsToBounds の併用）。
• メディア： 表示前に画像をダウンサンプリングしていますか？PhotoKit のフェッチは効率的ですか？不要な形式変換はありませんか？
• ビルド： -Xfrontend -debug-time-function-bodies による最も遅いファイルの特定。複雑な型推論。SPM の依存関係解決時間。
• バイナリ： 未使用のアセットカタログ項目、オンデマンドにできる埋め込みリソース。

モダナイゼーションに関する追加項目

• 構造化並行処理：async/await、アクター、タスクグループ。
• @Observable マクロ（iOS 17+）、#Preview マクロ、EnvironmentValues 用の @Entry。
• 型付き throws（Swift 6）、厳密な並行処理チェックへの対応状況。
• Xcode の整理：未使用のビルドフェーズ、古くなったスキーム、コード署名の不整合、不適切な階層に設定されたビルド設定。

サマリーに関する追加項目

行を追加：最小 iOS ターゲット、Swift のバージョン、強制アンラップの数、SwiftLint の違反数。

追加のアンチパターン

• 境界戦略を定めないまま UIKit から SwiftUI に移行する → ブリッジパターンを一度定義し、全体で統一して使用してください。

---

追補：Go

対象となるファイル： go.mod、*.go ファイル。

ステップ 0 の追加項目

• 実行：go vet、staticcheck、golangci-lint、govulncheck ./...、go mod tidy による差分チェック。
• go.mod の Go バージョンで決まる機能：range-over-func（1.23+）、log/slog（1.21+）、errors.Join（1.20+）、ジェネリクスの適用範囲、ループ変数の修正（1.22+）。
• 依存関係監査の詳細：go list -m -u all。置き換え可能なもの：gorilla/mux → stdlib の 1.22+ ルーティング、logrus → log/slog、pkg/errors → fmt.Errorf %w、testify → stdlib testing、go-playground/validator → 独自実装、gorm → sqlc/sqlx、シンプルな CLI では cobra → stdlib flag。

アーキテクチャに関する追加項目

• パッケージ境界：internal/ の使い方は適切ですか？循環依存のリスクはありませんか？
• インターフェースの乱立：利用側ではなく実装側が定義するインターフェースが多すぎませんか？インターフェースを受け取り、構造体を返してください。
• 依存性注入：wire、手動、または散在する init() のどれですか？
• 正常終了の連鎖：シグナル → コンテキストのキャンセル → リソースのクリーンアップ。
• エラーの伝播：センチネル、型付き、ラップのどれを使うか、一貫していますか？
• コンテキスト：値とキャンセルの使い分けは適切ですか？誤用されていませんか？

コード品質に関する追加項目

• 未チェックのエラー： _ = foo() — コメントで正当化されていない限り、すべて列挙してください。
• 複雑な関数での裸の return。
• パッケージレベルのグローバル変数と init() の乱用。
• 命名：Go の規約（MixedCaps、1～2 文字のレシーバー、単語 1 つの小文字のパッケージ名）。名前の重複（user.UserService）。
• 過剰な設計：実装が 1 つだけのインターフェース、不要なジェネリクス、設定値が 2 つだけなのに Options パターンを使うこと。
• 設計不足：2000 行超のファイル、引数が 5 つ超、ジェネリクスを使えば明確になる箇所での any／interface{} の使用。

テストの追加

• テーブル駆動テストは一貫していますか？ t.Helper() は使われていますか？ t.Run() を使ったサブテストはありますか？
• //go:build integration タグ付きの統合テストはありますか？
• レース検出器： go test -race は成功しますか？これは必須条件であり、任意ではありません。
• ホットパス向けのベンチマーク（BenchmarkX）。パーサー向けのファジングテスト（FuzzX）。
• 複雑な出力にはゴールデンファイルを使用します。testdata/ は整理されていますか？
• モック：境界でのみインターフェースを使い、すべてをモックしないでください。ハンドラーには httptest を使います。

パフォーマンスの改善

• CPU： タイトな処理経路での不要なアロケーション、ホットコードでのリフレクション、ループ内での正規表現のコンパイル（パッケージ変数として一度だけコンパイル）、ループ内での文字列連結（strings.Builder）。
• メモリ： ゴルーチンリーク（コンテキストをキャンセルせずに無制限に起動する）、sync.Pool の活用機会、スライスの事前割り当て（make([]T, 0, cap)）、ホットパスでの string↔[]byte 変換。
• 並行処理： ミューテックス競合（RWMutex？ atomic？）、チャネルのバッファーサイズ、上限のないゴルーチンのファンアウト（errgroup）、コンテキスト伝播の漏れ。
• I/O： 接続プールのサイズ、プリペアドステートメントの再利用、N+1 クエリ、HTTP クライアントの再利用（リクエストごとに作成しない）、レスポンスボディの未クローズ、ファイルへの bufio の使用。
• ビルド： CGO（ビルドが遅くなり、クロスコンパイルが複雑になります）、不要な go generate。
• バイナリ： -ldflags "-s -w"、-trimpath、未使用の依存関係による肥大化。

モダナイズの追加

• 明確になる場合は、interface{}／コード生成をジェネリクスに置き換えます（具体的な型が2つを超える場合に限ります）。
• range-over-func（1.23+）、log/slog、errors.Join、ループ変数の修正（1.22+）— 回避策を削除します。
• iter パッケージ（1.23+）、any／comparable 制約。
• ツールチェーン：Makefile／Taskfile の整備、golangci-lint 設定の最新化、CI（test、vet、lint、race、vulncheck）。

サマリーの追加

行を追加します：Go のバージョン（mod）、go vet の問題、staticcheck の問題、govulncheck の検出結果、未チェックのエラー、レースなし Y/N。

その他のアンチパターン

• インターフェースの過剰使用 → 1メソッドのインターフェースは Go に適していますが、最初から使うものではありません。
• 早すぎるジェネリクス導入 → 具体的な型が2つを超え、パターンが実証されている場合に限ります。

---

追補：Web／JavaScript／CSS

対象ファイル： package.json、tsconfig.json、*.js、*.ts、*.jsx、*.tsx、*.css、*.scss、*.html ファイル。

ステップ 0 の追加

• 実行項目：tsc --noEmit のエラー、ESLint／Prettier の違反、npm audit、バンドルサイズ（合計＋ルートごと）。
• TypeScript の strict モードは有効ですか？そうでない場合、移行計画の優先度は高くなります。
• 対象ブラウザーの下限（browserslist）によって、CSS のネスト、:has()、コンテナークエリ、structuredClone、AbortSignal.any、Promise.withResolvers が決まります。
• 依存関係の監査：npm outdated。置き換え可能なもの：moment→Temporal/date-fns、lodash→ネイティブ機能（Array.at、Object.groupBy、structuredClone）、axios→fetch、classnames→clsx／テンプレートリテラル、uuid→crypto.randomUUID、node-fetch→ネイティブの fetch（Node 18+）。

アーキテクチャの追加

• コンポーネント階層（ツリーを描く）。状態管理：ローカルとグローバル、props のバケツリレーと context とストア — 一貫していますか？
• データ取得：コンポーネントごと、ルートレベル、集中管理のどれですか？キャッシュ／重複排除はありますか？読み込み／エラー状態はありますか？
• API レイヤー：fetch 呼び出しは散在していますか、それとも集中管理されていますか？
• 該当する場合、SSR／SSG／CSR の境界。エラーバウンダリーの配置。
• ビルド設定の複雑さ。環境の扱い。

コード品質の追加

JS／TS：

• any 型 — すべてを挙げてください。これらは TypeScript の利点を損ないます。
• 安全性を回避する as アサーション。緩い等価比較（==）。
• 捕捉されない Promise の拒否。エラーバウンダリーの不足。
• ツリーシェイキングを妨げるバレルファイルの肥大化。未使用のエクスポート（ts-prune）。
• 300行を超えるコンポーネントファイル。

CSS：

• 詳細度の競合、!important の多用。
• カスタムプロパティを使わないマジックナンバー。デザイントークンが必要な重複値。
• 未使用の CSS。一貫性のない命名（BEM とユーティリティとランダムな命名）。
• z-index：文書化されたスケールがありますか、それとも無秩序ですか？メディアクエリ：散在していますか、それとも集中管理されていますか？
• CSS-in-JS、スタイルシート、ユーティリティのどれを使っていますか？一貫した方針ですか？

HTML／アクセシビリティ：

• セマンティック HTML（div だらけになっていませんか？）。ARIA：不足や誤りはありませんか。キーボード操作、フォーカス管理、色のコントラスト、代替テキスト、フォームラベル、見出し階層。

テストの追加

• ロジックにはユニットテスト（Jest/Vitest）を使用します。振る舞いにはコンポーネントテスト（Testing Library）を使用します。getByTestId の多用を指摘し、getByRole／getByText を優先します。
• 重要な経路には E2E テスト（Playwright/Cypress）を使用します。複雑なレイアウトにはビジュアルリグレッションテストを使用します。
• ネットワークのモックには MSW を使用します。一貫性はありますか？スナップショットテストは有用ですか、それともノイズですか？
• アクセシビリティテスト（axe-core）。スイートの実行時間について、合計30秒超、個別に5秒超の場合は指摘します。

パフォーマンスの追加

• Core Web Vitals： LCP（クリティカルレンダリングパス）、CLS（サイズ指定のない画像、フォントのちらつき、動的な挿入）、INP（長時間タスク、負荷の高いハンドラー）。
• バンドル： ルートごとの分割、ツリーシェイキングの有効性、画面下部コンテンツへの動的インポート、重複する依存関係、source-map-explorer による分析。
• 読み込み： クリティカル CSS はインライン化されていますか？レンダリングをブロックするリソースはありますか？フォント戦略（font-display、プリロード）は適切ですか？画像（WebP/AVIF、srcset、遅延読み込み、明示的なサイズ指定）は適切ですか？
• ランタイム： 不要な再レンダリング（計測で判明した、memo の不足）、DOM のスラッシング、イベントリスナーのクリーンアップ、Web Worker の活用機会、視覚的な更新への requestAnimationFrame の使用。
• キャッシュ： サービスワーカーの戦略、HTTP ヘッダー、CDN、stale-while-revalidate、アセットのフィンガープリント化。
• ネットワーク： API のウォーターフォール（逐次→並列）、過剰なデータ取得、ページネーションの不足。

モダナイズの追加

• CSS：ネイティブのネスト（プリプロセッサのネストを削除）、コンテナクエリ、:has()、View Transitions、Popover API、<dialog>（モーダルライブラリを削除）、color-mix()、@property。
• TS：strict モードへの移行、satisfies、テンプレートリテラル型、判別可能なユニオン、using（5.2以降）。
• プラットフォーム：structuredClone、Object.groupBy、Set メソッド、インポート属性。
• ツールチェーン：バンドラーの最新性（Webpack→Vite？）、Node のバージョン、パッケージマネージャーの統一、モノレポ用ツール、プレビュー環境へのデプロイ。

サマリーの追加

行を追加します：フレームワーク、TS strict の有無、any の数、ESLint 違反数、バンドルサイズ（gzip）、npm audit の脆弱性数、LCP。

追加のアンチパターン

• 早すぎる抽象化 → 3つのボタンのためにコンポーネントシステムを構築しないでください。
• CSS リセットのいたちごっこ → 症状ではなく、詳細度のモデルを修正してください。
• any を逃げ道として使う → すべての any は、複利で増える先送りの負債です。
• フレームワークの頻繁な乗り換え → 目新しさではなく、具体的な問題の解決に必要なときに移行してください。