既存プロジェクトへAIコーディングを導入するときは、最初の依頼を「コードを書いて」ではなく「今の仕組みと確認方法を調べて」にすると進めやすくなります。
既存の設計、命名規則、テスト、未完了の変更を把握してから、小さい修正を一つ任せます。
新規アプリのデモが作れることと、運用中のコードを直せることでは必要な確認が違います。
ここでは、AIに既存のリポジトリを読ませる際の準備と、依頼文、差分の確認方法を整理します。
最初に作業前の状態を確認する
Gitで管理している場合は、作業するリポジトリで次のコマンドを実行し、現在のブランチと未コミットの変更を確認します。
git status --short --branch表示された変更が自分の作業なのか、別の人やツールの作業なのか分からない場合は、そのままAIに整理させず由来を確認します。
新しいブランチを作るだけでは未コミットの変更が消えたり分離されたりするわけではありません。
既存の変更を把握し、今回触れるファイルを決めましょう。
コマンドの意味はGit公式のgit statusで確認できます。
Gitを使っていないプロジェクトなら、少なくとも作業前のコピーを別の場所に残し、戻せる状態を作ります。
初回は構成と実行方法を調べてもらう
リポジトリへ接続した直後は、README、依存関係、実行用スクリプト、テスト、プロジェクト固有の指示を調べてもらいます。
次のように、最初の段階では編集しないことを具体的に伝えます。
このプロジェクトの構成を調べてください。
現時点ではファイルを変更しないでください。
確認してほしいこと：
1. アプリの起点と主要な処理の流れ
2. 起動・ビルド・テストの実行方法
3. 今回直したい検索画面に関係するファイル
4. プロジェクト内の指示・設計上の制約
5. 調査しても分からなかった点
回答には根拠となるファイル名を添えてください。「Reactのようです」など技術名だけの回答より、どのファイルからどの処理を呼ぶのかが分かる回答を求めます。
推測と確認できた内容を分けてもらうと、設定ファイルを見落としている場合にも気付きやすくなります。
最初の修正は成功条件を小さく決める
最初から大規模なリファクタリングを依頼するより、一つの再現できる不具合を選びます。
たとえば「検索結果が0件のときに空白画面になる」という問題なら、0件時の表示、通信エラー時の表示、通常時の表示を分けて成功条件にします。
検索結果が0件のとき、空白ではなく案内を表示してください。
完了条件：
- 0件なら「該当する結果がありません」と表示する
- 1件以上なら既存の一覧表示を維持する
- 通信エラーを0件として扱わない
- 今回の変更で必要な確認を実行し、結果を示す
変更前に、関係するファイルと実装方針を簡潔に説明してください。
新しい依存関係を追加する場合は、その理由も示してください。これは依頼文の例です。
画面文言や要件は実際のプロジェクトに合わせます。
Claude Codeの公式ベストプラクティスでも、探索と計画、実装、検証を分け、確認できる基準を与える進め方が紹介されています。
実行してよい範囲を作業に合わせる
コードの読み書き、ローカルテスト、外部サービスの変更、デプロイは別の操作です。
たとえば下書き作成の検証であれば、テスト環境の下書き保存までに範囲を絞り、本番公開の操作を同じ依頼へ混ぜないようにします。
実際の認証情報をコード例やチャットへ貼らず、プロジェクトで定めた環境変数やシークレット管理を使います。
ログに値が出るコマンドを避けるなど、AIに渡す情報だけでなく実行結果に含まれる情報も確認してください。
変更後は差分と動作を別々に見る
AIから「完了しました」と報告されたら、実際の差分を確認します。
Gitでは次のコマンドで変更量と内容を見られます。
git diff --stat
git diff
git diff --cached
git status --shortgit diffだけでは、ステージ済みの変更や新規の未追跡ファイルをすべて確認できません。
ステージ済みはgit diff --cached、新規ファイルはgit statusとファイル内容で確認します。
詳細はgit diffの公式説明を参照してください。
差分では、目的に関係ないファイルの削除、設定の変更、依存関係の追加がないか見ます。
動作では0件・正常結果・通信エラーを実際の確認手順に沿って試します。
コードが短くなったことと、不具合が直ったことを同じ評価にしないようにしましょう。
テスト結果はコマンドと結果で受け取る
「テスト済み」という一言だけでなく、実行したコマンド、成功・失敗、実行できなかった確認を報告してもらいます。
作業前から失敗しているテストがある場合は、それと今回の変更による失敗を分けます。
画面操作や外部連携をまだ試していないなら、その範囲は未確認として残します。
AIが書いたテストが同じ実装の前提をなぞっているだけでないか、実際に起きた不具合を再現できるかも確認します。
次の依頼へ引き継ぐ情報を残す
変更の目的、修正ファイル、検証方法、未解決の点を短く残します。
会話の長さだけに頼らず、READMEやプロジェクトで決めた指示ファイルへ必要な情報を整理すると、次の作業でも前提を揃えやすくなります。
既存プロジェクトでのAI活用は、一度に任せる範囲を増やすより、調査の根拠と変更の結果を確認できる状態を作ることから始めます。
小さい修正で手順を揃えれば、次の機能追加にも同じ進め方を使えます。
