Antigravityヘッドレスモード完全ガイド｜CI/CD自動化

Google Antigravity（旧Gemini CLI）は、対話的なAIコーディングツールとして定評がありますが、その真の力を引き出すのがヘッドレスモードです。ターミナルの前に座ることなく、CI/CDパイプラインやスクリプトからAIを呼び出して自動化する——2026年のモダン開発に不可欠なテクニックを解説します。

ヘッドレスモードとは？対話型との使い分け

ヘッドレスモードの仕組み

ヘッドレスモードとは、ユーザーの対話操作なしにAntigravityを実行するモードです。プロンプトとコンテキストをコマンドラインやAPIで渡し、結果をstdoutまたはファイルに出力します。

# 基本的なヘッドレス実行
antigravity --headless --prompt "このファイルのユニットテストを書いて" \
  --input ./src/utils.ts \
  --output ./tests/utils.test.ts

対話型モードとの比較

比較項目	対話型モード	ヘッドレスモード
ユーザー操作	必要	不要
入力方法	対話的に指示	CLI引数/設定ファイル
出力	ターミナル表示	stdout/ファイル出力
適用場面	探索的な開発	定型作業の自動化
CI/CD連携	不可	可能
バッチ処理	不可	可能

使い分けの指針:

• 新機能の設計・実装など創造的な作業は対話型モード
• テスト生成・コードレビュー・ドキュメント更新など定型作業はヘッドレスモード

ヘッドレスモードのセットアップ

APIキーとGemini CLI設定

ヘッドレスモードを利用するには、Gemini APIキーの設定が必要です。

# APIキーの設定
export GEMINI_API_KEY="your-api-key-here"

# または設定ファイルに記載
echo '{"apiKey": "your-api-key"}' > ~/.antigravity/config.json

# Antigravityのバージョン確認
antigravity --version

非対話型コマンドの書き方

ヘッドレスモードの基本構文は以下の通りです。

# 基本構文
antigravity --headless \
  --prompt "実行したい指示" \
  --input <入力ファイル/ディレクトリ> \
  --output <出力先> \
  --model gemini-2.5-pro

# 複数ファイルの入力
antigravity --headless \
  --prompt "これらのファイルのコードレビューを行い、改善点を報告して" \
  --input ./src/ \
  --format markdown \
  --output ./review-report.md

Antigravityの基本的な使い方については、Antigravity使い方ガイドで詳しく解説しています。

GitHub Actionsとの連携

PRレビュー自動化ワークフロー

GitHub ActionsからAntigravityのヘッドレスモードを呼び出し、PRの自動レビューを実現します。

# .github/workflows/ai-review.yml
name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Get changed files
        id: changed
        run: |
          echo "files=$(git diff --name-only origin/main...HEAD | tr '\n' ',')" >> $GITHUB_OUTPUT
      
      - name: AI Review
        run: |
          antigravity --headless \
            --prompt "以下の変更点をレビューしてください。セキュリティ、パフォーマンス、可読性の観点で評価し、改善提案をしてください。" \
            --input "${{ steps.changed.outputs.files }}" \
            --format github-review \
            --output review-comments.json
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
      
      - name: Post Review Comments
        uses: actions/github-script@v7
        with:
          script: |
            const comments = require('./review-comments.json');
            // PRにレビューコメントを投稿

コード生成パイプライン

# .github/workflows/generate-tests.yml
name: Auto Generate Tests
on:
  push:
    branches: [main]
    paths: ['src/**/*.ts']

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Generate Tests
        run: |
          for file in $(git diff --name-only HEAD~1 -- 'src/**/*.ts'); do
            test_file="tests/$(basename $file .ts).test.ts"
            antigravity --headless \
              --prompt "このTypeScriptファイルの包括的なユニットテストをJest形式で生成してください" \
              --input "$file" \
              --output "$test_file"
          done
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
      
      - name: Create PR
        uses: peter-evans/create-pull-request@v6
        with:
          title: "🤖 Auto-generated tests"
          branch: "auto/tests-$(date +%Y%m%d)"

テスト自動生成

テストカバレッジが不足している箇所を検出し、自動でテストを追加するパイプラインも構築可能です。

# カバレッジレポートをもとにテスト生成
npx jest --coverage --json > coverage.json

antigravity --headless \
  --prompt "coverage.jsonを分析し、カバレッジが80%未満のファイルに対してテストを生成してください" \
  --input coverage.json \
  --context ./src/ \
  --output ./tests/

バッチ処理とスクリプト統合

シェルスクリプトからの呼び出し

#!/bin/bash
# batch-review.sh: コードベース全体のバッチレビュー

DIRS=("src/api" "src/services" "src/utils")
REPORT="./reports/review-$(date +%Y%m%d).md"

echo "# コードレビューレポート $(date +%Y-%m-%d)" > "$REPORT"

for dir in "${DIRS[@]}"; do
  echo "## $dir" >> "$REPORT"
  
  antigravity --headless \
    --prompt "このディレクトリのコードを分析し、改善点・セキュリティリスク・パフォーマンス問題を報告してください" \
    --input "$dir" \
    --format markdown >> "$REPORT"
  
  echo "" >> "$REPORT"
done

echo "レビューレポート生成完了: $REPORT"

複数ファイルの一括処理

# 全コンポーネントのドキュメントを一括生成
find ./src/components -name "*.tsx" | while read file; do
  doc_file="./docs/components/$(basename $file .tsx).md"
  
  antigravity --headless \
    --prompt "このReactコンポーネントのAPIドキュメントをマークダウン形式で生成してください。Props、使用例、注意事項を含めてください" \
    --input "$file" \
    --output "$doc_file" \
    --model gemini-2.5-flash  # バッチ処理はFlashモデルでコスト節約
done

日本語環境での設定については、Antigravity日本語ガイドも参考になります。

Antigravity IDE との併用パターン

ヘッドレスモードとAntigravity IDEを併用することで、開発効率を最大化できます。

併用パターンの例:

1. IDE: 新機能の実装（対話的な創造作業）
2. ヘッドレス: テスト生成、ドキュメント更新（定型作業の自動化）
3. CI/CD: PRレビュー、デプロイ前チェック（パイプライン統合）

# IDEで実装 → ヘッドレスでテスト生成 → CI/CDでレビュー
# の一連のフローを1コマンドで実行
antigravity workflow run \
  --config .antigravity/workflow.yaml \
  --target ./src/new-feature/

カスタムワークフローの構築については、Antigravityカスタムワークフロー自動化ガイドで詳しく解説しています。

コスト管理とレート制限の対策

ヘッドレスモードでバッチ処理を行う際は、APIコストとレート制限に注意が必要です。

コスト管理のポイント:

戦略	詳細
モデル使い分け	単純なタスクはFlash、高度な分析はPro
キャッシュ活用	--cacheフラグで同一入力の再実行を回避
バッチサイズ	1回のリクエストで複数ファイルをまとめて処理
実行時間帯	オフピーク時間に実行してレート制限を回避

# コスト節約のテクニック
antigravity --headless \
  --model gemini-2.5-flash \  # Flashモデルでコスト1/10
  --cache \                    # キャッシュ有効
  --max-tokens 2000 \         # 出力トークン制限
  --prompt "簡潔にコードレビューしてください"

レート制限への対策:

# リトライ付きバッチ実行
antigravity batch run \
  --config batch.yaml \
  --retry 3 \
  --retry-delay 60 \
  --concurrency 2  # 並列実行数を制限

Google AI のGemini API利用ガイドラインも確認しておきましょう。

実践事例：ドキュメント自動生成パイプライン

実際にAntigravityヘッドレスモードで構築したドキュメント自動生成パイプラインの事例を紹介します。

パイプラインの流れ:

1. コードがmainブランチにマージされる
2. GitHub Actionsが変更されたファイルを検出
3. Antigravityヘッドレスでドキュメントを生成/更新
4. 生成されたドキュメントをGitHub Pagesにデプロイ
5. Slackに完了通知

成果:

• ドキュメント作成の工数が月40時間 → 2時間に削減
• ドキュメントの鮮度が常に最新に保たれる
• エンジニアがドキュメント作成に時間を取られなくなった

CI/CD自動化の詳細については、Antigravity CI/CD自動化ガイドもご覧ください。

まとめ：ヘッドレスモードで開発を加速

Antigravityのヘッドレスモードは、AIコーディングツールをCI/CDパイプラインに組み込むための必須テクニックです。

ヘッドレスモード活用のステップ:

1. APIキーを設定し、基本的なヘッドレス実行を試す
2. テスト生成やコードレビューのスクリプトを作成
3. GitHub Actionsに組み込んで自動化
4. バッチ処理で大規模な定型作業を効率化
5. コスト管理の仕組みを整えて持続可能な運用に

SES現場では、プロジェクト参画時にCI/CDパイプラインにAIレビューを組み込む提案ができると、技術力の高さをアピールできます。