Google Antigravity ドキュメント自動生成ガイド｜AIでAPI仕様書・設計書・READMEを効率化する方法

SES現場でプロジェクトに参画すると、ドキュメントが古い・存在しないという問題に高確率で遭遇します。コードは日々更新されるのに、API仕様書やREADMEは半年前のまま——そんな状況はエンジニアにとって大きなストレスです。

Google AntigravityのGemini AIエンジンを活用すれば、コードベースを解析して正確なドキュメントを自動生成できます。本記事では、API仕様書・設計書・READMEの自動生成から、CI/CDパイプラインでの自動更新まで、SES現場で即実践できるテクニックを解説します。

なぜSES現場でドキュメント自動生成が重要なのか

SESエンジニアが新しいプロジェクトに参画する際、最初の壁は既存コードの理解です。ドキュメントが整備されていれば立ち上がりは早くなりますが、現実には以下のような課題が山積しています。

SES現場でよくあるドキュメント問題

課題	影響	発生頻度
APIドキュメントが未整備	エンドポイントの仕様を毎回コードから読み解く必要がある	約70%のプロジェクト
READMEが初期状態のまま	環境構築手順が不明で、セットアップに1日以上かかる	約60%のプロジェクト
設計書とコードの乖離	設計書を信じて実装すると、実際の挙動と異なりバグになる	約50%のプロジェクト
ドキュメント更新が属人化	特定のメンバーが離脱するとドキュメントが完全に放置される	約80%のプロジェクト

Google Antigravityを導入すれば、これらの課題をAIによる自動生成と自動更新で根本的に解決できます。

Google Antigravityでドキュメントを自動生成する基本フロー

Google Antigravityのドキュメント自動生成は、大きく3つのステップで実行します。

ステップ1：コードベースの解析

Antigravityに対象のソースコードを読み込ませます。Geminiモデルは大規模なコンテキストウィンドウを持つため、複数ファイルにまたがるコードベースでも一括で解析可能です。

# プロジェクト全体をAntigravityに読み込ませる
antigravity analyze --project ./src \
  --include "**/*.ts" "**/*.py" \
  --exclude "node_modules/**" "dist/**"

解析結果には、関数のシグネチャ、クラス構造、依存関係、エラーハンドリングパターンなどが含まれます。

ステップ2：テンプレートベースの生成

解析結果を基に、目的に応じたドキュメントテンプレートを指定して生成します。

# API仕様書をOpenAPI形式で生成
antigravity generate --type openapi \
  --source ./src/api \
  --output ./docs/api-spec.yaml

# README.mdを自動生成
antigravity generate --type readme \
  --source ./src \
  --output ./README.md

ステップ3：レビューと微調整

生成されたドキュメントは80〜90%の精度で正確ですが、ビジネスロジックの背景情報やプロジェクト固有の注意事項は人間がレビューして補足する必要があります。

API仕様書の自動生成テクニック

API仕様書の自動生成は、SES現場で最も需要の高いユースケースです。

RESTful APIの仕様書生成

ExpressやFastAPIで構築されたREST APIの仕様書を自動生成するプロンプトテンプレートです。

以下のAPIルーターコードを解析し、OpenAPI 3.0仕様のYAMLを生成してください。

要件:
- 全エンドポイントのパス、メソッド、パラメータ、レスポンスを網羅
- リクエスト/レスポンスのスキーマをcomponentsセクションに定義
- 認証方式（Bearer Token等）をsecuritySchemesに記載
- エラーレスポンス（400, 401, 404, 500）も含める
- 各エンドポイントにdescriptionとsummaryを付与
- 日本語でdescriptionを記述

コード:
[ここにAPIルーターのコードを貼り付け]

このプロンプトで生成されたOpenAPI仕様書は、Swagger UIやRedocでそのまま可視化できます。

GraphQL APIのスキーマドキュメント生成

GraphQL APIの場合は、スキーマ定義からドキュメントを生成します。

# GraphQLスキーマからドキュメントを生成
antigravity generate --type graphql-docs \
  --schema ./src/schema.graphql \
  --output ./docs/graphql/

生成されるドキュメントには、各Query・Mutation・Subscriptionの説明、引数の型と必須/任意の区別、戻り値の構造が含まれます。

設計書の自動生成テクニック

アーキテクチャ設計書

プロジェクトの全体構造を解析し、アーキテクチャ設計書を自動生成できます。以下のプロンプトテンプレートを使用します。

以下のプロジェクト構造とコードを解析し、アーキテクチャ設計書を生成してください。

含めるべきセクション:
1. システム概要（目的、対象ユーザー、主要機能）
2. アーキテクチャパターン（MVC/マイクロサービス/レイヤード等）
3. コンポーネント図（主要モジュールとその責務）
4. データフロー図（リクエストの処理フロー）
5. 外部連携（API、DB、メッセージキュー等）
6. 非機能要件（パフォーマンス、セキュリティ、スケーラビリティ）

出力形式: Markdown
言語: 日本語

プロジェクト構造:
[ここにディレクトリ構造とコードを貼り付け]

データベース設計書

テーブル定義やマイグレーションファイルから、ER図付きのデータベース設計書を生成します。

# マイグレーションファイルからDB設計書を生成
antigravity generate --type db-design \
  --source ./db/migrations \
  --output ./docs/database-design.md \
  --include-er-diagram

生成される設計書には、テーブル一覧、カラム定義（型・制約・デフォルト値）、リレーション、インデックス設計が含まれます。

READMEの自動生成テクニック

優れたREADMEは、プロジェクトの第一印象を決めます。Google Antigravityで、プロフェッショナルなREADMEを自動生成しましょう。

README生成プロンプトテンプレート

以下のプロジェクトを解析し、包括的なREADME.mdを生成してください。

含めるべきセクション:
1. プロジェクト概要（バッジ付き）
2. 主要機能一覧
3. 前提条件（必要なランタイム・ツール）
4. インストール手順（ステップバイステップ）
5. 環境変数の設定（.env.exampleの内容を反映）
6. 使い方（基本的なコマンド・APIの呼び出し例）
7. ディレクトリ構造の説明
8. テストの実行方法
9. コントリビューションガイドライン
10. ライセンス

スタイル: 
- 各セクションに適切な絵文字を使用
- コードブロックにはシンタックスハイライト指定
- 日本語で記述

変更履歴（CHANGELOG）の自動生成

Gitのコミット履歴から、人間が読みやすいCHANGELOGを自動生成する方法も効果的です。

# Gitコミットから変更履歴を生成
antigravity generate --type changelog \
  --from v1.0.0 --to HEAD \
  --output ./CHANGELOG.md \
  --format conventional-commits

CI/CDパイプラインでのドキュメント自動更新

ドキュメントの手動更新は必ず忘れられます。CI/CDパイプラインに組み込むことで、コード変更時にドキュメントが自動更新される仕組みを構築しましょう。

CI/CDとの連携方法の詳細については、Google AntigravityとGitHub Actionsで実現するCI/CDパイプラインも参考にしてください。

GitHub Actionsワークフロー例

name: Auto-update Documentation
on:
  pull_request:
    paths:
      - 'src/**'
      - 'api/**'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Antigravity
        uses: google/antigravity-action@v2
        with:
          api-key: ${{ secrets.ANTIGRAVITY_API_KEY }}
      
      - name: Generate API Docs
        run: |
          antigravity generate --type openapi \
            --source ./src/api \
            --output ./docs/api-spec.yaml
      
      - name: Generate README
        run: |
          antigravity generate --type readme \
            --source ./src \
            --output ./README.md
      
      - name: Check for changes
        id: check
        run: |
          git diff --quiet docs/ README.md || echo "changed=true" >> $GITHUB_OUTPUT
      
      - name: Commit and push
        if: steps.check.outputs.changed == 'true'
        run: |
          git config user.name "antigravity-bot"
          git config user.email "[email protected]"
          git add docs/ README.md
          git commit -m "docs: auto-update documentation"
          git push

このワークフローにより、PRでコード変更があった場合にドキュメントが自動的に更新され、常に最新の状態が維持されます。

ドキュメント差分の検出と通知

コードとドキュメントの乖離を検出し、Slackに通知する仕組みも構築できます。

- name: Check doc freshness
  run: |
    antigravity check --type doc-freshness \
      --source ./src \
      --docs ./docs \
      --threshold 7d \
      --notify slack

SES現場での活用事例

事例1：大規模レガシープロジェクトのドキュメント整備

あるSESプロジェクトでは、10年以上運用されたJavaアプリケーション（約50万行）のドキュメントがほぼ存在しない状態でした。Google Antigravityを使い、以下の成果を達成しています。

• API仕様書: 200以上のエンドポイントのOpenAPI仕様書を3日で生成（手動なら推定2ヶ月）
• 設計書: クラス図・シーケンス図を含むアーキテクチャ設計書を1週間で整備
• README: 環境構築手順書を自動生成し、新規参画者のセットアップ時間を8時間→2時間に短縮

レガシープロジェクトの効率的な改善手法については、Google Antigravity レガシーコード移行ガイドでも詳しく解説しています。

事例2：マイクロサービスのAPI仕様統一

12のマイクロサービスで構成されたシステムで、各サービスのAPI仕様書フォーマットがバラバラだった課題を解決した事例です。

1. Antigravityで全サービスのAPIを統一フォーマット（OpenAPI 3.0）で再生成
2. API Gatewayのドキュメントポータルに統合
3. CI/CDで仕様書の自動更新を設定

結果として、サービス間連携の調査時間が60%削減されました。

ドキュメント自動生成のベストプラクティス

効果的な自動生成のために、以下のベストプラクティスを押さえましょう。ベストプラクティスの全体像については、Google Antigravityのパフォーマンスを最大化するベストプラクティスも参照してください。

1. コードにコメント・型定義を充実させる

AIが正確なドキュメントを生成するためには、入力となるコードの品質が重要です。

// ❌ 悪い例：AIが意図を推測しにくい
function calc(a: any, b: any) {
  return a * b * 1.1;
}

// ✅ 良い例：AIが正確なドキュメントを生成できる
/**
 * 商品の税込価格を計算する
 * @param unitPrice - 商品の単価（税抜）
 * @param quantity - 購入数量
 * @returns 税込合計金額（消費税10%）
 */
function calculateTotalWithTax(unitPrice: number, quantity: number): number {
  return unitPrice * quantity * 1.1;
}

2. ドキュメントテンプレートを標準化する

プロジェクト全体で統一されたテンプレートを使用することで、生成されるドキュメントの品質が安定します。

3. 生成後のレビューフローを確立する

自動生成されたドキュメントは、必ず人間がレビューしてから公開します。特に以下の点を重点的にチェックしましょう。

• ビジネスロジックの説明が正確か
• セキュリティに関する情報が漏洩していないか
• 社内用語・プロジェクト固有の表現が適切か

4. 段階的に導入する

いきなり全ドキュメントを自動生成に切り替えるのではなく、以下の順序で段階的に導入することを推奨します。

1. まずREADME（影響範囲が小さく、効果が見えやすい）
2. 次にAPI仕様書（OpenAPIフォーマットで標準化）
3. 最後に設計書（精度検証を十分に行ってから）

プロンプトエンジニアリングでドキュメント品質を向上させる

より高品質なドキュメントを生成するためのプロンプトテクニックを紹介します。プロンプトエンジニアリングの基本については、Google Antigravity プロンプトエンジニアリング完全ガイドをご覧ください。

コンテキストの明示

あなたは経験豊富なテクニカルライターです。
対象読者: このプロジェクトに新しく参画するSESエンジニア（Java経験3年以上）
目的: プロジェクトの全体像を最短時間で把握できるドキュメントを作成
トーン: 技術的に正確で、かつ簡潔

出力品質の指定

品質基準:
- 曖昧な表現は使わない（「〜のようなもの」→ 具体的に記述）
- 全ての専門用語に初出時の説明を付与
- コード例は必ず動作確認済みのものを使用
- 各セクションは200-400字に収める

まとめ：ドキュメント自動生成でSES現場の生産性を向上させよう

Google Antigravityのドキュメント自動生成機能は、SES現場で最も時間を浪費しがちな「ドキュメント整備」を劇的に効率化します。

主要なポイントの振り返り:

• API仕様書: OpenAPI形式で自動生成し、Swagger UIで可視化
• 設計書: アーキテクチャ設計書・DB設計書をコードから自動生成
• README: プロフェッショナルなREADMEをテンプレートベースで生成
• CI/CD連携: GitHub Actionsでドキュメントの自動更新を実現

まずは小さく始めて、READMEの自動生成から試してみてください。効果を実感できたら、API仕様書、設計書へと段階的に展開しましょう。

Google Antigravityの基本的な使い方については入門ガイドを、チームでの活用についてはチームコラボレーションガイドもあわせてご覧ください。

出典・参考リンク

• Google Antigravity 公式ドキュメント
• OpenAPI Specification 3.0
• Swagger UI
• GitHub Actions ドキュメント
• Conventional Commits