はじめに

数週間前から業務でコーディングエージェント系の生成AIを使い始めました。これまではChatGPTなどのチャット系のAIを使用していましたが、本格的な開発支援ツールの導入により、レガシーシステムの移行に取り組んでいます。

前回の記事「AIコーディングを活用したレガシーコード適応への道2」では、レガシーコード改修においてマイクロマネジメント的な手法がベストであると記載しました。しかし、その後の実践を通して新たな発見があり、心境の変化というか、より効果的なアプローチを見つけることができました。今回はその内容について記載します。

プロジェクト概要

現在の技術環境

Java 8
jQuery
Glassfish
VB.net 2010

抱えている課題

現状のシステムは以下の課題を抱えています：

VB.net側で型定義が存在せず、全てがObjectマッピングで処理されている
APIのエンドポイントすら共通化されておらず、各機能で個別実装となっている
レガシーな技術スタックによる保守性の低下

移行の目標と戦略

現段階の目標：

VB.netの型なしObjectマッピングから、型安全なAPIへの移行

最終目標：

VB.netタブレットアプリケーションをReact Webアプリケーションへ移行

段階的アプローチを選択した理由：
当初は直接的な移行を試みましたが、Object型の問題によりAPIなどの移行がスムーズに進まなかったため、段階を踏むアプローチに変更しました。

使用したAIツール

Claude Code（https://docs.anthropic.com/ja/docs/claude-code/overview）
GitHub Copilot（https://docs.github.com/ja/copilot）
- VB.netのサポートを考慮し、Cursorではなくエディタとの親和性を優先

プロジェクトファイル活用による劇的な改善

転換点となった発見

従来のClaude CodeだけでKiro風をやる（Claude Codeスラッシュコマンドに登録した /kiro コマンドを使った要件定義から実装までの一連の開発手法）で期待した結果が得られなかった経験から、新たなアプローチを試行しました。

転換点となった気づき：

生成されたコードや仕様書で不足・誤解している内容をすべてCLAUDE.md（プロジェクトファイル）にClaude Codeを利用して記載
このアプローチにより、出力内容が急激に安定化
Claude.mdに記載された内容をAIが「自明のもの」として処理するように

本質的な理解：
この手法は「新人がチームに参加する際のルール定義」と同じプロセスでした。個人の好みで開発していた状況から、AIに対する厳密なルール定義の重要性を認識しました。

この手法を試したきっかけは、以下のXのポストからプロジェクトファイルへの書き込みが不足しているのではないかと気づいたためです。
https://x.com/suthio_/status/1948230666363265285

実践から得られた具体的成果

劇的な改善結果：

手修正の頻度が80%以上減少：従来は生成コードの大部分に手修正が必要だったが、ほぼそのまま利用可能に
コンパイルエラーが90%以上減少：型安全性を重視したルール定義により、VB.NET固有の制約違反が激減
開発速度が約3倍向上：反復的な修正作業が不要になり、新機能開発に集中可能

プロジェクトファイルの効果的な構成例：

技術的制約を明確に定義：

' VB.NET Development Guidelines
' Visual Studio 2010 Compatibility
' - Framework: .NET Framework 4.0
' - 文字列補間は使用不可（String.Format()を使用）
' - null ではなく Nothing を使用
' - AndAlso, OrElse を使用（短絡評価）

アーキテクチャパターンの明示：

' API Mapping Conventions
' Java Entity → VB.NET Entity
' Java ObjectResponse<T> → VB.NET ObjectResponse(Of T)
' Java "error" property → VB.NET "isError" property（予約語回避）

コーディング規約の統一：

' Development Best Practices
' - 既存実装のチェック：重複実装を回避
' - 変数命名：汎用的な"response"ではなく説明的な名前を使用
' - エラーハンドリング：BasicResponseクラスで統一

実践のポイント：

作成されたコードが意図と合わない場合は、即座にプロジェクトファイルに記載
継続的な誤差の修正により、AI出力の精度が段階的に向上
反復的なフィードバックループが品質向上の鍵

段階的タスク分割の実践例

以下は /kiro コマンドで実際に効果を発揮したプロンプトの構造です。

段階的タスク分割プロンプト：

@[プロジェクトパス]/Form/[フォーム名].vb のAPIを型にマッピングしてほしいです。

手順：
1. まずは使用されているAPIを洗い出してください
2. APIがない場合は適切な場所に作成してください
3. 作成したAPIで利用するクラスがない場合は、必要な場所に作成してください
4. 最後に対象ファイルをAPIに置き換えてください
5. Objectからの要素取得ではなく、プロパティでの取得に変更してください

目的：Object型を排除し、型安全性を確保する

効果：

明確な段階分けにより、各ステップでの検証が可能
方向性のズレが発生した場合の軌道修正が容易
Object型排除という明確な目的設定

カスタムコマンドの作成と活用

繰り返し作業の効率化のため、効果を確認したプロンプトをカスタムコマンド化しました。

コマンドの目的：
VB.NETファイルのObject型使用箇所を型安全なAPIクラスに置き換える汎用処理

3段階の実行フェーズ：

API使用状況の洗い出し：Object型使用箇所と必要なAPIクラスの特定
不足クラスの特定と作成：既存実装のチェックと重複実装の回避
型安全な置き換え実装：コンパイル時型チェックの有効化

使用方法：

/api-type-mapping [対象VB.NETファイルパス]

効果：

一定の品質を保ちながら反復作業を大幅に効率化
最小修正で既存の動作を保持
Object型排除によるコンパイル時型チェックの有効化

失敗から学んだ重要な教訓

`/init` コマンドの限界と手動改善の必要性

実践を通じて、Claude Code の /init コマンドで自動生成されるプロジェクトファイルには限界があることが判明しました。

自動生成の課題：

不完全な情報：複雑なプロジェクト構造を完全に理解できない場合がある
レガシーコードの影響：既存コードの問題をそのまま「仕様」として解釈してしまう
管理ファイルの複雑さ：プロジェクトの管理ファイルが増えるほど、適切な解析が困難

初期の失敗パターンと対策

典型的な失敗パターン：

問題の原因：初期は单純にAIに「レガシーコードをモダン化して」と依頼
発生した問題：AIが「現状のコードが仕様」と誤解し、同様のパターンを繰り返すことが頻発
具体例：Object型を使った既存コードを見本として、新しいコードでも同じパターンを採用

効果的な解決策：

重要な発見：プロジェクトの「現状」ではなく、「どのように修正したいか」を明示的に定義することの重要性

実践的なアプローチ：

レガシーコードの問題点を「改善すべき課題」として明記
目指すべき実装パターンを具体例で示す
AIが既存のコードに引っ張られないよう、明確な方向性を提示
「どう修正したいか」を意図と異なる出力が発生した時点で即座にプロジェクトファイルに記載

レガシーコード改修でのAI活用のポイント

段階的なタスク分割：大規模な要件定義よりも小さな単位での確実な改善
明確な目的設定：Object型排除など、具体的で測定可能な目標
継続的なフィードバック：意図と異なる出力は即座にプロジェクトファイルに反映

実証されたベストプラクティス

今回の実践から、「プロジェクトファイルを育てる + Claude CodeだけでKiro風をやる」 が現時点でのベストプラクティスであることが実証されました。

Kiro駆動開発については公式サイトで詳細を確認できます。

プロジェクトファイルを育てるアプローチ

基本的な流れ：

/initコマンドでベースを生成
実際の開発で発生した問題を継続的に記録
AIの誤解や期待と異なる出力を即座にフィードバック
プロジェクト固有のルールや制約を段階的に蓄積

Kiro駆動開発との組み合わせ効果：

要件定義段階でプロジェクトファイルの内容を参照
実装段階で新たに発見したルールをプロジェクトファイルに追加
次回の開発サイクルでより精度の高いAI支援を実現

継続的改善がもたらす長期的価値

プロジェクトファイルの詳細化による効果：
従来から /init コマンドで自動生成したプロジェクトファイルに必要な内容を追記する運用は行っていましたが、今回の実践でより詳細で具体的な内容を記載することの重要性を強く実感しました。

具体的な改善効果：

単純な技術仕様だけでなく、「なぜそうするのか」という意図の明記
AIが迷いやすいポイントの事前説明
プロジェクト固有の制約や方針の詳細な記述

知識資産としての価値：
「プロジェクトファイルの継続的改善」というアプローチは、単発の開発タスクを超えて、長期的なプロジェクトにおいて蓄積される知識資産としての価値を持つことが実証されました。

まとめ

レガシーシステムのモダン化という複雑な課題に対して、AIツールと人間の協働による新しいアプローチの可能性が明確になりました。

重要な発見：

プロジェクトファイルの「育成」による劇的な開発効率向上
手修正頻度80%減、開発速度3倍向上という具体的成果
AIを「チームメンバー」として適切にオンボーディングすることの重要性

今後の課題：
この手法をさらに多くのレガシープロジェクトで検証し、汎用的なベストプラクティスとして確立していくことが次のステップとなります。