🦔

レガシーコードと向き合っていく / Clude Code ✖️ Project Analyze

に公開
AI
legacy
Claude
idea

はじめに

Claude Code を利用して、プロジェクト解析を進めていきながら、果てしてこの進め方はいいのか？という思いが募り、最近社内で勧められていた書籍「LangChainとLangGraphによるRAG・AIエージェント［実践］入門 エンジニア選書」をもとに、AIエージェントのデザインパターンが適切なのかと、解析した内容の精度が上がるのかをみていこうと思います。

本編の計画

目的

  • レガシーとなっているアプリケーション、レガシーになりつつあるアプリケーションの解析を行い、これから実施しようとしているアプリケーション改修を 楽に 進めていきたいので、自分で調べていくより、AIに縋りたい一心と、ドキュメントにすることを任せたいので、Claudeを用いて挑戦をする。
    • なお、レガシーを強調しているのは、まとまったドキュメントがないことや、ドキュメントが複数あり、どのドキュメントの進行をしたらいいのかがワカラナイため、アプリケーションコードなどの実態が存在しているものが抽出したほうが確かな情報になると思ったのと、今後、ドキュメントを用いて、アプリケーションコードを作っていくなら、AIを用いて循環できるようにしたいという思いから、自ら何かを記載するというのは極力せずに、進めていこうとしています。
    • ドキュメントは、https://www.rdra.jp/ がよいという話を聞いているので、本件とは別に解析内容の考察後に、本件と組み合わせて実現しようと思っています。

背景

  • アプリケーション改修をするうえで、現状解析を必須であるが、システム構成が入り組んでおり、SSR/SPAや、アーキテクチャーも複数のフレームワークに跨って稼働していることもあり、現状何があるかの洗い出しをするだけでも、プロジェクトを進めたときに協力しながら進めた方が、他作業をしながらではあったものの、３〜４週間かかったこともあり、時間がかかることが容易に想像が着いたので、楽を したい。

達成基準

  • 以下をレポートとして出力する。（業務要件の影響を把握する。データ構成がアプリケーション構造が１：１の関係性になっているので、テーブル変更は即アプリケーションに影響する。
    • テーブルの影響把握
    • テーブルと関連するアプリケーションの影響把握

実施したこと

解析のための準備した環境のまとめ

最初から、準備していたわけではなく、Claude Code は最初に利用したが、その後は、必要に応じて環境を入れていった。

  • 最初に入れたもの）Claude Code（Pro で契約） / Serena

  • 紆余曲折して辿り着いたデータ解析）DuckDB
    • Claude code に任せてインストール
  • データ解析をしやすくなってから入れたもの）github
    • Claude Code に任せてClone
    • Cloneするためのトークン設定は行う

テーブル影響の解析から実施

1st try

  • 内容：テーブル定義書（CSV）を読み込み、リレーション含め教え込む
  • 結果：参考データを読ませてもいたが、正直、二つ三つテーブル結合するような内容を質問するも結果は正しく回答されず、精度はいまいち。
  • 反省：DBに直接アクセスしたくなかったので、ファイル読み込みで対処させようとしたが、時間がかかった。解析しやすい状態にしなければならないと思い、次の一手を考える

2nd try

  • 内容：テーブル定義書（xml from schema spy）を読み込ませ、社内で流行りのDuckDBを取り寄せる
    • DuckDBの確認
      • 高速な分析：DuckDBはカラムナストレージとベクトル化されたクエリ実行エンジンにより、特に大量データの集計や分析クエリにおいて従来の行ベースのRDBMS (RDSなど) よりも遥かに高速なパフォーマンスを発揮することがあります。
      • ローカルでの実行：DuckDBはアプリケーションのプロセス内で動作し、データもローカルに保持（または外部接続）します。これにより、RDSに接続せずオフラインやローカルリソースを活用した分析が可能になります。
      • データレイク連携：RDSからデータをエクスポートしてParquetなどの形式でS3などに配置し、DuckDBから直接読み込むことで、データレイク分析基盤として活用できます。
  • 結果：多少、データ構成を交えて説明を行うことで、求めている結果が返ってきた。

DuckDB統合情報

schema_integration:
  primary_source: "/Users/name/tmp/schemaspy/database-er-20250827/confidential/test.public.xml"
  analysis_method: "直接XML解析"
  
  enhanced_tables:
    - "enhanced_tables" (863テーブル定義+日本語説明)
    - "enhanced_columns" (9,002カラム詳細+制約情報)
    - "table_relations" (1,806リレーション関係)
  
  legacy_tables:
    - "api_endpoints" (128件のAPI定義)
    - "database_tables" (旧701テーブル構造)
    - "table_columns" (旧7,731カラム詳細)
  
  high_value_queries:
    -- ビジネス重要テーブル
    business_critical: "SELECT * FROM enhanced_tables WHERE table_name ILIKE '%{ 解析したいテーブル }%' OR table_name ILIKE '%{ 解析したいテーブル }%'"
    -- リレーション分析
    relation_analysis: "SELECT parent_table, child_table, foreign_key_name FROM table_relations WHERE is_implied = false"
    -- 影響度ランキング
    impact_ranking: "SELECT table_name, COUNT(*) as relations FROM table_relations GROUP BY table_name ORDER BY relations DESC"

テーブル✖️アプリケーションの解析から実施

1st try

  • 内容：アプリケーションのシステム構成は、APIサーバー一つに、複数のフロントエンドがあるような構成で、常に最新の状態で分析ができるようにしたかったので、リモートアクセスでするようにした
  • 結果：欲しい結果を求めつつ、不明点は質問するようにして、url を指定しつつ、対象コードの学習をしてもらったが、解析がうまくいっていないのか、検討はずれの回答ばかり返ってくる。
  • 反省：Claude にリモートとローカルで解析するならどっちがいい？と尋ねるが想定していた通り、解析をあげようと思うなら、ローカルだった。。

2nd try

  • 内容：git clone で各種リポジトリーを持ってきて解析をする。
    • 解析をする時は、要点を絞って、解析をする。例えば、ECサイトであれば価格調整をするとしたら、などにする。
  • 結果：いままでの知見に対しての回答と合わせて、コードベースから読み取られた忘れていた仕様を見つけてもらうようになる。（あと、こういうことに影響あるよと新規提案も混じる）
  • ふりかえり：アプリケーションコード自体が、xxxxid と xxxxcode は同一であるが、別物と結論づけることもあったが、「わからないことは聞いて」「ステップバイステップにして」「事実に基づいて」と伝えることで、解消していった。

AIエージェントデザインパターン

ここまで実施してきた時に冒頭にあげていた、「LangChainとLangGraphによるRAG・AIエージェント［実践］入門」を読み始め、LangChain/LangGraphデザインパターン定義デザインパターンがあり、この瞬間、「Claudeといままで対話しながら進めてきましたが、この進め方はよかったのだろうか？」と、ふりかえりを始めました。

ふりかえるため、LangChain/LangGraphデザインパターン定義

Claude Code と共に、いままで作り上げてきた内容は、何のパターンに当てはまるのかを確認と評価をする。評価結果によっては、分析方法を見直すように進める。

定義一覧

1. RAGパターン

  • Naive RAG: 単純な検索→生成
  • Advanced RAG: 前処理・後処理付きRAG
  • Modular RAG: モジュール化されたRAG

2. エージェントパターン

  • ReAct: Reasoning（推論）+ Acting（行動）の反復
  • Plan-and-Execute: 計画立案→実行
  • Self-Reflection (Reflexion): 自己評価→改善
  • Multi-Agent Collaboration: 複数エージェント協調
  • Tool Use Agent: ツール使用特化

3. メモリパターン

  • Conversation Memory: 会話履歴保持
  • Entity Memory: エンティティ抽出・記憶
  • Knowledge Graph Memory: 知識グラフ構築

4. ワークフローパターン

  • Sequential Chain: 順次処理チェーン
  • Parallel Execution: 並列実行
  • Conditional Routing: 条件分岐
  • Human-in-the-Loop: 人間介入型

5. 最適化パターン

  • Query Expansion: クエリ拡張
  • Reranking: 再ランキング
  • Contextual Compression: コンテキスト圧縮
  • Ensemble Retrieval: アンサンブル検索

プロジェクト評価

レガシーアプリケーション.md

デザインパターンの定義をもとに解析をますが、プロジェクトは６個ありますが、単に貼り付けるだけでも長くなるので、一つだけ抜粋して紹介。Claudeがレポートにまとめた結果と、自分自身が持ち合わせている知識を照らし合わせても、大体網羅できていると思ったものの、大体なので、何が漏れているのかはこの時点でははっきりしていない。

適用パターン

カテゴリ パターン 適用度 説明
RAG Advanced RAG ✅ 完全 repository-context.md + スキーマ + コード検索
エージェント ReAct ✅ 完全 推論（FK制約分析）→ 行動（Grep検索）の反復
エージェント Tool Use Agent ✅ 完全 Read/Grep/Glob ツール活用
エージェント Self-Reflection ❌ 未適用 自己評価なし
ワークフロー Sequential Chain ✅ 完全 スキーマ分析 → コード分析 → 影響評価
ワークフロー Parallel Execution 🟡 部分 複数ファイルの並列Read
メモリ Knowledge Graph Memory 🟡 部分 FK制約関係のグラフ構造把握

分析プロセス:

1. RAG: repository-context.md から Laravel構成取得
   ↓
2. ReAct: "価格 テーブルのFK制約を調べる" (推論)
   → Grep "価格.*fkey" (行動)
   → "11テーブルがFK参照" (観察)
   ↓
3. Sequential Chain:
   Schema分析 → Model分析 → Controller分析 → 影響評価
   ↓
4. Tool Use: Read で テーブル名・価格.php 読み込み
   ↓
5. 結果統合 → レポート生成

📈 パターン適用度サマリ（全レポート横断）

アプリケーションレポート（6レポート）

パターン 適用率 評価
Advanced RAG 100% (6/6) ✅ 優秀
ReAct 100% (6/6) ✅ 優秀
Tool Use Agent 100% (6/6) ✅ 優秀
Sequential Chain 100% (6/6) ✅ 優秀
Conversation Memory 100% (6/6) ✅ 優秀
Parallel Execution 17% (1/6) ⚠️ 改善余地
Self-Reflection 0% (0/6) ❌ 未適用
Multi-Agent 0% (0/6) ❌ 未適用
Plan-and-Execute 0% (0/6) ❌ 未適用

データベースレポート（4レポート）

パターン 適用率 評価
Advanced RAG 100% (4/4) ✅ 優秀
ReAct 100% (4/4) ✅ 優秀
Tool Use Agent 100% (4/4) ✅ 優秀
Sequential Chain 100% (4/4) ✅ 優秀
Knowledge Graph Memory 100% (4/4) ✅ 優秀
Query Expansion 100% (4/4) ✅ 優秀
Plan-and-Execute 25% (1/4) ⚠️ 改善余地
Self-Reflection 0% (0/4) ❌ 未適用
Multi-Agent 0% (0/4) ❌ 未適用

📊 最終評価

Claude Code

現在のアプローチは基本的には良好（B+評価）ですが、上記3つのパターンを導入することで A+評価に到達できます。特に大規模・複雑なタスクでは効果が顕著です。

Claude からは、できていないことや、改善提案を受けるも、何が悪いのかはさっぱりわからない。
なので、何が悪いのかを教えてもらう。あと、実際に人にもフィードバックをしていただく。

現状の強み from Claude Code

  1. Advanced RAG: 全レポートで適切に活用
  • プロジェクト構成の理解: repository-context.mdから各アプリケーションの技術スタック（Laravel / レガシー / ※一部ぼかしています）を正確に把握
  • データベース構造の理解: PostgreSQLスキーマ + FK制約の全体像を取得
  • 既存実装の把握: コード + スキーマの組み合わせで、価格決定ロジックや認証フローを理解
  1. ReAct: 推論→行動サイクルが確立
  • 段階的な問題解決: 仮説→検証→観察のサイクルで、見落としを防ぎながら分析
  • 動的な調査: 静的な計画ではなく、発見に応じて次の調査対象を決定
  1. Knowledge Graph Memory: DB関係の可視化が優秀
  • テーブル依存関係の全体像: FK制約をグラフ構造で可視化
  • 影響範囲の完全な把握: 中心テーブルから放射状に広がる依存関係を理解
  • データフローの理解: 価格決定やカート処理のデータ流れを追跡
  1. Query Expansion: 影響範囲の自動拡大が効果的
  • 想定外の影響範囲の発見: 初期検索対象から派生的に関連する箇所を発見
  • 固定カラムの発見: FK参照だけでなく、カラム名パターンでの影響も検出

改善すべき点 from Claude Code

  1. Self-Reflection: 全レポートで未適用（品質バラツキの原因）
  • 品質の自己検証: レポート完成後に抜け漏れをチェックできなかった
  • 精度の担保: FK制約の整合性やコード引用の正確性を検証できなかった
  • 継続的改善: 前回の失敗から学んで次回に活かすメカニズムがなかった
  1. Multi-Agent: 並列処理の機会損失
  • 足りないとのこと
    • 並列分析: 6つのアプリケーションを順次分析（非効率）
    • 専門性の発揮: Laravel/Ethna/Reactの各技術に特化した分析ができなかった
    • 時間短縮: 全レポート生成に時間がかかった
  • サブエージェントを作りなさいとの啓示
    • Laravel Agent: Eloquent ORM, Migration に精通
    • React Agent: TypeScript型定義、Component構造に精通
    • Ethna Agent: ActionClass/Manager パターンに精通
  1. Plan-and-Execute: 計画の可視化不足
  • タスク全体の把握: 「次に何をすべきか」が不明瞭
  • 進捗の可視化: どこまで完了したかが分からない
  • タスク漏れの防止: 暗黙的な計画のため、重要な分析を見落とすリスク

人によるフィードバック

貴重なフィードバックをいただく、概要は以下の内容。

  • 知らない機能がある　※事前に要不要の確認はしたものの、認識間違いがあり、漏れていた・・・。
  • データからそのまま出力されるので改修は不要と・・・。

所感

人から頂いたフィードバックと照らし合わせると、以下の観点を追加すると人が実施するレビューに近づけそうな気概しています。

  • "Self-Reflection" がなかったことで、失敗からの学習がなかった
    • おそらく、失敗としているのは、「xxxxid と xxxxcode は同一である」などの指摘を指していると思われるが、正直、同じ指摘をしているわけではないと思っているが、自分の認識と、Claude Codeの認識があっているとは思っていないので、どう改善されるかは試していくのがよい
  • "Multi-Agent" がなかったことで、専門性の発揮ができなかった
    • これは、各々分野を任せることは必要なのだろうと思っているのと、書籍にも同じような話があがっているので、取り入れていく必要がある。
  • "Plan-and-Execute"、正直これは、分析していくうえで、どのように分析するかの計画立ては必要であるが、どういう順番で調査してもらうのか？ということなのか？と、何を教えたらいいのかわからないので、とりあえずの壁打ちが必要。

ネクストアクション

  • 実施すること
    • 足りないと言われた３つ、Self-Reflection、Multi-Agent、Plan-and-Execute を構築した上で再評価を行う
    • RDRAの基本情報構造で関連性を示した上で、解析をしてもらう
  • ここまで実施しての思うところ
    • 中途入社などで新しくチームに参画した方に、どういう業務があり、誰が、いつ、どこで、何を、どのように実施しているのか、そしてそれはなぜ、実行されているのかを、オンボードし続けなければならないんだろうと。これが整えば、毎回人に教えるということが減り、システム構造のここを教えてや、ドキュメント制作などは捗るような気がしてきました。

Discussion