Antigravity コンテキスト・エンジニアリング上級マスターガイド：大規模プロジェクトでAIの精度を実用範囲で活かす実践技法

# Project Intelligence — [プロジェクト名]
 
## Architecture Philosophy
このプロジェクトは「Hexagonal Architecture（Ports & Adapters）」を採用している。
**理由**: ビジネスロジックをインフラ実装から分離し、テスト可能性と移植性を最大化するため。
 
### 意思決定の優先順位
1. 既存パターンに従う（新しいパターンを発明するより一貫性を優先）
2. TypeScript の型安全性を妥協しない（`as unknown as` は原則禁止）
3. エラーは必ず `Result<T, E>` 型で返す（例外スローは UI 層のみ許可）
 
## Domain Vocabulary（ドメイン用語定義）
- **Listing**: 物件情報の単位。`Property` と混同しないこと（Property は法的所有権の概念）
- **Offer**: ユーザーが送信した購入意向。`Bid` とは異なる（Bid はオークション型のみ）
- **Escrow**: 第三者保管状態。必ず法務チェック済みのワークフローを経ること
 
## What NOT to Do
- [ ] ビジネスロジックを `src/infrastructure/` に書かない
- [ ] `console.log` を本番コードに残さない（必ず `logger.info()` を使う）
- [ ] Stripe の price ID をハードコードしない（必ず `config/pricing.ts` 経由）
- [ ] DB アクセスを UI コンポーネントから直接行わない
 
## Uncertainty Protocol
不明点がある場合の対応順序:
1. `src/docs/decisions/` の ADR（Architecture Decision Records）を参照
2. 既存の類似実装パターンを踏襲
3. 上記で判断できない場合、実装前に必ず確認を求める

# scripts/inject-context.sh
#!/bin/bash
# 現在の作業コンテキストをセッション開始時に注入するスクリプト
 
SPRINT_FILE=".antigravity/current-sprint.md"
MODULE_FILE=".antigravity/current-module.md"
 
if [ -f "$SPRINT_FILE" ]; then
  echo "## 📍 Current Sprint Context"
  cat "$SPRINT_FILE"
  echo ""
fi
 
if [ -f "$MODULE_FILE" ]; then
  echo "## 🔧 Active Module Context"
  cat "$MODULE_FILE"
  echo ""
fi
 
echo "## ⚠️ Active Workarounds"
cat ".antigravity/workarounds.md" 2>/dev/null || echo "（現在なし）"

# 認証フロー — Why This Design
 
## 現在の実装
JWT + Refresh Token のローテーション方式を採用。
 
## なぜ Session Cookie を使わないのか
- Cloudflare Workers 環境での SameSite 制約
- CDN エッジでのセッション同期コストの問題
- この決定は 2025-11 のインシデント #143 を受けて変更済み
 
## 今後の変更予定
2026-Q3 に Passkey 対応を追加予定（design-doc/passkey-migration.md 参照）

# ❌ 冗長な書き方（コンテキストを無駄に消費）
ユーザーが商品をカートに追加する際は、まず在庫データベースをチェックし、
在庫がある場合はカートテーブルに追加し、在庫がない場合はエラーを返します。
また、プレミアム会員の場合は最大10個まで追加でき、通常会員は5個までです。
さらにセール期間中は数量制限が変わることがあり...
 
# ✅ 圧縮された書き方（同じ情報をコンパクトに）
カート追加ロジック:
- 在庫チェック → カート追加 or StockError
- 数量上限: Premium=10 / Standard=5 / セール中は config/sale-limits.ts 参照
- 実装: src/domain/cart/CartService.ts の `addItem()` メソッド

## AI Interaction Patterns — What Worked
 
### 効果的だったプロンプトパターン
1. 「〜のみを修正し、他には手を加えないでください」
   → スコープを明確にすることで副作用が減少
2. 「修正前に変更内容の要約を出力してください」
   → 予期しない変更を事前にキャッチできる
3. 「既存のテストが通ることを確認してから提示してください」
   → 回帰バグを防止
 
### 避けるべきパターン
- 「ベストプラクティスで実装してください」（判断基準が曖昧）
- 「パフォーマンスを改善してください」（測定基準がない）
- 「全体的にきれいにしてください」（スコープが不明確）

## Weekly Context Review Agenda
 
1. AGENTS.md の変更差分確認（git diff main -- AGENTS.md）
2. 先週追加された Knowledge Items のレビュー
3. 「今週 AI に修正させた一時的な回避策」の共有
4. 永続化すべきパターン vs 削除すべき一時情報の仕分け
5. 来週の作業コンテキストの事前設計

# AGENTS.md 変更時の必須チェックリスト（git hook として設定）
#!/bin/bash
# .git/hooks/pre-commit
 
if git diff --cached --name-only | grep -q "AGENTS-md"; then
  echo "⚠️  AGENTS.md が変更されています"
  echo "変更前に以下を確認してください:"
  echo "  1. 変更はチームで合意済みですか？"
  echo "  2. 既存のルールと矛盾していませんか？"
  echo "  3. 理由（Why）は記述しましたか？"
  read -p "続行する場合は 'yes' を入力してください: " confirm
  if [ "$confirm" != "yes" ]; then
    exit 1
  fi
fi

# ADR-042: 検索機能のリアルタイム化
 
## 決定
WebSocket ではなく Server-Sent Events (SSE) を採用
 
## 理由（Antigravity Planning Mode で検討）
- WebSocket: Cloudflare Workers でのサポートが限定的
- SSE: 一方向ストリームで要件を満たし、インフラコストが低い
 
## Antigravity への指示
このファイルを参照する際は：
- 検索の「リアルタイム」実装は必ず SSE を使うこと
- WebSocket の提案は却下済みであることを前提とすること

#!/usr/bin/env python3
"""
scripts/validate-context.py
AGENTS.md と Knowledge Items の品質を検証するスクリプト
"""
 
import re
import sys
from pathlib import Path
 
def validate_agents_md(filepath: Path) -> list[str]:
    """AGENTS.md の品質チェック"""
    errors = []
    content = filepath.read_text(encoding='utf-8')
 
    # 必須セクションのチェック
    required_sections = [
        "## Architecture Philosophy",
        "## What NOT to Do",
        "## Uncertainty Protocol",
    ]
    for section in required_sections:
        if section not in content:
            errors.append(f"Missing required section: {section}")
 
    # ルールに「なぜ」が欠けているかチェック
    rules = re.findall(r'- \[ \] (.+)', content)
    for rule in rules:
        if len(rule) < 20:  # 短すぎるルールは理由が省略されている可能性
            errors.append(f"Rule may be missing context: '{rule}'")
 
    # 非推奨マークなしの古い日付参照をチェック
    old_dates = re.findall(r'202[34]-\d{2}', content)
    if old_dates:
        errors.append(f"Old date references found (consider updating): {old_dates}")
 
    return errors
 
def validate_knowledge_items(directory: Path) -> list[str]:
    """Knowledge Items のディレクトリ構造チェック"""
    errors = []
    md_files = list(directory.glob("**/*.md"))
 
    for filepath in md_files:
        content = filepath.read_text(encoding='utf-8')
        word_count = len(content.split())
 
        # 単一ファイルが大きすぎる場合
        if word_count > 2000:
            errors.append(
                f"{filepath.name}: {word_count} words — consider splitting into smaller files"
            )
 
        # 「なぜ」のセクションが欠けている場合
        if "## Why" not in content and "## なぜ" not in content and word_count > 300:
            errors.append(f"{filepath.name}: Missing 'Why' section")
 
    return errors
 
if __name__ == "__main__":
    errors = []
 
    agents_path = Path("AGENTS-md")
    if agents_path.exists():
        errors.extend(validate_agents_md(agents_path))
 
    knowledge_dir = Path(".antigravity/knowledge")
    if knowledge_dir.exists():
        errors.extend(validate_knowledge_items(knowledge_dir))
 
    if errors:
        print("❌ Context validation failed:")
        for error in errors:
            print(f"  - {error}")
        sys.exit(1)
    else:
        print("✅ Context validation passed")

#!/bin/bash
# scripts/context-dashboard.sh
 
echo "=== Antigravity Context Quality Dashboard ==="
echo ""
 
# AGENTS.md の統計
echo "📋 AGENTS.md Stats:"
AGENTS_WORDS=$(wc -w < AGENTS.md)
AGENTS_RULES=$(grep -c "- \[ \]" AGENTS.md || echo 0)
echo "  - Word count: $AGENTS_WORDS"
echo "  - Defined rules: $AGENTS_RULES"
echo ""
 
# Knowledge Items の統計
echo "📚 Knowledge Items:"
TOTAL_FILES=$(find .antigravity/knowledge -name "*.md" 2>/dev/null | wc -l)
TOTAL_WORDS=$(find .antigravity/knowledge -name "*.md" 2>/dev/null -exec wc -w {} + | tail -1 | awk '{print $1}')
echo "  - Total files: $TOTAL_FILES"
echo "  - Total words: $TOTAL_WORDS"
echo ""
 
# 最終更新日
echo "🕐 Last Context Updates:"
git log --oneline --since="7 days ago" -- AGENTS.md .antigravity/ 2>/dev/null | head -5
echo ""
 
echo "=== Dashboard Complete ==="