15,000行の巨大コードを劇的改善：テックリードが主導した大規模リファクタリングの実録
本記事は、個人開発サービス「CheckMe（checkme.run）」の技術的な開発過程を詳述したもので、特に巨大化したコードベースの改善（リファクタリング）に焦点を当てています。サービスの中核となる`main.py`ファイルは、当初15,352行、サイズは1.1MBを超える単一ファイルとなっており、AIプロンプト54個、ツールロジック60本分、デッキデータ106個、全設定値がすべてこのファイルに「詰め込まれて」いました。この状態では、エラー発生時の原因特定に時間を要し、新機能追加によるシステム崩壊リスクが極めて高いという診断がなされました。
この問題に対し、テックリードが主導し、3日間にわたる大規模なリファクタリングを実施しました。主な改善方針は「データはコードに書かず、ロジックのみを残す」「繰り返しは一度だけ書く」という原則に基づいています。具体的な改善策は以下の4点です。
1. **AIプロンプトの外部化**: 54個のAIプロンプトをハードコードからSQLiteデータベースに移行。これにより、デプロイ不要でプロンプトの更新が可能となり、変更履歴の管理やn8nからの自動更新が可能になりました。
2. **設定データの分離**: ツールメタ情報やポケモンタイプデータなど、各種設定値を`config/*.json`ファイル群に分離し、コードの可読性を高めました。
3. **共通ラッパーへの集約**: 以前は各エンドポイントで重複していたキャッシュ処理やAI呼び出し（ボイラープレート）のロジックを、`_ai_call()`という共通ラッパー関数に集約。これにより、冗長なコードが1行に集約されました。
4. **レスポンスヘルパーの統一**: エラー処理やテンプレートレンダリングなどのレスポンス処理を共通関数に統一しました。
これらの改善の結果、コードの行数は15,352行から9,949行へと削減され、サイズも1.1MBから450KBに大幅に縮小しました。これは35%の削減に相当し、開発の持続可能性と保守性を劇的に向上させました。筆者は、巨大な`main.py`ファイルは個人開発における典型的な技術的負債であり、データとロジックの分離、共通ラッパーの徹底的な活用が重要であると結論づけています。
背景
本記事は、個人開発サービスにおける「技術的負債」の典型的な事例と、その解決プロセスを解説しています。初期段階では、開発のスピードを優先するあまり、すべてのデータやロジックが単一ファイルに集約され、コードが肥大化（モノリス化）しました。これは、開発初期によく見られる構造的な問題です。
重要用語解説
- 技術的負債: ソフトウェア開発において、短期的な実装の容易さのために、後で修正・改善が必要な構造的な欠陥を指します。将来的な開発コスト増大の原因となります。
- リファクタリング: コードの外部から振る舞いを変えずに、内部構造（可読性、効率性など）を改善する作業のこと。システムの健全性を保つために不可欠です。
- ボイラープレート: 特定の機能を実現するために、毎回同じように記述しなければならない定型的なコードの塊。共通関数化することで削減が図られます。
今後の影響
このリファクタリングは、単なるコードの削減に留まらず、サービスの保守性と拡張性を飛躍的に向上させました。今後は、より大規模な機能追加や、月間10万PVを目指すための安定的な運用基盤が確立されたと予想されます。データとロジックの分離は、今後の機能追加のスピードを加速させる鍵となります。