Antigravity の Agent-First ワークフロー実践ガイド — プロジェクト管理からスキル設計まで

Agent-First 開発とは何か

Antigravity における「Agent-First 開発」は、従来の「プロンプトを毎回書く」という開発スタイルから、「エージェント（自律的なAI）を育成・管理する」という新しいパラダイムへのシフトです。

従来のAI開発との違い

【従来の方法】
1. 毎回、同じプロンプトを書き直す
2. 文脈が消えるため、前回の決定を忘れる
3. スケーリングが困難（チーム内での再利用が難しい）

【Agent-First の方法】
1. 「エージェント」（組織化された AI）を作成
2. エージェントが記憶を保持し、学習する
3. 複数プロジェクト・複数チームで再利用可能

例：
従来：「React コンポーネントを書いて」→毎回プロンプト入力
Agent-First：「React エージェント」を1度設定 → 以降は指示だけ

Antigravity のプロジェクト構造

Antigravity で推奨されるプロジェクト構造は、「1プロジェクト = 1フォルダ」という明確な分離です。

推奨フォルダ構成

my-projects/
├── project-alpha/          # プロジェクトA
│   ├── agents/              # このプロジェクト用のエージェント
│   │   ├── frontend-agent.md
│   │   ├── backend-agent.md
│   │   └── qa-agent.md
│   ├── skills/              # 再利用可能スキル
│   │   ├── api-integration.md
│   │   └── database-query.md
│   ├── artifacts/           # 生成されたコード・ドキュメント
│   │   ├── components/
│   │   ├── services/
│   │   └── tests/
│   ├── docs/                # プロジェクトドキュメント
│   │   ├── requirements.md
│   │   ├── architecture.md
│   │   └── api-spec.md
│   └── context.md           # プロジェクト全体のコンテキスト

├── project-beta/           # プロジェクトB
│   └── [同じ構造]

└── shared-skills/          # 全プロジェクト共通スキル
    ├── code-review.md
    ├── testing.md
    ├── documentation.md
    └── deployment.md

context.md の役割

各プロジェクトの context.md は、そのプロジェクト全体の「記憶」の役割を果たします。

# プロジェクトコンテキスト
 
## プロジェクト概要
- 名前：AI アシスタント搭載タスク管理アプリ
- 目的：タスク自動分類・優先度提案
- 開始日：2026-01-15
- チーム規模：3名
 
## 技術スタック
- フロントエンド：React 19 + TypeScript
- バックエンド：Python FastAPI
- データベース：PostgreSQL 15
- デプロイ：Docker + Kubernetes
 
## 主要な決定事項（なぜそれを選んだか）
1. React を選んだ理由：社内の経験豊富なエンジニアが 2名
2. FastAPI を選んだ理由：Python での ML 統合が容易
3. PostgreSQL を選んだ理由：複雑なクエリが必要
 
## 既知の制約
- 初期段階では、タスク数 10万件を想定
- UI は ダークモード対応必須
- API レスポンス時間 200ms 以内
 
## 完了済み機能
- [x] ユーザー認証
- [x] タスク CRUD
- [ ] AI 優先度提案
 
## チームメンバーの役割
- Alice：フロントエンドリード（React）
- Bob：バックエンドリード（Python）
- Charlie：QA・テスト

このコンテキストにより、エージェント（AI）が「このプロジェクトは何か」を常に理解している状態を保ちます。

Skills Library の構築 — 再利用可能なAI行動

Antigravity の強力な機能として「Skills Library」があります。これは「特定のタスク（スキル）に対する、再利用可能な AI 行動定義」です。

スキルの設計原則：「1スキル = 1ジョブ」

# Skill: React-Form-Generation
 
## 目的
React フォームコンポーネントを自動生成する
 
## 入力
- フォームのフィールド定義（JSON）
  ```json
  {
    "fields": [
      {"name": "email", "type": "email", "required": true},
      {"name": "password", "type": "password", "required": true},
      {"name": "remember", "type": "checkbox"}
    ]
  }

処理ステップ

フィールド定義を解析
React Hook Form を使用したコンポーネント生成
バリデーションロジックの追加
Tailwind CSS でスタイリング
TypeScript 型安全性の確保

出力

FormComponent.tsx（フォームコンポーネント）
FormComponent.test.tsx（テストコード）
types.ts（型定義）

設定パラメータ

variant: 'simple' | 'advanced'
darkMode: boolean
submitButtonText: string

制限事項

複雑な条件付き表示（フィールドの表示/非表示切り替え）は非対応
ファイルアップロード欄は非対応


このスキルを定義すれば、以降は以下のように利用できます：

指示：「React-Form-Generation スキルを使用して、以下のログインフォームを生成してください

フィールド：

email（メールアドレス）
password（パスワード）
remember-me（チェックボックス）

variant: 'simple'、darkMode: true」


エージェントはスキル定義を参照し、自動で正確なコンポーネントを生成します。

### スキルライブラリの例

実際のプロジェクトで活躍するスキル：

<table>
  <thead>
    <tr><th>スキル名</th><th>目的</th><th>入力</th><th>出力</th></tr>
  </thead>
  <tbody>
    <tr><td>React-Component-Gen</td><td>React コンポーネント生成</td><td>要件</td><td>JSX コード</td></tr>
    <tr><td>API-Endpoint-Gen</td><td>FastAPI エンドポイント生成</td><td>エンドポイント定義</td><td>Python コード</td></tr>
    <tr><td>Database-Migration-Gen</td><td>DB マイグレーション生成</td><td>スキーマ変更</td><td>SQL</td></tr>
    <tr><td>Test-Suite-Gen</td><td>テストコード生成</td><td>関数/メソッド</td><td>Jest/pytest コード</td></tr>
    <tr><td>Documentation-Gen</td><td>API ドキュメント生成</td><td>コード</td><td>Markdown</td></tr>
  </tbody>
</table>

## Artifact システム — 計画→提案→コード化のサイクル

Antigravity の Artifact システムは、「草案（ドラフト）」と「本実装」を明確に分離する仕組みです。

### 典型的なワークフロー

#### ステップ 1：計画（Markdown）

```markdown
# 機能：タスク優先度表示コンポーネント

## 要件
- タスク一覧を表示
- 各タスクに優先度（高・中・低）を色分け表示
- ユーザークリックで優先度変更可能
- ダークモード対応

## 設計案
- 優先度ラベル：色分け表示（赤・橙・黄）
- タスクカード：Tailwind CSS で実装
- インタラクション：onClick で優先度更新 API 呼び出し

## API 依存
- GET /api/tasks
- PUT /api/tasks/{id}/priority

ステップ 2：提案（Artifact）

Antigravity が Artifact を生成：

// Artifact として生成されたコンポーネント
import React, { useState } from 'react';
 
export function TaskPriorityDisplay({ tasks }) {
  const priorityColors = {
    high: 'bg-red-600',
    medium: 'bg-orange-500',
    low: 'bg-yellow-400'
  };
 
  const handlePriorityChange = async (taskId, newPriority) => {
    await fetch(`/api/tasks/${taskId}/priority`, {
      method: 'PUT',
      body: JSON.stringify({ priority: newPriority })
    });
  };
 
  return (
    <div className="space-y-2">
      {tasks.map(task => (
        <div key={task.id} className="flex items-center gap-4">
          <div
            className={`w-4 h-4 rounded ${priorityColors[task.priority]}`}
            onClick={() => handlePriorityChange(
              task.id,
              task.priority === 'high' ? 'medium' : 'high'
            )}
          />
          <span>{task.title}</span>
        </div>
      ))}
    </div>
  );
}

ステップ 3：レビュー

開発者が Artifact を確認：

指摘：
「onClick ハンドラーが優先度を 'high' → 'medium' にしか変更できません。
次の優先度に循環するようにしてください：
高 → 中 → 低 → 高」

ステップ 4：修正

Antigravity が修正：

const prioritySequence = ['high', 'medium', 'low'];
 
const handlePriorityChange = async (taskId, currentPriority) => {
  const currentIndex = prioritySequence.indexOf(currentPriority);
  const nextIndex = (currentIndex + 1) % prioritySequence.length;
  const newPriority = prioritySequence[nextIndex];
 
  await fetch(`/api/tasks/${taskId}/priority`, {
    method: 'PUT',
    body: JSON.stringify({ priority: newPriority })
  });
};

ステップ 5：確定

確定したコードが artifacts/ フォルダに保存されます。

Artifact のメリット

可視化：AI が何を作ろうとしているかが明確
イテレーション：修正指示 → 自動修正のサイクルが高速
チーム共有：Artifact URL で他チームメンバーと共有可能
履歴管理：すべての版が自動保存される

Agent-Assisted vs Autonomous モード

Antigravity では 2つのエージェント動作モードが用意されています。

Agent-Assisted モード（推奨：実装段階）

エージェント（AI）が 人間の指示を待つ 待機状態。

フロー：
1. 開発者：「TaskForm コンポーネント作成」と指示
2. Antigravity が Artifact を提案
3. 開発者が確認・修正指示
4. Antigravity が修正
5. 確定まで人間がコントロール

メリット：

開発者の意図が正確に反映される
品質が高い
チームの認識が統一される

デメリット：

時間がかかる

Autonomous モード（使用限定：単純タスク）

エージェント（AI）が 自動で判断・実行 する模式。

フロー：
1. 開発者：「テストコード を自動生成して」と指示
2. Autonomous エージェントが自動で：
   - 関数を分析
   - テストケース設計
   - テストコード生成
   - リポジトリに commit
3. 開発者は結果を確認するだけ

メリット：

高速
単純タスクに最適

デメリット：

開発者が意図を失う可能性
複雑な判断には向かない

使い分けの指針

タスク	推奨モード	理由
新規機能の UI 実装	Agent-Assisted	要件の正確な反映が必須
バグ修正	Agent-Assisted	根本原因の議論が必要
テストコード生成	Autonomous	単純な機械的作業
ドキュメント生成	Autonomous	テンプレート化しやすい
API 設計	Agent-Assisted	全体設計への影響大
コード自動フォーマット	Autonomous	規則が明確

実践的な1日のワークフロー

朝：本日のタスク計画

Project context.md を確認
本日のタスク（Markdown）を作成

# 本日のタスク（2026-03-20）
 
## 完了目標
- [ ] タスク優先度表示コンポーネント完成
- [ ] API エンドポイント実装
- [ ] ユニットテスト追加
- [ ] ドキュメント更新
 
## 実装順序
1. Agent-Assisted：UI コンポーネント設計
2. Agent-Assisted：バックエンド API 実装
3. Autonomous：テストコード生成
4. Autonomous：ドキュメント生成

午前：フロントエンド実装

開発者：
「TaskPriorityDisplay コンポーネントを作成してください。
要件は project-context.md に記載されています。」

Antigravity（Agent-Assisted）：
Artifact として提案

開発者：
「見た目は良いですが、クリック時のアニメーション を追加してください」

Antigravity：
Artifact を更新

開発者：
「OK、これで確定」
→ components/ に保存

午後：バックエンド実装

開発者：
「FastAPI で PUT /tasks/{id}/priority エンドポイント を実装してください。
- 優先度（high/medium/low）を受け取る
- データベースに保存
- 変更前後のタスク情報をログに記録」

Antigravity（Agent-Assisted）：
```python
@app.put("/tasks/{task_id}/priority")
async def update_task_priority(
    task_id: int,
    priority: str = Body(..., embed=True),
    current_user: User = Depends(get_current_user)
):
    # バリデーション
    if priority not in ['high', 'medium', 'low']:
        raise HTTPException(status_code=400)

    # 現在の優先度を記録
    old_task = db.query(Task).filter(Task.id == task_id).first()

    # 優先度を更新
    old_task.priority = priority
    db.commit()

    # ログ記録
    logger.info(f"Task {task_id}: {old_task.priority} → {priority}")

    return old_task


開発者が確認して修正指示を出し、最終確定。

### 夕方：テスト・ドキュメント

開発者（Autonomous モード指定）：「前述のテストスイートを自動生成してください」

Antigravity（自動実行）：

def test_update_task_priority_success():
    # テスト実装
 
def test_update_task_priority_invalid():
    # テスト実装
 
def test_update_task_priority_unauthorized():
    # テスト実装

自動生成完了

開発者：「ドキュメントも自動生成」

Antigravity： API ドキュメント自動生成完了


## ベストプラクティス

### 1. Context の定期更新

週 1回、project context.md を更新。プロジェクトの状態を正確に保ち、エージェント（AI）の理解を保つ。

### 2. スキルの段階的構築

プロジェクト開始時は少数のスキル → 実装を進めるにつれて、汎用スキルを徐々に増やす。

### 3. Artifact の活用ルール

- 新規実装：必ず Artifact で提案 → レビュー → 確定
- バグ修正：Artifact で修正案 → テスト → 確定
- ドキュメント生成：Autonomous で自動生成 OK

### 4. エージェント育成の投資

最初の 3日間は「単にコード生成させる」ではなく「このプロジェクトを理解させる」ことに時間を使います。その後の効率が劇的に向上します。

## 困ったときのトラブルシューティング

### エージェントが要件を誤解している

→ Context を更新し、「なぜそのやり方を選んだのか」という背景を明記

### Artifact が複雑すぎる

→ スキルを細分化。「1つのスキル = 1つの小さなジョブ」に分割

### チームメンバー間で異なる指示を出している

→ Context と Skills Library を共有。ドキュメント化を最優先

## 全体を振り返って：Agent-First 開発への移行

Agent-First ワークフローは、最初は「複雑だ」と感じるかもしれません。

しかし、一度習得すれば：

1. **エージェント（AI）が学習し、育成される**
2. **チーム全体で同じやり方を共有**
3. **スケーラビリティが劇的に向上**
4. **新メンバーのオンボーディングが高速化**

これらの利点により、個人作業の効率も、チーム作業の生産性も大幅に向上します。

是非、試してみてください。