金色の配線パターンが広がる基板の接写
現場の実践

引き継いだPythonプロジェクトの技術棚卸しで陥る3つの落とし穴

目次を見る

前任者が退職したあとに残されたPythonのリポジトリを引き継いだとき、何から手を付けるか迷った経験はないでしょうか。

この記事は、保守対象のコードベースを引き継いだエンジニアや、モノレポ化した社内システムの技術構成を棚卸ししたいPM・アーキテクトに向けた内容です。静的解析(プログラムを実行せずソースコードやファイル構成だけを読み取る手法)でプロジェクト全体を把握しようとした際に起きやすいつまずきを整理し、確認の手順を示します。

何が起きるか:棚卸し結果と実態のズレ

既存プロジェクトを引き継ぐ際、技術スタックや依存ライブラリ、外部サービス連携の全体像を知りたい場面は多くあります。

よく整備されたプロジェクトなら README やドキュメントを読めば済みます。しかし長年運用されたレガシーシステムやモノレポ(複数サービスのコードを1つのリポジトリにまとめる構成)では、情報が設定ファイル・依存関係マニフェスト(requirements.txt や pyproject.toml など依存ライブラリの一覧を記したファイル)・Dockerfile・ソースコードの各所に散らばっています。

この状況を解消する手段として、プロジェクトを実行せずファイルシステムを走査するだけで技術棚卸しを行うスキャナーツールが使われることがあります。ところが、こうしたツールが吐き出すレポートをそのまま信じると、思わぬ見落としが発生します。

具体的には次の3つのズレが典型例です。

  • Docker Compose に定義されているだけで実際には起動していないサービスを「稼働中」と誤認する
  • pip install 済みだがコード内で一度もインポートされていないライブラリを「使用中」と数えてしまう
  • .env に書かれているが参照されていない環境変数を「必須設定」と判断してしまう

これらは棚卸し結果を読む側が気づかなければ、移行計画や影響範囲の見積もりを誤らせる原因になります。

なぜ起きるか:静的解析の原理的な限界

原因を段階的に分解すると、根っこにあるのは「静的解析は観測可能な情報しか扱えない」という設計上の性質です。

まず、静的解析エンジンはアプリケーションを起動しません。依存ライブラリのインストールもDockerコンテナの起動も行わず、ファイルシステム上に存在するファイルだけを読み取ります。これは解析対象の環境を汚さず、どんなプロジェクトにも安全に適用できる利点があります。

一方でこの設計は、「宣言されていること」と「実際に動いていること」を区別できない副作用を持ちます。たとえばDocker Composeの docker-compose.yml にサービス定義が書かれていても、それは「定義されている」事実を示すだけで「現在稼働している」ことの証明にはなりません。

同様に、依存関係マニフェストに記載されたパッケージがソースコード内で import されているかどうかは、マニフェストを読むだけでは分かりません。実際に import 文を解析するフェーズを経て初めて「使用されている」と判定できます。

さらに、ディレクトリ走査の段階で node_modules や .venv、__pycache__、vendor のような生成物ディレクトリを除外しないと、解析対象のファイル数が爆発的に増え、ノイズに埋もれて本質的な依存関係が見えなくなります。除外リストの設計が甘いツールほど、この問題を起こしやすくなります。

自分のプロジェクトが該当するか確認する方法

棚卸しツールの出力を鵜呑みにする前に、次の点を自分のプロジェクトで確認してみてください。

依存関係マニフェストの数を数える

モノレポや複数言語が混在するプロジェクトでは、requirements.txt や pyproject.toml、package.json、go.mod など複数のエコシステムのマニフェストが同居します。

find . -type f \( -name "requirements*.txt" -o -name "pyproject.toml" -o -name "package.json" -o -name "go.mod" \) \
  -not -path "*/node_modules/*" -not -path "*/.venv/*"

このコマンドで複数件ヒットするなら、単一言語・単一環境を前提にした棚卸しツールでは情報が欠落する可能性が高くなります。

Docker Compose の定義と実際の稼働を突き合わせる

docker compose config --services
docker compose ps --services --status running

前者は「定義されているサービス一覧」、後者は「実際に起動中のサービス一覧」です。両者の差分が、棚卸しレポートが「稼働中」と誤認する可能性のある箇所です。

未使用の依存ライブラリを洗い出す

Pythonであれば pip-audit や pipdeptree のような専用ツールに加えて、単純にgrepで確認する方法もあります。

pip freeze | cut -d= -f1 | while read pkg; do
  grep -rq "import ${pkg}" --include="*.py" . || echo "未使用の可能性: ${pkg}"
 done

パッケージ名とimport名が異なるケース(例: Pillow を import PIL で使う)もあるため、ヒットした結果は目視での最終確認が必要です。

対策の手順

静的解析による棚卸しレポートを業務判断の根拠にする場合、以下の手順で裏取りを行うことをおすすめします。

1. 除外ディレクトリ設定を確認する: 使用するスキャナーが .git node_modules .venv dist build などを除外対象にしているか、設定ファイルかソースコードで確認します。含まれていなければノイズ混入のリスクが高くなります。

2. 「宣言」と「実行時の状態」を分けてレポートを読む: Docker Composeのサービス定義、環境変数の存在、依存ライブラリのインストール済み一覧は、いずれも「宣言」の情報です。docker compose ps やログ監視、pip-audit のような実行時確認手段と突き合わせます。

3. サブプロジェクトの境界を手動で検証する: モノレポ内の各サービスディレクトリに、独立したマニフェストファイル(pyproject.toml や package.json)があるか確認します。棚卸しツールがサブプロジェクトとして正しく認識しているかは、この境界検出のロジック次第です。

4. 関係性マッピングの出典を追う: サービスAとサービスBが「連携している」と棚卸しレポートに書かれていた場合、その根拠が環境変数の文字列一致なのか、実際のAPI呼び出しコードの解析なのかを確認します。前者は誤検出の余地が大きくなります。

5. レポート形式に応じて用途を分ける: HTML形式のレポートは関係者への説明資料に、JSON形式はCI/CDパイプラインでの自動チェックに、CSV形式は表計算ソフトでの棚卸し台帳管理に向いています。出力形式が複数選べるツールであれば、目的に応じて使い分けると二度手間になりません。

確認すべきドキュメントの場所

具体的なツールを導入する場合は、そのツールの公式ドキュメントで次の2点を必ず確認してください。

  • 除外ディレクトリのデフォルト設定と、カスタマイズ可能な設定ファイルの場所
  • 「検出(detectors)」と「分析(analyzers)」の処理が分離されているか。分離されていれば、どの段階で何を観測したかをログやレポートから追跡しやすくなります

まとめ

静的解析ベースの技術棚卸しは、ドキュメントが散逸したレガシープロジェクトやモノレポの全体像をつかむ出発点として有効です。

ただし、宣言された情報と実行時の実態は別物だという前提を忘れると、移行計画やリスク評価を誤る落とし穴にはまります。

導入する際は、まず自分のリポジトリで docker compose config と docker compose ps を突き合わせ、未使用パッケージの洗い出しコマンドを一度実行してみてください。

棚卸しレポートを「仮説」として扱い、実行時の確認作業とセットで運用する姿勢が、引き継いだプロジェクトの技術的負債を正しく見積もる土台になります。

参考

🔎 Python Project Scanner Architecture: Static Analysis, Multi-Ecosystem Dependencies, and Technical Mapping

AI 駆動開発のご相談は forva AI へ。

まずはお気軽にどうぞ。