長期プロジェクトで Antigravity の品質を維持する実践ガイド — セッション設計・コンテキスト管理・品質劣化防止の7原則

Antigravity を使い始めた最初の数週間は、何をやっても気持ちよく動きます。でも、プロジェクトが 3 ヶ月・6 ヶ月と続くにつれて、少しずつおかしくなっていきます。

「最初はちゃんと型定義を守ってくれていたのに、いつの間にか any を使い始めた」「決めたはずのアーキテクチャを無視してコードを書き始めた」「前回解決した同じバグを、また同じように書いてくる」

これらは Antigravity の能力が下がったのではなく、プロジェクトのコンテキストが劣化した結果です。Antigravity は「今見えているもの」で判断します。見えているものが不明瞭・矛盾・過去の汚れを含んでいれば、出力も同様になります。

長期プロジェクトで品質を維持するための 7 つの実践原則を順を追って整理していきます。

品質劣化の3つの原因

対策の前に、原因を整理します。

原因 1：コンテキスト汚染

プロジェクトの開始時にあったルール、その後変更されたルール、一時的な実験コード、リファクタリング途中のコードが混在し始めます。Antigravity は「新しいコンテキスト」に引きずられます。現在のコードが古いルールで書かれていれば、そのルールが「現在のプロジェクトの標準」だと解釈されます。

原因 2：agents.md の劣化

多くのプロジェクトで agents.md（または AGENTS.md、.antigravity/rules）は「書いたきり更新しない」状態になります。コードが変化してもドキュメントは最初の状態のまま。Antigravity がドキュメントと実コードの矛盾する情報を見て、どちらを信頼するかを間違えます。

原因 3：技術的負債の蓄積

型定義が複数箇所に散在する、同じ処理が微妙に違う実装で存在する、コメントアウトされたコードが残存します。こうした「ノイズ」が増えると、Antigravity のパターン認識精度が下がります。

原則 1：agents.md をリビングドキュメントとして管理する

agents.md は「最初に書く仕様書」ではなく、「常に現在の状態を反映する生きたドキュメント」として管理します。

私が採用している構造です。

# PROJECT_NAME — Antigravity Context
 
## 現在のアーキテクチャ（必ず最新を保つ）
最終更新: 2026-05-01
 
### ディレクトリ構成
src/
  features/      # 機能ごとのモジュール
  shared/        # 共通コンポーネント
  infrastructure/# APIクライアント・DB
 
### 設計決定（ADR形式）
- [2026-03-15] データ取得: SWR → TanStack Query に移行
  理由: サスペンスモード対応のため
  影響: src/features/*/hooks/*.ts すべて
 
## 現在使用している主要ライブラリとバージョン
（package.json の内容を週次で同期）
 
## 命名規則（現在有効なもの）
- コンポーネント: PascalCase
- カスタムフック: useCamelCase  
- 定数: SCREAMING_SNAKE_CASE
- ※2026-04以降: camelCase廃止、すべてconst使用
 
## やってはいけないこと（Negative Rules）
- `any` 型を使わない（eslint-disable で一時的に許容する場合は要コメント）
- console.log を本番コードに含めない
- コンポーネント内に500行以上のロジックを書かない

最も重要なのは Negative Rules のセクションです。「何をすべきか」より「何をしてはいけないか」のほうが、Antigravity の制御には効果的です。

原則 2：セッションを目的で分割する

長いセッションは品質劣化の温床です。1 つのセッションで多くのことをやろうとすると、コンテキストが混乱します。

セッションの種類を分けます。「設計セッション」では新しい機能の設計と仕様決定だけを行い、コードは書きません。「実装セッション」では決まった仕様の実装だけを行います。「リファクタセッション」では既存コードの改善だけを行い、機能追加はしません。「デバッグセッション」では問題の診断と修正だけを行います。

この分割をするだけで、Antigravity のコンテキストが目的に集中して、出力の品質が体感で上がります。特に「設計と実装を同じセッションでやる」ことをやめるだけで、設計の一貫性が大きく改善されます。

原則 3：セッション開始時の「文脈注入」を習慣にする

新しいセッションを始めるとき、必ず以下のフォーマットで状況を渡します。

## 今日の作業コンテキスト

**プロジェクト**: [プロジェクト名]
**現在のフォーカス**: [具体的な機能名 or ファイル名]
**前回までの進捗**: 
- ✅ ユーザー認証フロー完成
- ✅ 商品一覧APIの基本実装完成  
- 🔄 カート機能実装中（CartContextまで作成済み）
**今日の目標**: CartContext に在庫チェックロジックを追加する
**守ってほしい制約**:
- TypeScriptの型は必ずexplicitに書く
- 在庫APIはsrc/infrastructure/inventory.tsのみから呼ぶ
**参照ファイル**: src/features/cart/CartContext.tsx, src/infrastructure/inventory.ts

この「文脈注入」を省略してすぐに「在庫チェックのロジックを書いて」と言うと、Antigravity はプロジェクト全体のコンテキストなしに汎用的なコードを書き始めます。文脈を与えれば、プロジェクトの規約・既存の設計・今日の目標を理解した上でコードを書いてくれます。

原則 4：定期的なコンテキストリセットを実行する

月に 1 回程度、意図的にコンテキストを「リセット」する作業を行います。

具体的には以下の手順です。

新しいチャットセッションを開き、agents.md だけを貼り付けます。「このドキュメントを読んで、現在のプロジェクトの状態について質問してください」と指示します。Antigravity が「この点が不明瞭です」「ここに矛盾があります」と指摘してきます。その指摘を元に agents.md を更新します。

これは「コードを見ずに agents.md だけで状況が把握できるか」のテストです。できない場合は agents.md が劣化しています。

原則 5：技術的負債を「見えるリスト」にする

解決していない技術的負債を Antigravity が見えない形で蓄積させると、品質劣化の原因になります。agents.md の中に「Known Issues」セクションを作り、意図的な負債を明示します。

## Known Issues（意図的な技術的負債）
 
### 優先度: 高
- [ ] src/features/auth/tokens.ts: JWTの検証ロジックが簡易実装
  詳細: 署名検証を省いている。本番リリース前に修正必須
  
### 優先度: 中  
- [ ] src/shared/hooks/useDebounce.ts: タイムアウトのクリーンアップが不完全
  詳細: コンポーネントのアンマウント時にタイマーが残る可能性
 
### 優先度: 低（意図的に放置）
- [ ] 一部コンポーネントにハードコードされた文字列（i18n対応前）

このリストがあることで「ここは意図的にこうなっている」という情報を Antigravity に与えられます。負債を修正しようとして予期しない変更を加えることを防げます。

原則 6：「役割の明確化」でリファクタリングセッションを運営する

リファクタリングセッションは最も品質が乱れやすいです。「改善」と「機能変更」が混ざりやすいからです。

リファクタセッションを始めるときは必ずこのプロンプトを最初に送ります。

このセッションでは既存コードのリファクタリングのみを行います。
機能の追加・変更・削除は行いません。
以下のファイルを対象にします：[ファイル名]

リファクタリングの目的：
- [具体的な目的（例: 型安全性の向上）]

リファクタリング後も変わらないこと：
- 外部から見たAPIの振る舞い（入出力）
- ファイルの責務

このルールが守られているか確認しながら作業してください。

この「役割の明確化」を行うと、Antigravity が「機能も改善しちゃおう」という余計なことをしなくなります。

原則 7：アウトプットのレビューパターンを作る

長期プロジェクトでは、生成されたコードを惰性でマージしてしまうことが品質劣化の一因です。以下の 3 段階レビューを習慣にすることで、品質の低下を早期に検知できます。

まず「型安全性チェック」として TypeScript の型エラーがないか、any が使われていないかを確認します。次に「命名規則チェック」として agents.md の規則に従っているかを確認します。最後に「アーキテクチャチェック」として決めた層の分離（例：コンポーネントに直接 API コールを書いていない）が守られているかを確認します。

これらは手動でやるのは大変ですが、CI に以下のチェックを入れておくと自動化できます。

# .github/workflows/quality-check.yml
- name: TypeScript strict check
  run: npx tsc --noEmit --strict
 
- name: ESLint (no-any, no-explicit-any)
  run: npx eslint src --rule '{"@typescript-eslint/no-explicit-any": "error"}'
 
- name: Import boundary check
  run: npx eslint src --rule '{"no-restricted-imports": ["error", {"patterns": ["../../"]}]}'

全体を振り返って：コンテキストの品質を保つことが、出力の品質を保つ

Antigravity の出力品質は、コードの品質とコンテキストの品質の掛け算です。

コードをきれいに保っても、agents.md が古く・矛盾していれば品質は落ちます。逆に agents.md が完璧でも、コードが負債だらけなら同じです。両方を継続的に整備することが、長期プロジェクトでの品質維持の本質です。

7 つの原則の中で、まず始めるべきは「agents.md をリビングドキュメントとして管理する」ことです。これだけでも、長期プロジェクトでの Antigravity との作業の質は大きく変わります。