取り組みの背景 — 「なぜAntigravityを使っているのに遅い」と感じるのか
Antigravityを導入した直後は感動するほどの速さを体験できます。しかし数週間が経つと「なんとなく遅い」「コンテキストが迷子になる」「同じ修正を何度もお願いしている」という感覚に陥るエンジニアは少なくありません。
これはAntigravityの問題ではありません。ワークフローの設計が、AIの能力を引き出す構造になっていないことが原因です。
対象読者：Antigravityを日常的に使っているが、さらなる速度向上を求めているエンジニア・個人開発者
1. コンテキストウィンドウを「資産」として管理する
1-1. コンテキストが「汚染」されるメカニズムを理解する
Antigravityのコンテキストウィンドウは有限です。1つのセッションで多くのファイルを開き、長い会話を続けると、AIは「何が重要な情報か」を判断しにくくなります。これをコンテキスト汚染と呼びます。
コンテキスト汚染が起きているサインには以下があります。
- 「さっき言ったこと忘れた？」と感じる修正指示が増える
- AIが関係のないファイルを編集しようとする
- 同じ質問をしても回答の品質にばらつきが生じる
- レスポンスが明らかに遅くなる
対策の基本は「セッションをこまめに分割する」ことです。1つのセッションで複数の機能実装をまたがないようにしましょう。
1-2. セッション設計の原則
効果的なセッション設計の基本原則は「1セッション = 1つの明確な目標」です。
# 良い例: セッションの目的を明確に絞る
# セッション1: ユーザー認証APIの実装
# セッション2: フロントエンドのログインUIの実装
# セッション3: E2Eテストの追加
# 悪い例: 1つのセッションで何でもやろうとする
# セッション1: 認証API + ログインUI + テスト + リファクタリング + バグ修正セッション開始時に目標を明確に宣言する習慣をつけましょう。
このセッションでは「ユーザープロフィール更新APIエンドポイントの実装」に集中します。
関連ファイル: src/api/users.ts, src/types/user.ts, tests/api/users.test.ts
1-3. ファイルコンテキストの戦略的制御
Antigravityにどのファイルを読ませるかを意識的にコントロールする点が肝心です。無関係なファイルを多く開いていると、AIの注意が分散します。
実践テクニック：
ピンポイント参照: 大きなファイルの一部のみが必要な場合は、その部分を抜粋して提示します。
// 以下の部分だけを修正してください:
// src/services/payment.ts の processPayment 関数（50-80行目）
async function processPayment(amount: number, currency: string): Promise<PaymentResult> {
// ... 現在のコード ...
}差分指定: 新機能追加の場合は、既存コードの構造だけ見せて詳細は省略します。
現在のファイル構造（詳細は省略）:
- getUserById(): ユーザー取得
- updateUser(): ユーザー更新
- deleteUser(): ユーザー削除
→ ここに createUserSession() を追加してください
2. タスク分解の技法 — 大きな課題を小さな成功に変える
2-1. 「象食べる」戦略
「象を食べるにはどうするか？ひと口ずつ」という格言がソフトウェア開発にも当てはまります。Antigravityに「ECサイトを作って」と言うのは失敗のもとです。
効果的なタスク分解の手順：
ステップ1: エピックの定義
エピック: ユーザー注文管理システムの構築
ステップ2: ストーリーへの分解
ストーリー1: 注文一覧の表示
ストーリー2: 注文詳細の表示
ストーリー3: 注文ステータスの更新
ストーリー4: 注文のキャンセル処理
ストーリー5: メール通知の送信
ステップ3: タスクへの分解（Antigravityへの指示単位）
タスク1-1: OrderList コンポーネントの雛形作成
タスク1-2: API呼び出しロジックの実装
タスク1-3: ローディング・エラー状態の実装
タスク1-4: ページネーションの追加
タスク1-5: ユニットテストの追加
2-2. タスクの「受入条件」を明示する
各タスクに受入条件（アクセプタンスクライテリア）を明示することで、AIの出力品質が劇的に向上します。
タスク: OrderList コンポーネントの実装
受入条件:
✅ TypeScriptで型安全に実装されている
✅ エラー境界でエラーをハンドリングしている
✅ ローディング中はスケルトンUIを表示する
✅ 注文が0件の場合は「注文がありません」を表示する
✅ テストカバレッジ80%以上
✅ Storybookのストーリーが含まれている
2-3. Planning Modeを使った自動タスク分解
Planning Modeは大きな実装の前に使うと効果的です。タスク分解をAntigravity自身にやってもらいましょう。
[Planning Modeで実行]
プロジェクト: マルチテナント対応SaaSの認証システム実装
技術スタック: Next.js 15 + Supabase + TypeScript
以下を計画してください:
1. 実装が必要なコンポーネント/モジュールの一覧
2. 依存関係（何を先に作るべきか）
3. 各タスクの概算工数
4. リスクがある部分と代替案
このように使うと、Antigravityが詳細な実装計画を提示してくれます。その計画をレビューして、修正してから実装フェーズに移行するのがプロのワークフローです。
3. AGENTS.md の高度な設定 — AIに「現場のルール」を教える
3-1. AGENTS.md の基本構造と戦略的活用
AGENTS.md はAntigravityがプロジェクトを理解するための「新人向けオンボーディングドキュメント」として機能します。しかし多くのエンジニアが表面的な使い方しかしていません。
効果的なAGENTS.md の構成：
# プロジェクト概要
[1-2文で何を作っているか]
# 技術スタック（決定の理由も記載）
- Next.js 15 App Router: Cloudflare Workers対応のため
- Supabase: リアルタイム機能が必要なため（FirebaseではなくPostgreSQLベースが必須）
- Stripe: 決済処理（webhookはEdge Runtimeで動作確認済み）
# アーキテクチャの制約（絶対に守ること）
- Server Componentsではfsモジュールを使わない（Cloudflare Workers非対応）
- クライアントコンポーネントではenvironment variablesをNEXT_PUBLIC_プレフィックス必須
- データフェッチはすべてServer Actionsを経由する（APIルート直接呼び出し禁止）
# 命名規則
- コンポーネント: PascalCase（例: UserProfileCard）
- ファイル名: kebab-case（例: user-profile-card.tsx）
- 型定義: PascalCase + Type/Interfaceサフィックス不要（例: User, Order）
# テスト方針
- ユニットテスト: Vitest + Testing Library
- E2Eテスト: Playwright（CIでのみ実行）
- モックポリシー: データベースはモックしない、外部APIのみモック
# よくある失敗パターン（これをやってはいけない）
- useEffectでデータフェッチ: 必ずServer ComponentかSWRを使う
- anyキャストの多用: 必ずzodで型検証する
- console.logの残存: すべてlogger.tsを使う3-2. ドメイン知識を教え込む
技術的な制約だけでなく、ビジネスロジックもAGENTS.mdに記載しましょう。
# ビジネスルール（重要）
## 価格計算
- 価格はすべてセント単位で保存（¥100 = 10000 yen_cents）
- 消費税は10%（軽減税率8%は対象外商品のみ適用）
- 割引は税抜価格に適用してから税計算
## ユーザー権限
- ROLE_ADMIN: 全操作可能
- ROLE_MANAGER: 自組織内の全操作可能
- ROLE_MEMBER: 読み取りと自分のデータのみ更新可能
## 注文ステータス遷移
pending → confirmed → shipped → delivered → completed
↓
cancelled（pending/confirmed のみキャンセル可能）
refunded（delivered/completed のみ返金可能）3-3. AGENTS.md の定期的なアップデート戦略
AGENTS.mdは生きたドキュメントです。新しい知見が得られたらすぐに更新しましょう。
[セッション終了前の習慣]
このセッションで学んだことのうち、AGENTS.mdに追記すべき情報を提案してください。
このプロンプトを毎セッション末尾に使うことで、AGENTS.mdが自動的に充実していきます。
4. Planning Mode と Fast Mode のハイブリッド戦略
4-1. 2つのモードの使い分け判断フロー
タスクを受け取る
↓
実装範囲が明確か？
├─ NO → Planning Mode で設計から始める
└─ YES → 影響ファイルが3つ以上か？
├─ YES → Planning Mode で確認してから実装
└─ NO → Fast Mode で直接実装
Planning Modeを使うべき状況:
- 新機能の実装（スコープが曖昧）
- リファクタリング（影響範囲が広い）
- バグの根本原因調査（どのファイルが問題かわからない）
- アーキテクチャの変更
Fast Modeを使うべき状況:
- 明確なバグ修正（原因が特定済み）
- 小さなUI調整（1-2コンポーネントの変更）
- テストの追加（既存実装に対して）
- ドキュメントの更新
4-2. Planning Mode の質問技術
Planning Modeで質問の質を上げることで、計画書の精度が上がります。
# 悪い例
「ユーザー認証を実装して」
# 良い例
「以下の条件でユーザー認証システムを設計してください:
- メール+パスワード認証
- Google OAuth（Supabaseを使用）
- JWTトークンはhttponly cookieで管理
- リフレッシュトークン対応
- セッション有効期限: 24時間
- 複数デバイスのセッション管理対応
現在の認証関連ファイル:
- src/lib/supabase/client.ts（クライアント側）
- src/lib/supabase/server.ts（サーバー側）
- middleware.ts（ルート保護）
実装が必要なファイル一覧と、それぞれで変更する内容を優先順位とともに示してください。」
4-3. モード切り替えのシグナル
実装中にPlanning Modeへ切り替えるべきサインを知っておきましょう。
- 「これを変えると他にも影響が出そう」と思った瞬間
- 同じ問題を3回以上修正しているとき
- エラーの原因が特定できず5分以上経過しているとき
[実装中にモード切り替え]
一旦実装を止めて、この問題の根本原因を調査してほしい。
現在の状況: [エラーメッセージ/現象]
試したこと: [試したこと1], [試したこと2]
考えられる原因を優先度順に列挙して、それぞれの確認手順を示してください。
5. 並列処理・マルチウィンドウ活用パターン
5-1. Antigravity の 3エージェントウィンドウ を活かす
Antigravityは複数のウィンドウを開いて並列作業することが可能です。これを戦略的に活用しましょう。
フロントエンド / バックエンド / テスト の並列実装:
ウィンドウ1: APIエンドポイントの実装（バックエンド）
ウィンドウ2: UIコンポーネントの実装（フロントエンド）
ウィンドウ3: テストケースの設計（テスト）
ただし、並列作業をする場合はインターフェース（型定義）を先に決めることが大原則です。型定義が固まる前に並列実装を始めると、後で大きな手戻りが発生します。
// 最初にインターフェースを合意する（types/order.ts）
export interface Order {
id: string;
userId: string;
items: OrderItem[];
totalAmount: number; // yen_cents単位
status: OrderStatus;
createdAt: Date;
updatedAt: Date;
}
export type OrderStatus =
| 'pending'
| 'confirmed'
| 'shipped'
| 'delivered'
| 'completed'
| 'cancelled'
| 'refunded';
// ↑ この型を全ウィンドウで共有してから並列実装開始5-2. コンフリクトを最小化する並列作業の設計
並列作業でよくある失敗は「同じファイルを複数のウィンドウが編集する」ことです。これを防ぐためのルール：
並列作業の分割原則:
- ウィンドウA: src/app/（pages・layouts）
- ウィンドウB: src/components/（再利用コンポーネント）
- ウィンドウC: src/lib/（ユーティリティ・API client）
- ウィンドウD: tests/（テストファイル）
この分割により、ファイルレベルのコンフリクトをほぼゼロにできます。
5-3. 並列作業のマージ戦略
並列作業後のマージは計画的に行いましょう。
# ウィンドウごとにブランチを分ける
git checkout -b feature/order-api # ウィンドウ1
git checkout -b feature/order-ui # ウィンドウ2
git checkout -b feature/order-tests # ウィンドウ3
# 依存順にマージ
# 1. まずAPIブランチをマージ
# 2. APIに依存するUIブランチをマージ
# 3. 最後にテストブランチをマージ6. 開発速度を数値で測るメトリクス設計
6-1. 測定すべき3つの指標
AI支援開発の速度向上を定量評価するための指標です。
指標1: タスク完了率（Task Completion Rate）
# 1日のタスク数を記録するシンプルなスクリプト
# ワークログ例: worklog.json
{
"date": "2026-04-04",
"planned_tasks": 8,
"completed_tasks": 6,
"rework_tasks": 1, # 修正が必要になったタスク
"completion_rate": 0.75,
"notes": "認証セッションのバグで2タスク遅延"
}指標2: コンテキストリセット頻度
セッション中に「最初からやり直し」が必要になった回数を記録します。この頻度が高いほどコンテキスト管理に問題があります。
指標3: 受入条件未達率
Antigravityが生成したコードが最初のレビューで受け入れ条件を満たさなかった割合です。これが高い場合、タスク定義の質に問題があります。
6-2. 週次レビューテンプレート
## 週次AIワークフローレビュー（[日付]）
### 定量データ
- 今週の完了タスク数: XX / XX (計画)
- コンテキストリセット: X回
- 受入条件未達: X%
### 最も効果的だったワークフロー
[具体的な手法と結果]
### 最も時間を浪費した原因
[原因と来週の改善策]
### AGENTS.md 更新内容
[今週追加した知見]7. よくある速度低下パターンと解決策
7-1. 「曖昧な指示ループ」から抜け出す
症状：修正を指示するたびに少しずれた結果が返ってきて、何度も往復します。
原因：指示が曖昧で、AIが正しい方向を推測しています。
解決策：Before/Afterを明示します。
# 悪い指示
「ボタンのスタイルをかっこよくして」
# 良い指示
「ボタンのスタイルを変更してください。
現在: bg-blue-500 text-white px-4 py-2 rounded
変更後: bg-gradient-to-r from-blue-600 to-purple-600 text-white
px-6 py-3 rounded-xl shadow-lg hover:shadow-xl
transition-all duration-200 hover:scale-105
font-semibold tracking-wide
※ この変更は LoginButton.tsx と RegisterButton.tsx の両方に適用してください」
7-2. 「デグレード修正ループ」を断ち切る
症状：Aを修正するとBが壊れる、Bを修正するとAが壊れる、を繰り返す。
原因：テストがなく、副作用の検知が人手に依存しています。
解決策：テストファーストで修正します。
[デグレード修正ループに入ったとき]
現在の問題: [現象]
懸念: 修正によるデグレードが怖い
手順:
1. まず現在の動作をテストで固定してください
2. その後、テストがパスする最小の修正を提案してください
3. 修正後、全テストが通ることを確認してください
7-3. 「コンテキスト溢れ」の診断と対処
症状：同じセッションを長く続けていると、回答の質が落ちてくる。
診断コマンド：
[現状確認]
このセッションで私が実装しようとしていることを、あなたの理解で簡潔に3つの箇条書きでまとめてください。
このプロンプトへの回答が的外れであれば、コンテキスト溢れが起きています。
対処法：セッションをリセットして、コンパクトなサマリーから始める。
[新セッション開始]
前のセッションの継続です。状況をサマリーします:
目標: [1文で]
完了済み: [箇条書き2-3件]
次のタスク: [1つだけ]
注意事項: [あれば]
8. 実践：大規模リファクタリングの進め方
8-1. 段階的リファクタリング戦略
大規模なリファクタリングを一気にやろうとするのは最も失敗しやすいパターンです。
フェーズ1: 現状分析（Planning Mode）
[Planning Mode]
以下のディレクトリ構造を分析して、リファクタリングの優先度マップを作成してください。
評価軸:
- 変更頻度（gitログから推測）
- 依存度（どれだけ他から参照されているか）
- テストカバレッジ
- 技術的負債の深刻度
src/
├── components/ (28ファイル)
├── hooks/ (15ファイル)
├── lib/ (12ファイル)
└── pages/ (20ファイル)
フェーズ2: インターフェース先行設計
// 現在の型定義（問題がある）
interface UserData {
id: any;
info: any;
settings: any;
}
// リファクタリング後の目標型定義
interface User {
id: UserId; // Branded Type
profile: UserProfile;
preferences: UserPreferences;
subscription: SubscriptionPlan;
}
// まずこの型定義だけを実装し、残りは段階的に移行フェーズ3: ストラングラーパターンで移行
[Fast Mode]
UserData型を使っているファイルを1つずつ新しいUser型に移行します。
今日は src/components/UserProfileCard.tsx だけを対象にします。
要件:
- UserData型の使用をUser型に置き換える
- 型が変わることで必要になるデータ変換は src/lib/adapters/userAdapter.ts に集約する
- 既存のテストがすべてパスすること
まとめ
本記事で解説したテクニックと合わせて、Antigravity ワークスペース最適化の基礎や、Planning Mode と Fast Mode の深い比較も参照してみてください。また、大規模プロジェクトでのコンテキスト戦略については Antigravity プロジェクトコンテキスト管理マスターガイド もあわせてお読みいただくと理解が深まります。
ここではAntigravityを使った開発速度を根本から高める以下の手法を解説しました。
コンテキスト管理では、セッションを明確な目標で分割し、ファイルコンテキストを戦略的に制御することが大切です。タスク分解では「1タスク = 1つの明確な成果物」という原則と、受入条件の明示が品質向上の鍵です。
AGENTS.mdは技術的な制約だけでなくビジネスルールも含め、「新人エンジニアが迷わないオンボーディング資料」として設計することで、セッションをまたいだコンテキストの一貫性を保てます。
Planning ModeとFast Modeのハイブリッド活用では、影響範囲と不確実性に応じてモードを切り替える判断力が速度向上の本質です。並列ウィンドウ活用では、インターフェースを先に固めてから並列実装することでコンフリクトを防ぎます。
そして最も大切なのは、速度を数値で測り、週次でレビューして改善し続けることです。感覚ではなくデータで改善するエンジニアが、AI時代において最も速く成長できます。
より深くAntigravityのワークフローを