未知のレガシーシステムにClaude Codeを持ち込んで学んだこと——人間の主体性と仕組みの両輪
フリーランスエンジニアのMasuyama氏が、数ヶ月にわたって自分にとって全く未知の大規模レガシーシステムにClaude Codeを導入した実践記録だ。失敗の記述と、それを受けて構築した開発パイプラインの詳細が両方書かれており、現場に直結する内容になっている。
出典: 未知のレガシーシステムをClaude Codeで開発して学んだこと
要点 (事実のみ)
- テストの一部が壊れており、型チェックも落ちているレガシーシステムに対し、数ヶ月間Claude Codeで業務開発を行った
- 「理解が浅いままAIに任せる」「チケットの要件を文字通り実装する」「AIに全部任せて放置する」という3つの失敗パターンを経験した
- 失敗を受けて、ドメイン×ファイル対応表・URL-コントローラ紐づけ・認証認可の仕組みをClaude Code Skillsとしてマッピング化した
- 「親セッションは一行もコードを書かない」リーダー原則を設け、tmux子セッションでBE/FEを並列実装する構成を採用した
- 設計書作成→レビュー+ハンドオフ→並列実装→最終検証という4ステージパイプラインを構築し、各ステージ終わりに人間チェックポイント（CHK1/CHK2）を設けた
- レビューにはClaude Code以外に別モデル（Codex CLI）も使い、同一バイアスによる見落としを防いだ
徐 聖博の見解
この記事を読んで率直に感じたのは、「自分のプロジェクト」と「他人のシステム」の間には、AIの能力とは無関係な根本的な非対称があるということだ。私自身もシンシアで受託開発を担当するエンジニアと日常的に仕事をしている。顧客のシステムに入るとき、コードの文脈を知っているのは常に顧客側であり、私たちは後から追いかける立場になる。その非対称を埋めるのは人間の理解力であって、AIの探索能力ではない。Masuyama氏が指摘する「AIが書いたコードは動くが、なぜこう書いたのかを自分が説明できない」という状態は、受託開発の現場では致命傷になる。レビュアーへの説明責任は人間が引き受けるしかない。
パイプライン設計で特に目を引いたのは、セッション分離とハンドオフ文書の組み合わせだ。「設計書そのものを渡すのではなく、相手側がどう実装するかの視点で再構成した文書を使う」という発想は、通常のチームのブリーフィングと同じ構造を取っている。AIをチームメンバーとして扱うなら、情報の渡し方も同様に設計する必要がある、という当然の帰結だ。
一方で「チケットの要件を疑う」点は、AI以前の問題として受託開発の本質を突いている。私がシンシアで受託案件を扱うとき、要件定義フェーズにどれだけ時間を使うかがその後の品質を決める。AIが実装を高速化してくれるほど、要件の曖昧さが増幅されて出力される速度も上がる。AIの速度を活かすためにこそ、上流の人間の介在は省けない。
マッピングを「日々アップデートし続けた」ことでClaude Codeの出力精度が上がっていったという記述も重要だ。これはコンテキストの品質管理そのものであり、AIの性能差より運用設計の差が結果を左右することを示している。
(編集レンズ: 実装・運用視点 / 発注側・中小企業・開発実務への含意)
