code-necromancer

コードネクロマンサー

タグライン：墓場から死んだコードベースをよみがえらせる

レガシーコードベースを理解し、復活させ、近代化するための体系的なフレームワークです。

使用するタイミング

✅ 次の場合に使用してください：

• ドキュメントがなく、5つ以上のリポジトリを含むコードベースを引き継ぐ場合
• 2年以上休眠状態にある製品を復活させる場合
• 技術的負債が多く、属人化した知識が失われている会社に入社する場合
• 買収したコードベースのデューデリジェンスを行う場合
• 既存の機能を壊さずにレガシーシステムを近代化する場合

❌ 次の場合には使用しないでください：

• グリーンフィールドプロジェクト（新たに始めてください）
• 十分にドキュメント化された、活発に開発されているコードベース
• 保守されているシステムの簡単なバグ修正

3つのフェーズ

フェーズ1：考古学

目標：何かに手を付ける前に、全体像を完全に把握します。

成果物	説明
repo-inventory.json	メタデータ、言語、活動状況を含む全リポジトリ
dependency-graph.mmd	リポジトリ間および外部との依存関係
architecture-diagram.mmd	システム構成を示す図
tech-stack-matrix.md	リポジトリごとの言語／フレームワークのバージョン
maturity-assessment.md	コード品質、テストカバレッジ、ドキュメントの品質
missing-pieces.md	欠落、孤立したリポジトリ、壊れた連携

プロセス：一覧化 → 詳細スキャン → 相互照合 → 可視化 → 評価

→ 詳細な手法については、references/archaeology-guide.md を参照してください。

フェーズ2：復活

目標：開発環境でシステムを動作させます。

成果物	説明
dependency-audit.md	古くなったパッケージ、脆弱性、破壊的変更
environment-variables.md	デフォルト値を含む、必要な環境変数すべて
secrets-needed.md	API キー、証明書、OAuth 認証情報
infrastructure-status.md	クラウドリソースと、現存するもの／削除済みのもの
resurrection-blockers.md	起動を妨げる重大な問題
integration-tests/	コンポーネントが動作し、相互に通信することを検証するテスト

プロセス：依存関係の監査 → 環境の把握 → インフラの確認 → テストの作成 → 阻害要因の文書化

→ 復活テストのパターンについては、references/integration-test-patterns.md を参照してください。

フェーズ3：若返り

目標：機能の同等性を保ちながら近代化します。

成果物	説明
security-recommendations.md	脆弱性の修正、コンプライアンス
modernization-roadmap.md	工数の見積もりを含む、優先順位付けされたアップグレード
architecture-improvements.md	スケーラビリティ、パフォーマンス、保守性

プロセス：セキュリティを最優先 → インフラ（コンテナ化、CI/CD） → コード品質 → アーキテクチャ

主なコマンド

# List all repos in org
gh repo list ORG --limit 1000 --json name,primaryLanguage,pushedAt

# Dependency analysis
npm audit && npm outdated      # Node.js
pip list --outdated && safety check  # Python
go mod graph                    # Go

# Find env vars in code
grep -rn 'process\.env\|os\.environ' --include="*.js" --include="*.py"

→ フレームワーク／技術スタックの特定については、references/framework-detection.md を参照してください。 → クラウドリソースの検出については、references/infrastructure-mapping.md を参照してください。 → 依存関係の検出については、references/dependency-patterns.md を参照してください。

避けるべきアンチパターン

1. 時期尚早な復活

どのようなものか：コードを一切読まずに npm install を実行する なぜ問題なのか：同じバグを5回修正することになり、依存関係も変わっています 対策：まず考古学を完了し、手を付ける前に理解します

2. スコープの拡大

どのようなものか：「ついでにリファクタリングもしましょう」 なぜ問題なのか：範囲が膨れ上がり、復活を実現できなくなります 対策：フェーズを厳密に分け、リファクタリングはフェーズ3で行います

3. 一括アップデート

どのようなものか：すべての依存関係を1つのコミットで更新する なぜ問題なのか：何かが壊れても、原因がわかりません 対策：段階的に更新し、その都度テストします

4. テストの無視

どのようなものか：「動いたから、リリースしよう」 なぜ問題なのか：リグレッションが頻発し、変更を比較する基準もありません 対策：作業を進めながら復活テストを書き、進捗を証明します

5. 変更の未記録

どのようなものか：「修正したけれど、何を変更したか忘れてしまった」 なぜ問題なのか：知識が再び属人化し、6か月後には次の担当者があなた自身になります 対策：学んだことも変更したことも、すべて記録します

6. 古いドキュメントを信頼する

どのように見えるか：2019 年の README に従う なぜ間違いなのか：API は変更され、サービスは廃止されます 対処法：すべての手順を検証してください。ドキュメントは間違っていることがあります

成功指標

発掘完了の条件：

• メタデータとともに、すべてのリポジトリをカタログ化している
• 依存関係グラフを可視化している
• アーキテクチャ図を作成している
• 中核となるリポジトリと周辺リポジトリを特定している
• 不足している要素を記録している

復旧完了の条件：

• すべてのサービスをローカルで起動できる
• サービス同士が通信できる
• 統合テストに合格する
• 少なくとも 1 つのユーザーフロー全体が機能する

再生完了の条件：

• 重大なセキュリティ脆弱性がない
• すべての依存関係が妥当な範囲で最新である
• CI/CD パイプラインが動作する
• ドキュメントが最新である
• チームが新機能を開発できる

参考資料

→ references/archaeology-guide.md - コード発掘の詳細な手法 → references/dependency-patterns.md - 各種エコシステムにおける依存関係の検出 → references/framework-detection.md - フレームワーク／スタックの特定 → references/infrastructure-mapping.md - クラウドリソースの発見 → references/integration-test-patterns.md - 復旧テストのパターン

テンプレート

→ templates/repo-inventory.json - リポジトリカタログ → templates/archaeology-report.md - フェーズ 1 の成果物 → templates/resurrection-plan.md - フェーズ 2 の計画 → templates/rejuvenation-roadmap.md - フェーズ 3 のロードマップ