Antigravity × AIペアプログラミングで初心者が陥りやすい10の落とし穴と回避法

AIペアプログラミングで「なぜかうまくいかない」を解消する

「AIの提案がいつも的外れ」「修正を重ねるほどコードが壊れていく」「結局、自分で書いた方が早かった」——AIペアプログラミングを始めたばかりの頃、多くの人がこうした壁にぶつかります。

Antigravity のAIエージェントは、正しく付き合えば開発の心強いパートナーになります。裏を返せば、うまくいかないときにはたいてい共通した原因が潜んでいます。私自身も通ってきたつまずきを10のパターンに整理し、それぞれの回避法を添えていきます。

落とし穴 1: プロンプトが曖昧すぎる

最も多い失敗パターンが、AIへの指示が漠然としすぎるケースです。

ありがちな例:

// ❌ 曖昧なプロンプト
「このコードを良くして」
「バグを直して」
「もっと速くして」

AIは超能力者ではありません。「良くする」とは何を指すのか——可読性なのか、パフォーマンスなのか、セキュリティなのか——を明確にする必要があります。

回避法:

// ✅ 具体的なプロンプト
「この関数のループ処理を Map を使ったO(1)ルックアップに変更し、
 1000件以上のデータでのパフォーマンスを改善してください。
 既存のテストが通ることも確認してください。」

プロンプトには何を、なぜ、どのように の3要素を含めることを意識しましょう。Antigravity のAIエージェントは詳細な指示ほど正確な結果を返してくれます。

落とし穴 2: コンテキストを与えないまま作業を始める

Antigravity のAIは、プロジェクト全体を最初から把握しているわけではありません。コンテキストなしでコードを書かせると、プロジェクトの規約やアーキテクチャに合わない提案が返ってきます。

回避法:

Antigravity では AGENTS.md や Knowledge Items を活用して、プロジェクトの前提情報をAIに共有できます。

<!-- AGENTS.md の例 -->
# プロジェクトルール
- フレームワーク: Next.js 16 (App Router)
- 言語: TypeScript (strict mode)
- スタイル: Tailwind CSS v4
- テスト: Vitest + Playwright
- 命名規則: camelCase（変数）、PascalCase（コンポーネント）

作業開始前に @ファイル名 でプロジェクト設定ファイルや関連コードを参照させると、的確な提案が返ってくるようになります。詳しくは Antigravity 完全入門ガイド 2026 も参考にしてみてください。

落とし穴 3: AIの提案をレビューせずにそのまま採用する

「AIが書いたコードだから正しいはず」という思い込みは危険です。AIは文法的に正しいコードを生成しますが、ビジネスロジックの正確性や、エッジケースの考慮が不十分なことがあります。

ありがちな例:

// AIが生成した一見正しいコード
function calculateDiscount(price: number, discount: number): number {
  return price * (1 - discount / 100);
}
// ⚠️ 問題: discount が100を超える場合や負の値のバリデーションがない

回避法:

// ✅ バリデーションを追加した改善版
function calculateDiscount(price: number, discount: number): number {
  if (price < 0) throw new Error("Price must be non-negative");
  if (discount < 0 || discount > 100) {
    throw new Error("Discount must be between 0 and 100");
  }
  return price * (1 - discount / 100);
}
// 期待する出力: calculateDiscount(1000, 20) → 800

AIの生成コードは必ず 差分を確認 してからコミットしましょう。Antigravity の Diff View を使えば、変更箇所をひと目で確認できます。

落とし穴 4: 一度に大量の変更を依頼する

「ユーザー認証機能を一から作って」のように、大きなタスクを一気に投げるのは失敗のもとです。AIの出力が長くなるほど、後半の品質が下がりやすくなります。

回避法:

タスクを小さな単位に分割し、段階的に進めましょう。

// ✅ 段階的なアプローチ
Step 1: 「ユーザーモデルのスキーマを定義して」
Step 2: 「サインアップAPIエンドポイントを作成して」
Step 3: 「パスワードハッシュ化とバリデーションを追加して」
Step 4: 「ログインAPIとJWTトークン発行を実装して」
Step 5: 「認証ミドルウェアを作成して」

1回のやりとりで 1つの責務 に集中させることで、各ステップの品質を高く保てます。

落とし穴 5: エラーメッセージを貼り付けるだけで質問する

エラーが出たときに、スタックトレースをそのまま貼り付けて「これを直して」と依頼するケースです。AIはエラーの文面だけでは、根本原因を特定しにくい場合があります。

回避法:

エラーメッセージに加えて、以下の情報を添えましょう。

// ✅ 効果的なエラー報告
「以下のエラーが発生しました。

エラー: TypeError: Cannot read properties of undefined (reading 'map')

発生箇所: src/components/UserList.tsx の 42行目
再現手順: ユーザー一覧ページにアクセスし、APIレスポンスが空の場合に発生
期待する動作: 空のリストが表示される
実際の動作: 白画面になる」

何をしたときに、どこで、何が起きたか の3点を伝えると、AIは適切な修正案を提示できます。

落とし穴 6: AIとの会話が長くなりすぎる

1つのチャットセッションで延々と修正を繰り返すと、コンテキストが膨張し、AIの応答精度が低下していきます。

回避法:

30ターン以上 になったら新しいセッションを開始する
現時点の状態をまとめてから新セッションに引き継ぐ
Antigravity の Auto-continue 機能を活用しつつも、区切りのよいタイミングでリセットする

// 新セッション開始時のプロンプト例
「認証機能の実装を進めています。現在の状態:
- サインアップAPI: 完成（src/api/auth/signup.ts）
- ログインAPI: 完成（src/api/auth/login.ts）
- 認証ミドルウェア: 未着手
次のステップとして認証ミドルウェアを実装したいです。」

こまめにリセットすることで、常にフレッシュなコンテキストで作業できます。

落とし穴 7: テストを後回しにする

「まず動くものを作って、テストは後から」という進め方は、AIとの開発でも悪手です。テストなしでは、AIの修正が別の箇所を壊していることに気づけません。

回避法:

AIにコードを書かせるときは、同時にテストも生成させましょう。

// ✅ コードとテストを同時に依頼する例
// src/utils/formatCurrency.ts
export function formatCurrency(amount: number, locale = "ja-JP"): string {
  return new Intl.NumberFormat(locale, {
    style: "currency",
    currency: locale === "ja-JP" ? "JPY" : "USD",
  }).format(amount);
}
 
// src/utils/formatCurrency.test.ts
import { describe, it, expect } from "vitest";
import { formatCurrency } from "./formatCurrency";
 
describe("formatCurrency", () => {
  it("日本円のフォーマット", () => {
    expect(formatCurrency(1500)).toBe("￥1,500");
  });
  it("米ドルのフォーマット", () => {
    expect(formatCurrency(29.99, "en-US")).toBe("$29.99");
  });
  it("0円の場合", () => {
    expect(formatCurrency(0)).toBe("￥0");
  });
});
// 期待する出力: すべてのテストがパス

テストがあることで、後からのリファクタリングも安心して進められます。プロンプト設計の基本について、より深く学びたい方にはプロンプトエンジニアリング実践ガイドも役立つでしょう。

落とし穴 8: 生成されたコードの依存関係を確認しない

AIが提案するコードには、プロジェクトにインストールされていないライブラリが含まれていることがあります。そのまま実行して「モジュールが見つからない」エラーに悩むケースは少なくありません。

回避法:

# AIがコードで使用しているパッケージの確認
# 例: AIが zod を使ったコードを生成した場合
cat package.json | grep zod
# 出力がなければインストールが必要
npm install zod
# 期待する出力: added 1 package

AIにコードを生成させたら、import 文を確認し、未インストールのパッケージがないかチェックする習慣をつけましょう。Antigravity のターミナル統合機能を使えば、その場でインストールコマンドを実行できます。

落とし穴 9: バージョン管理を怠る

AIとの反復的な開発では、「さっきのバージョンの方がよかった」と思うことが頻繁にあります。こまめにコミットしていないと、良い状態に戻せなくなります。

回避法:

AIとの作業中は 機能単位で小さくコミット する
Antigravity の Checkpoints 機能を活用して、いつでもロールバックできる状態を保つ
ブランチを切ってから実験的なAI提案を試す

# 実験的な変更を試す前に
git checkout -b feature/ai-experiment
# AIと作業 → うまくいったらマージ
git checkout main
git merge feature/ai-experiment
# うまくいかなかったら破棄
git checkout main
git branch -D feature/ai-experiment

より高度なバージョン管理テクニックに興味がある方は、Antigravityでバイブコーディングの生産性を10倍にする実践テクニックでも詳しく解説しています。

落とし穴 10: AIに頼りすぎてスキルが停滞する

最後の落とし穴は、技術的な判断をすべてAIに委ねてしまうことです。AIは優れたツールですが、アーキテクチャの設計判断やビジネスロジックの決定は、開発者自身が行うべき領域です。

回避法:

AIの提案を受けたら「なぜこのアプローチなのか」を理解してから採用する
週に1回は、AIなしでコードを書く時間を設ける
AIの生成コードを読み解くことを、学習の機会と捉える

// ✅ 学びを深めるプロンプト例
「この関数をリファクタリングしてください。
 また、なぜその方法を選んだのか理由も説明してください。」

AIを「考えてくれる存在」ではなく「一緒に考えるパートナー」として活用する姿勢が、長期的なスキル成長につながります。

まとめ

AIペアプログラミングの落とし穴は、そのほとんどが「AIとのコミュニケーション方法」に起因しています。プロンプトを具体的にする、コンテキストを適切に共有する、タスクを小さく分割する——これらの基本を押さえるだけで、Antigravity との共同作業は驚くほどスムーズになります。

完璧なプロンプトを最初から書ける人はいません。大切なのは、失敗パターンを知った上で少しずつ改善していく姿勢です。本記事で紹介した10のポイントを意識しながら、ぜひ日々の開発に取り入れてみてください。

AIを活用した生産性向上の具体的なテクニック集は「Antigravity 生産性を上げる10の必須テクニック」（著者: Antigravity Lab）でも紹介していますので、あわせてご覧ください。

Antigravity × AIペアプログラミングで初心者が陥りやすい10の落とし穴と回避法

AIペアプログラミングで「なぜかうまくいかない」を解消する

落とし穴 1: プロンプトが曖昧すぎる

落とし穴 2: コンテキストを与えないまま作業を始める

落とし穴 3: AIの提案をレビューせずにそのまま採用する

落とし穴 4: 一度に大量の変更を依頼する

落とし穴 5: エラーメッセージを貼り付けるだけで質問する

落とし穴 6: AIとの会話が長くなりすぎる

落とし穴 7: テストを後回しにする

落とし穴 8: 生成されたコードの依存関係を確認しない

落とし穴 9: バージョン管理を怠る

落とし穴 10: AIに頼りすぎてスキルが停滞する

まとめ

お読みいただきありがとうございます

関連記事