既存プロジェクト向けVibeCodingガイド

このドキュメントは、既存のプロジェクトにVibeCoding（>85%のAI支援による開発）を適用する方法をガイドします。既存のコードベースへのAIの統合は、新規プロジェクトよりも体系的で慎重なアプローチが必要です。

既存プロジェクトにVibeCodingを適用する際の課題

• 型付けの欠如: 多くの古いコードベースは、純粋なJavaScript、型ヒントのないPHP、型アノテーションを使用しないPythonを使用しています。
• 一貫性のない構造: プロジェクトの各部分が異なる規約に従っていいる可能性があります。
• ドキュメントの不足: ビジネスルールやシステムアーキテクチャに関するドキュメントが不足しています。
• 「魔法の」コード: 多くの古いフレームワークは暗黙の規約（Convention over Configuration）に依存しており、AIが理解するのが困難です。
• 変更への恐れ: 特に十分なテストがない場合に、動作中のコードを変更することへの懸念があります。

AIエージェントをサポートするIDEの選択

エージェントモードをサポートするIDEであれば、VibeCodingを実行できます。 重要なのは、IDEの種類ごとにコンテキスト（ユーザー ルール、プロジェクト ルール、ドキュメントなど）を設定する必要があることです。

開始にあたり推奨されるIDEは以下の通りです：

• VSCode + AugmentCode: 14日間のトライアルを利用可能。インライン アシストと補完はまだ改善の余地がありますが、エージェントは非常に優れています。
• Cursor: 開始に適した良い選択肢です。
• Windsurf: 開始に適した良い選択肢です。

コードベースの分析と準備戦略

1. コードベースを理解する

• プロジェクトマップを作成する:
  • すべての主要なモジュール/コンポーネントをリストアップする
  • データフローとビジネスプロセスを理解する
  • 最も複雑なコンポーネントを特定する
• コード品質を評価する:
  • テストカバレッジを確認する
  • 型付けの使用度を評価する
  • 理解しにくい/複雑なコード部分を特定する

2. AI向けのドキュメントを準備する

• AI用の「コードベースハンドブック」を作成する。 内容：
  • ディレクトリ構造とコンポーネントの責任
  • 使用されている命名規則
  • 主要な処理フローと重要なビジネスルール
  • 適用されているパターン
• 既存のコードベースからサンプルスニペット集を作成し、参照資料とする

段階的な統合戦略

1. 安全な部分から始める

• 「既存コードに触れない」タスク:
  • ドキュメント、コメント、JSDoc/PHPDocを作成する
  • 既存モジュールのテストを作成する
  • 既存APIのスキーマバリデーションを作成する
• 分離された新機能:
  • 既存コードへの依存が少ない新機能を選択する
  • これらの機能に完全にVibeCodingを適用する

2. 部分ごとに改善する

• 「ストラングラーフィグ」パターン (Strangler Fig Pattern):
  • 古いコードをVibeCodingで開発された新しいレイヤーでラップする
  • 古いコードの部分を徐々に置き換える
• 「並行」戦略:
  • 古いコードと並行して新しいコードを作成する
  • 完全に置き換える前にA/Bテストを実施する

3. 徐々に型を追加する

• TypeScript (JavaScript):
  • allowJs: true を使用して .js を .ts に徐々に変換する
  • any から始めて、徐々に型を改善する
  • JSファイル内でJSDocを使用して型サポートを得る
• PHP:
  • 公開メソッドに型ヒントを追加し始める
  • 関数のシグネチャを変更できない場合はDocBlockを使用する
• Python:
  • 必要な場合に # type: ignore を使用して型ヒントを追加する
  • スタブファイル (.pyi) を使用して古いコードに型を補足する

言語/フレームワーク別のガイドライン

JavaScript/TypeScript (Node.js, フロントエンド)

• Express.js (古い):
  • Request/Response用の型インターフェースを作成する
  • コントローラーを機能ごとに別々のファイルに分割する
  • 直接コーディングする代わりに、バリデーションにミドルウェアを使用する
• React (古い):
  • クラスコンポーネントを関数コンポーネント+フックに変換する
  • TypeScript + PropTypesを並行して使用し、徐々に変換する
  • カスタムフックを使用してロジックをコンポーネントから分離する
• Vue 2:
  • プラグイン @vue/composition-api を使用してComposition APIを使用する
  • Vuex/コンポーネントにJSDoc/TypeScriptを追加する

PHP

• Laravel (古いバージョン):
  • Model/Controller/Serviceに型ヒントを追加する
  • リクエスト/レスポンス用にDTO (Data Transfer Objects) を作成する
  • 複雑なロジックをサービスまたはアクションに抽出する
• レガシーPHP:
  • 古い関数用に（型付けされた）現代的なファサードを作成する
  • 古いロジックを明確な構造を持つクラスにラップする

Python

• Django (古いバージョン):
  • モジュールごとに型付けを追加する
  • 大きなビューをより小さなビューに分割する
  • ビジネスロジックをビューからサービスに移動する
• Flask:
  • Blueprintsを使用してモジュラーパターンにリファクタリングする
  • データバリデーション用にPydanticモデルを追加する

既存プロジェクトで作業する際のAIへのプロンプト例

1. コードベースの分析とマッピング

以下のコードベースを分析し、以下を示す「プロジェクトマップ」の作成を手伝ってください：
1. ディレクトリ構造と主要コンポーネント
2. コアとなるデータフロー
3. 使用されているデザインパターン
4. 現在のアーキテクチャの長所と短所

[主要なファイル/ディレクトリの一部をここにコピー＆ペースト]

2. 型のないコードに型を追加する

以下のJavaScriptコードにTypeScriptの型を追加するのを手伝ってください。ロジックは完全に維持し、以下のみを追加してください：
1. 変数、パラメータ、戻り値の型
2. オブジェクト用のInterface/Type
3. 複雑なロジックを説明するために必要な場合のJSDoc

[変換したいソースコードをここにコピー＆ペースト]

3. 機能に基づいてリファクタリングする

以下のファイルを技術レイヤーによる構成から機能モジュールによる構成にリファクタリングするのを手伝ってください。
現在、これらは別々のディレクトリ（controllers/, services/, models/）にありますが、「user」機能に基づいてグループ化したいです。

[関連ファイルをリストアップ]

既存プロジェクトにVibeCodingを適用する際の原則

• 動作の維持: リファクタリング時に機能が以前と同じように動作することを確認する
• 小さなステップ: 制御可能な小さな部分ごとにVibeCodingを適用する
• テスト先行、リファクタリング後: 変更前に古いコードのテストを作成する
• 古いコードから学ぶ: 既存のビジネスロジックを明確に理解する
• フレームワークに逆らわない: 新しい構造を強制するのではなく、古いフレームワークの規約と連携する
• 変更の文書化: すべての決定、特にアーキテクチャ上の理由を記録する

ケーススタディ：VibeCodingによるLaravel 5.xからLaravel 10+への近代化

ステップ1：分析と準備

• モデルとそのリレーションシップのリストを作成する
• リファクタリングが必要な大きなコントローラーを特定する
• 複雑なビジネスルールを理解する
• 古くなったパッケージを確認する

ステップ2：段階的な強化戦略

• モデルに型ヒントを追加する
• リクエスト/レスポンス用にDTOを作成する
• カスタムバリデーションルールを抽出する
• コントローラーからサービスへロジックを移動する
• Bladeビューを部分的にリファクタリングする

ステップ3：AIを活用した支援

• モデルのリレーションシップを自動分析する
• 既存のルートに基づいてOpenAPI記述を生成する
• テストカバレッジを改善する
• コントローラーをResource/APIResourceパターンに変換する

---

覚えておいてください：近代化プロセスは短距離走ではなくマラソンです。一歩ずつ進め、徹底的にテストし、古いコードと新しいコードの間で一貫性を保ちましょう。