TypeScript と Antigravity を組み合わせることで、AIエージェントによる自動コード生成の恩恵を受けながら、型安全性を損なわない堅牢なフルスタックアプリケーションを構築できます。Antigravity のエージェント機能を最大限に活用しながら、TypeScript の型システムと Zod を使ったバリデーションを組み込む実践的なワークフローを順を追って整理していきます。
この記事で学べること
- Antigravity の TypeScript サポートの仕組みと活用ポイント
- 型安全な API ルートとフロントエンドの構築手順
- Zod スキーマを用いたランタイムバリデーションの統合
- Antigravity エージェントへの効果的な TypeScript プロンプト指示
- よくある型エラーとエージェントを使った解決法
対象読者: TypeScript の基礎知識があり、Antigravity を実務レベルで活用したい開発者。
前提知識・環境準備
まず必要なツールを用意します。
- Google Antigravity（バージョン 1.20 以上）: antigravity.google/download からダウンロード
- Node.js 20 以上
- TypeScript 5.3 以上
Antigravity を起動したら、新規ワークスペースを作成し、以下のプロンプトでプロジェクトを初期化します。
TypeScript フルスタックスターターを作成してください。
Next.js 15 App Router、Zod、Tailwind CSS を使用し、
型安全な API ルートと形式検証を含む構成にしてください。
エージェントがフォルダ構成・package.json・tsconfig.json を自動生成します。
TypeScript プロジェクトの構成と型設計
Antigravity エージェントが生成するフォルダ構成は次のようになります。
my-app/
├── src/
│ ├── app/
│ │ ├── api/
│ │ │ └── users/
│ │ │ └── route.ts ← 型安全な API ルート
│ │ └── page.tsx
│ ├── lib/
│ │ └── schemas.ts ← Zod スキーマ定義
│ └── types/
│ └── index.ts ← 共有型定義
├── tsconfig.json
└── package.json
共有型定義の作成
src/types/index.ts に共有型を定義します。エージェントへのプロンプト例：
src/types/index.ts に以下の型を定義してください：
- User（id, name, email, createdAt）
- CreateUserInput（name, email）
- ApiResponse<T>（data, error, success）
これらは API ルートとフロントコンポーネントで共有します。
エージェントが生成する型定義の例：
// src/types/index.ts
export interface User {
id: string;
name: string;
email: string;
createdAt: Date;
}
export interface CreateUserInput {
name: string;
email: string;
}
export interface ApiResponse<T> {
data: T | null;
error: string | null;
success: boolean;
}Zod によるランタイムバリデーションの統合
TypeScript の型チェックはコンパイル時にしか機能しません。実行時のデータ検証には Zod を使い、型推論と組み合わせます。
src/lib/schemas.ts に Zod スキーマを作成してください：
- CreateUserSchema（name: 2〜50文字、email: メール形式必須）
- 型推論で CreateUserInput 型を自動導出してください
エージェントが生成するスキーマ例：
// src/lib/schemas.ts
import { z } from "zod";
export const CreateUserSchema = z.object({
name: z.string()
.min(2, "名前は2文字以上で入力してください")
.max(50, "名前は50文字以内で入力してください"),
email: z.string()
.email("有効なメールアドレスを入力してください"),
});
// Zod スキーマから TypeScript 型を自動生成
export type CreateUserInput = z.infer<typeof CreateUserSchema>;
// => { name: string; email: string; }（手動型定義と完全一致）z.infer を使うことで、スキーマの変更が型定義に自動反映され、ズレが生じません。
型安全な API ルートの実装
Next.js App Router の API ルートに Zod バリデーションを組み込みます。
// src/app/api/users/route.ts
import { NextRequest, NextResponse } from "next/server";
import { CreateUserSchema } from "@/lib/schemas";
import type { ApiResponse, User } from "@/types";
export async function POST(
request: NextRequest
): Promise<NextResponse<ApiResponse<User>>> {
try {
const body = await request.json();
// Zod でランタイムバリデーション
const result = CreateUserSchema.safeParse(body);
if (!result.success) {
return NextResponse.json(
{
data: null,
error: result.error.errors[0].message,
success: false,
},
{ status: 400 }
);
}
// バリデーション済みデータは型安全に使用可能
const { name, email } = result.data; // CreateUserInput 型が確定
const newUser: User = {
id: crypto.randomUUID(),
name,
email,
createdAt: new Date(),
};
return NextResponse.json({ data: newUser, error: null, success: true });
} catch {
return NextResponse.json(
{ data: null, error: "内部サーバーエラー", success: false },
{ status: 500 }
);
}
}返り値に ApiResponse<User> 型を明示することで、フロントエンドとの型の一貫性が保証されます。
Antigravity エージェントへの TypeScript プロンプト戦略
エージェントに高品質な TypeScript コードを生成させるには、型の制約を明示するプロンプトが重要です。
効果的なプロンプト例
型推論の活用を指示する場合：
ユーザーフォームコンポーネントを作成してください。
- React Hook Form + Zod resolver を使用
- CreateUserSchema の型を zodResolver で接続
- errors オブジェクトの型は UseFormReturn から自動推論させる
- 送信ハンドラーは ApiResponse<User> を受け取り、型安全に処理
型エラーの修正を依頼する場合：
以下の型エラーを修正してください：
"Type 'string | undefined' is not assignable to type 'string'"
user.email が undefined になりうる箇所を特定し、
Non-null assertion の代わりに適切な型ガードを使って修正してください。
AGENTS.md での TypeScript 設定
プロジェクトルートに AGENTS.md を作成し、TypeScript の規約をエージェントに伝えます（Antigravity 1.20 以降 GEMINI.md と共に参照されます）。
# AGENTS.md
## TypeScript 規約
- `any` 型の使用を禁止。`unknown` + 型ガードを使用すること
- 型推論が効く場合は明示的な型アノテーションを省略してよい
- Zod スキーマから `z.infer` で型を導出し、重複した型定義を避ける
- null チェックは Optional Chaining（`?.`）を優先する
- API レスポンスは必ず `ApiResponse<T>` でラップすることよくあるエラーと Antigravity を使った対処法
エラー 1: Property 'X' does not exist on type 'Y'
このエラーはオブジェクトの型定義と実際のプロパティ名のズレで発生します。
Antigravity エージェントへの指示：
TypeScript エラー "Property 'userId' does not exist on type 'User'" を修正してください。
User 型の定義を確認し、プロパティ名の統一（userId か id か）を決定して全ファイルに反映してください。
エージェントがファイル全体を横断して一括修正します。
エラー 2: 非同期関数の型推論ズレ
// ❌ 問題: async 関数の戻り値型が広すぎる
async function fetchUser(id: string) {
const res = await fetch(`/api/users/${id}`);
return res.json(); // Promise<any> になってしまう
}
// ✅ 修正: 明示的な型アノテーション
async function fetchUser(id: string): Promise<ApiResponse<User>> {
const res = await fetch(`/api/users/${id}`);
return res.json() as Promise<ApiResponse<User>>;
}エージェントへの指示：
fetchUser 関数に明示的な戻り値型 Promise<ApiResponse<User>> を追加し、
呼び出し元でも型推論が正しく機能するようにしてください。
エラー 3: Enum vs Union Type の選択
Antigravity がコード生成時に enum を使う場合があります。TypeScript では Union Type の方がツリーシェイクに有利です。
生成されたコードの enum を Union Type に書き換えてください：
status: "pending" | "active" | "inactive"
理由：バンドルサイズ削減と型推論の正確性向上のため。
応用：エージェントを使った型定義の自動同期
大規模プロジェクトでは、バックエンドとフロントエンドの型定義が乖離しがちです。Antigravity エージェントを使って型定義の同期チェックを自動化できます。
src/types/index.ts と src/app/api/**/route.ts を横断的に確認し、
型定義の不整合（プロパティ名・型の違い）をすべてリストアップしてください。
修正が必要な箇所は自動的に修正してください。
Manager Surface（マルチエージェント）を使えば、型チェックエージェントとテストエージェントを並列実行し、CI 相当の品質チェックをローカルで実施できます。
詳しい使い方は Next.js + Antigravity フルスタック開発 および Supabase + Antigravity でバックエンド構築 の記事も参考にしてください。
全体を振り返って
TypeScript + Antigravity の組み合わせは、AIによる高速コード生成と静的型システムによる品質保証を両立させる強力なアプローチです。主なポイントをまとめます。
- Zod +
z.inferでスキーマと型を一元管理し、重複を排除する - AGENTS.md に TypeScript 規約を記述してエージェントの生成品質を向上させる
- API ルートに明示的な型アノテーションを付けることでフロントエンドとの型一貫性を保証する
- Manager Surface を使って型チェックとテストを並列実行し開発速度を上げる
次のステップとして、Vercel + Antigravity デプロイガイド で型安全なアプリを本番環境にデプロイする方法も確認してみてください。