◉ANTIGRAVITY LABEN
記事一覧/Antigravity 基本
◉ Antigravity 基本/2026-03-15上級

Antigravity コンテキスト設計 — AGENTS.md と Knowledge Items で AI に「伝わる」プロジェクトを作る

Antigravity が最大限に力を発揮するためのコンテキスト設計を解説。AGENTS.md の書き方・Knowledge Items の活用・チーム開発での共有方法まで、AI に「伝わる」プロジェクト構成術を体系化します。

AGENTS.md12context7knowledge itemsproject setuppremium15

取り組みの背景 — なぜ同じ Antigravity でも「精度に差」が出るのか

同じ Antigravity を使っていても、開発者によって出力品質に大きな差が生まれます。その差の大半は「コンテキストの質」に起因します。

Antigravity は、プロジェクトのコード・ドキュメント・設定ファイルを読み込んでコンテキストを形成します。しかし何も手を加えなければ、Antigravity が把握するのは「コードの表面的な構造」だけです。プロジェクトの背景・意図・制約・規約を明示的に伝えることで、提案の精度は劇的に向上します。

柱1：AGENTS.md — プロジェクトの「説明書」

AGENTS.md とは

AGENTS.md はプロジェクトルートに置く Markdown ファイルで、Antigravity がセッション開始時に自動で読み込む特別なファイルです。「このプロジェクトで AI に最初に伝えておきたいこと」を書く場所です。

基本構成テンプレート

# プロジェクト概要
 
## このプロジェクトについて
[プロジェクト名] は [目的] のための [技術スタック] アプリケーションです。
対象ユーザー：[ユーザー像]
規模：[DAU/MAU/チーム規模等]
 
## 技術スタック
- フロントエンド：Next.js 15 (App Router), TypeScript, Tailwind CSS
- バックエンド：Hono (Cloudflare Workers), Zod
- データベース：Supabase (PostgreSQL), Drizzle ORM
- 認証：Supabase Auth
- テスト：Vitest, Playwright
 
## ディレクトリ構成
src/
├── app/           # Next.js App Router のページ
├── components/    # 再利用可能な UI コンポーネント
│   ├── ui/        # 基本 UI (Button, Input 等)
│   └── features/  # 機能単位のコンポーネント
├── hooks/         # カスタムフック
├── lib/           # ユーティリティ・サービス層
└── types/         # TypeScript 型定義
 
## コーディング規約
- コンポーネント：PascalCase、1ファイル1コンポーネント
- フック：useXxx 命名、src/hooks/ に配置
- エラーハンドリング：src/lib/errors.ts の AppError クラスを使う
- API コール：src/lib/api.ts のラッパー関数を使う（直接 fetch しない）
- 状態管理：サーバー状態は TanStack Query、UI 状態は useState
 
## 禁止事項
- src/app/ 以外に直接 fetch を書かない
- console.log を本番コードに残さない
- any 型を使わない（やむを得ない場合はコメントで理由を書く）
 
## 現在の開発状況
- 完了：ユーザー認証、プロフィール表示、記事一覧
- 進行中：コメント機能（src/features/comments/）
- 未着手：通知機能、フォロー機能

「伝えるべき情報」の優先順位

AGENTS.md に書く情報の優先順位は次の通りです。

**最優先（必ず書く）**として、使用技術のバージョン（Next.js 15 と 14 では App Router の動作が異なる）、プロジェクト固有のパターン（独自のエラーハンドリング・API ラッパー等）、禁止事項（チームで決めたアンチパターン）が挙げられます。

**推奨（書くと精度が上がる）**として、ディレクトリ構成と責務、主要な型定義の場所、テストの書き方の方針があります。

**任意（余裕があれば）**として、将来の拡張予定、パフォーマンス・セキュリティの要件、ビジネスドメインの用語集が挙げられます。

柱2：Knowledge Items — 繰り返し参照する情報の管理

Knowledge Items の概念

Knowledge Items は Antigravity の Manager Surface で管理できる「再利用可能なコンテキストブロック」です。AGENTS.md がプロジェクト全体の概要なら、Knowledge Items は「特定のトピックに関する詳細な参照情報」です。

// Knowledge Item の活用例：API 仕様書
 
// Item名: "API認証仕様"
// 内容:
/*
## 認証フロー
 
全 API リクエストには Authorization ヘッダーが必要。
形式: Authorization: Bearer {JWT_TOKEN}
 
### トークン取得
POST /api/auth/login
Body: { email: string, password: string }
Response: { accessToken: string, refreshToken: string, expiresIn: number }
 
### トークンリフレッシュ
POST /api/auth/refresh
Body: { refreshToken: string }
Response: { accessToken: string, expiresIn: number }
 
### エラーコード
401: トークン無効または期限切れ
403: 権限不足
*/
 
// この Knowledge Item を参照させるコマンド例:
// "@API認証仕様 を参照して、この API クライアントに認証を実装して"

効果的な Knowledge Items の分類

Knowledge Items の構成例:

├── API仕様/
│   ├── 認証フロー          # JWT・OAuth の詳細仕様
│   ├── エラーコード一覧     # 全エラーコードと対処法
│   └── レートリミット      # 制限値とリトライ戦略
│
├── UIコンポーネント/
│   ├── デザインシステム     # カラー・スペーシング・タイポグラフィ
│   ├── アニメーション規約   # transition・timing 統一ルール
│   └── アクセシビリティ    # ARIA・キーボード操作の要件
│
├── データベース/
│   ├── スキーマ概要        # 主要テーブルとリレーション
│   ├── クエリパターン      # よく使う Drizzle ORM のパターン
│   └── マイグレーション方針
│
└── ビジネスロジック/
    ├── 料金計算ロジック    # 割引・税計算の仕様
    └── 権限モデル         # ロール・パーミッションの定義

柱3：プロジェクト構造でコンテキストを伝える

ファイル名・ディレクトリ名による暗示的なコンテキスト

Antigravity はファイル構造からも多くのコンテキストを読み取ります。命名規則を一貫させることで、指示なしでも適切な実装を行います。

// ✅ コンテキストが伝わる構造

src/
├── features/
│   ├── auth/
│   │   ├── components/     # 認証関連 UI
│   │   ├── hooks/          # 認証関連フック
│   │   ├── api.ts          # 認証 API コール
│   │   └── types.ts        # 認証関連型定義
│   └── comments/
│       ├── components/
│       ├── hooks/
│       ├── api.ts
│       └── types.ts
└── shared/
    ├── components/ui/      # 汎用 UI コンポーネント
    └── lib/                # 汎用ユーティリティ

// この構造なら「コメント機能に認証が必要なフックを追加して」という指示で
// Antigravity は自動的に src/features/comments/hooks/ に配置しようとする

型定義ファイルの充実

型定義が充実しているプロジェクトでは、Antigravity の提案精度が高くなります。

// src/types/domain.ts — ドメイン型を一箇所に集約
 
export interface User {
  id: string;
  email: string;
  displayName: string;
  avatarUrl: string | null;
  role: "admin" | "member" | "guest";
  createdAt: Date;
  updatedAt: Date;
}
 
export interface Article {
  id: string;
  title: string;
  slug: string;
  content: string;
  authorId: string;
  author?: User;          // リレーション（オプショナル）
  publishedAt: Date | null;
  status: "draft" | "published" | "archived";
  tags: string[];
}
 
export interface Comment {
  id: string;
  articleId: string;
  authorId: string;
  author?: User;
  content: string;
  createdAt: Date;
  updatedAt: Date;
  deletedAt: Date | null;  // ソフトデリート
}
 
// ユーティリティ型
export type WithPagination<T> = {
  items: T[];
  total: number;
  page: number;
  perPage: number;
  hasNext: boolean;
};

チーム開発でのコンテキスト共有

AGENTS.md をチームで維持する

AGENTS.md は .gitignore に入れず、チームの共有ドキュメントとして管理します。

# チーム開発での AGENTS.md 更新ルール
 
## 更新するタイミング
- 新しいライブラリを追加したとき
- コーディング規約を変更したとき
- 新しいパターン（エラーハンドリング等）を確立したとき
- アーキテクチャの方針を変えたとき
 
## 更新方法
1. 変更を PR に含める（コード変更と一緒に）
2. PR レビュー時に AGENTS.md の変更も確認対象にする
 
## 効果測定
月1回、チームで「Antigravity の提案が意図通りだったか」を振り返り、
AGENTS.md に不足していた情報を追記する

「プロジェクト固有パターン」の文書化

チームで決めたパターンを AGENTS.md に明記することで、新メンバーがすぐに Antigravity を使いこなせるようになります。

## よく使うパターン
 
### API エラーハンドリング
```typescript
// src/lib/api.ts の apiClient を使う
const { data, error } = await apiClient.get<User>(`/users/${id}`);
if (error) {
  // AppError 型が返る
  toast.error(error.userMessage);
  return;
}
// data は型安全

フォームバリデーション

React Hook Form + Zod を組み合わせる。 スキーマは src/lib/schemas/ に配置。

日付フォーマット

date-fns を使う。moment.js は使用禁止。 タイムゾーンは常に JST で表示。


---

## 実践：コンテキスト設計の改善ステップ

新しいプロジェクトにコンテキスト設計を導入する場合、段階的に改善します。

**Week 1（最低限）**: プロジェクト概要・技術スタック・ディレクトリ構成を AGENTS.md に書く。これだけで「間違ったライブラリを使う提案」が大幅に減ります。

**Week 2（中程度）**: コーディング規約・禁止事項・主要パターンを追加します。「レビューで毎回同じ指摘をしていること」を AGENTS.md に書くと効果的です。

**Week 3（本格運用）**: Knowledge Items を作成します。API 仕様・スキーマ・ビジネスロジックを Knowledge Items に整備すると、複雑な実装タスクの精度が向上します。

**Month 2 以降（継続改善）**: 「Antigravity の提案がずれていた」ケースをメモし、月1回 AGENTS.md を更新します。

---

## 個人開発者の視点から（実体験メモ）

## ここまでの要点
Antigravity のコンテキスト設計は「どれだけ正確に AI に伝えるか」の技術です。AGENTS.md・Knowledge Items・プロジェクト構造の3つを整えることで、Antigravity の提案はプロジェクト固有のパターンに沿った高精度なものになります。

特に重要なのは AGENTS.md の「禁止事項」セクションです。「やってほしくないこと」を明示することで、コードレビューで繰り返す同じ指摘が激減します。

関連記事としてAGENTS.md 活用ガイドや[AI パートナーとの日常開発ワークフロー](/articles/tips/ai-partner-daily-workflow)も参考にしてください。
シェア

お読みいただきありがとうございます

Antigravity Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ（¥150）で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

◉ Antigravity 基本2026-06-24
Antigravity 4サーフェスを1案件で組み合わせる — SDKで自作エージェントを動かすまで
Antigravity 2.0・CLI・IDE・SDK を1つの案件の中でどう使い分け、どう橋渡しするか。設計の発散から本番の収束、そして Python SDK で小さなカスタムエージェントを動かすところまでを、実際の運用フローに沿って実装込みで解説します。
◉ Antigravity 基本2026-05-31
独立した複数リポジトリでエージェント運用の一貫性を保つ — マルチリポ・ガバナンス設計の実装メモ
monorepo ではなく、独立した複数リポジトリにまたがって Antigravity エージェントの振る舞いを揃える設計手法を、4サイト並行運用の実体験から整理しました。AGENTS.md の単一ソース配布、ドリフト検出、品質ゲートの横展開までを実装コード付きで解説します。
◉ Antigravity 基本2026-05-29
Antigravity の Inspector を1ヶ月運用して見えた、エージェント挙動の読み解き方
Antigravity の Inspector を本気で運用に組み込んだ1ヶ月の所感です。壁紙アプリ4本の保守で何が見えて、何が変わったか。エージェントの内部判断を読み解く手順と、見落としやすい落とし穴をまとめました。
📚RECOMMENDED BOOKS
大規模言語モデル入門
山田育矢
LLM開発
生成AIプロンプトエンジニアリング入門
我妻幸長
プロンプト
Claude CodeによるAI駆動開発入門
平川知秀
AI駆動開発
※ アフィリエイトリンクを含みます
もっと見る →