ponshu-room-lite/docs/architecture/AI_COLLABORATION_PROTOCOL.md

# 🤝 AI同士の直接連携プロトコル（伝書鳩脱却計画）

**作成日**: 2026-01-19
**目標**: 開発者が仲介しなくても、Claude ↔ Gemini ↔ Antigravity が直接情報を共有・更新できる仕組み
**実現期限**: Phase 2.0-B 完了後（4週間以内）

---

## 🎯 現状の問題点

### **現在のフロー（非効率）**

```
Claude（アーキテクチャ決定）
    ↓ 開発者がコピペ
Gemini（図表生成依頼）
    ↓ 開発者が画像をダウンロード
Antigravity（レビュー依頼）
    ↓ 開発者がフィードバックを転記
Claude（修正）
    ↓ 開発者がまたコピペ...

開発者 = 伝書鳩 😩
```

### **問題点**

1. **時間のロス**: コピペに5-10分/回 × 10回/日 = 50-100分/日
2. **情報の劣化**: 要約や誤転記のリスク
3. **開発者の疲弊**: 本来の開発に集中できない
4. **リアルタイム性の欠如**: AIの議論が非同期になる

---

## 🚀 目指すべき理想の姿

### **理想のフロー（自動化）**

```
Claude（アーキテクチャ決定）
    ↓ 自動で docs/ に書き込み
    ↓ Webhook発火
Gemini（変更を検知、図表を自動生成）
    ↓ 生成した画像を docs/images/ に保存
    ↓ Slack通知
Antigravity（通知を受け取り、レビュー）
    ↓ コメントを docs/reviews/ に書き込み
    ↓ Webhook発火
Claude（フィードバックを自動読み込み、修正）

開発者 = 最終承認のみ ✅
```

---

## 🛠️ 実装方法（3つのアプローチ）

### **アプローチ1: Git + Webhook（短期実装・推奨）**

**仕組み**:
1. すべてのAIが同じGitリポジトリにアクセス
2. ファイル変更をコミット → Webhook発火
3. 各AIが通知を受け取り、自動処理

**メリット**:
- ✅ 実装が簡単（既存のGitea活用）
- ✅ バージョン管理が自動
- ✅ 差分が明確

**デメリット**:
- ⚠️ AIが直接Gitにコミットする仕組みが必要

**実装ステップ**:

```bash
# 1. Gitea にAI専用ユーザー作成
# Giteaで: Settings → Users → Create New User
# Username: claude-bot, gemini-bot, antigravity-bot

# 2. 各AIにアクセストークン発行
# Giteaで: User Settings → Applications → Generate New Token

# 3. Claudeがドキュメント更新時に自動コミット
# Claude側（MCP経由で実装）:
git config user.name "Claude Bot"
git config user.email "claude@posimai.local"
git add docs/architecture/
git commit -m "feat(arch): Update architecture decision"
git push origin main

# 4. Webhook設定（Giteaで）
# URL: https://gemini-webhook.example.com/on-commit
# Trigger: Push events
# Target: docs/architecture/**

# 5. Geminiが受け取る
# Gemini側:
# - Webhookを受信
# - 変更ファイルを読み取り
# - 図表生成が必要か判定
# - 必要なら画像生成 → docs/images/ にコミット
```

---

### **アプローチ2: Notion API（中期実装）**

**仕組み**:
1. Notionをマスターデータベースとして使用
2. 各AIがNotion APIで読み書き
3. リアルタイム同期

**メリット**:
- ✅ UI/UXが優れている（人間も見やすい）
- ✅ リアルタイム更新
- ✅ コメント・レビュー機能が標準

**デメリット**:
- ⚠️ Notion APIの習得が必要
- ⚠️ 外部サービス依存（データ主権の観点で懸念）

**実装ステップ**:

```javascript
// 1. Notion Integration作成
// https://www.notion.so/my-integrations

// 2. Claude側の実装例（MCP経由）
const { Client } = require('@notionhq/client');
const notion = new Client({ auth: process.env.NOTION_API_KEY });

// アーキテクチャページを更新
await notion.pages.update({
  page_id: 'architecture-page-id',
  properties: {
    'Status': { status: { name: 'Updated' } },
    'Last Updated': { date: { start: new Date().toISOString() } }
  }
});

// 3. Geminiが変更を検知
// Notion Webhook（Beta機能）を使用
// または、定期的にポーリング（1分ごと）

// 4. Antigravityがコメントを追加
await notion.comments.create({
  parent: { page_id: 'architecture-page-id' },
  rich_text: [{
    text: { content: 'このアーキテクチャは良いが、メモリ配分を再検討すべき。' }
  }]
});
```

---

### **アプローチ3: MCP（Model Context Protocol）（長期実装）**

**仕組み**:
1. Claude Code のMCPサーバーを拡張
2. ファイルシステム監視 + AIエージェント連携
3. 完全自動化

**メリット**:
- ✅ 最も自動化度が高い
- ✅ ローカル完結（データ主権維持）
- ✅ Claude Codeとの深い連携

**デメリット**:
- ⚠️ 実装が複雑
- ⚠️ MCPの理解が必要

**実装ステップ**:

```typescript
// MCP Server 実装例
// mcp-server-posimai/src/index.ts

import { McpServer } from '@anthropic/mcp-server';
import { watch } from 'fs';
import { exec } from 'child_process';

const server = new McpServer({
  name: 'posimai-collaboration',
  version: '1.0.0',
});

// docs/ フォルダを監視
watch('docs/architecture', { recursive: true }, async (event, filename) => {
  console.log(`File changed: ${filename}`);

  // 1. 変更内容を解析
  const content = await fs.readFile(`docs/architecture/${filename}`, 'utf-8');

  // 2. Geminiに通知（HTTP POST）
  if (filename.includes('.md')) {
    await fetch('https://gemini-webhook.example.com/notify', {
      method: 'POST',
      body: JSON.stringify({
        type: 'document_updated',
        file: filename,
        content: content,
      }),
    });
  }

  // 3. Antigravityにメール通知
  exec(`echo "ドキュメント更新: ${filename}" | mail -s "Posimai Update" antigravity@example.com`);
});

server.listen(3001);
```

---

## 📅 実装ロードマップ

### **Phase 1: 手動からセミ自動へ（Week 1-2）**

```
現在: 開発者がすべて転記
    ↓
Week 1: 共有Gitリポジトリ作成
Week 2: Webhook設定
    ↓
結果: AIがファイルを監視できる
```

**実装タスク**:
- [ ] Giteaにドキュメント専用リポジトリ作成
- [ ] Claude用アクセストークン発行
- [ ] Webhook URL設定（テスト用）

---

### **Phase 2: Geminiの自動図表生成（Week 3-4）**

```
現在: 開発者がGeminiにプロンプトをコピペ
    ↓
Week 3: Gemini Webhookエンドポイント作成
Week 4: 自動図表生成スクリプト実装
    ↓
結果: .md更新 → 自動で画像生成
```

**実装タスク**:
- [ ] Gemini API統合（Cloud Functions or VM上）
- [ ] 画像生成トリガー実装
- [ ] docs/images/ への自動保存

---

### **Phase 3: Antigravityの自動レビュー（Month 2）**

```
現在: 開発者がAntigravityに状況説明
    ↓
Month 2: Slack Bot作成
    ↓
結果: ドキュメント更新 → Slackに通知 → レビュー
```

**実装タスク**:
- [ ] Slack Workspace作成
- [ ] Incoming Webhook設定
- [ ] Gitea Webhook → Slack連携

---

### **Phase 4: 完全自動化（Month 3-6）**

```
現在: 開発者が最終承認
    ↓
Month 3-6: MCP実装、AIエージェント化
    ↓
結果: AIが自律的に議論・決定（開発者は拒否権のみ）
```

---

## 🔧 具体的な実装例

### **例1: Claudeが決定 → Geminiが図表生成**

```bash
# Claude側（docs/ に書き込み）
cat > docs/architecture/NEW_DECISION.md <<'EOF'
# 新しいアーキテクチャ決定

## 概要
PostgreSQLをVM内に移動することを検討。

## 理由
...
EOF

git add docs/architecture/NEW_DECISION.md
git commit -m "feat: Consider moving PostgreSQL to VM"
git push

# → Gitea Webhook発火

# Gemini側（Webhookを受信）
# Cloud Functions（Node.js）で実装
export default async function handler(req, res) {
  const { file, content } = req.body;

  // 図表生成が必要か判定
  if (content.includes('アーキテクチャ') || content.includes('構成')) {
    // Gemini APIで図表生成
    const imageUrl = await generateDiagram(content);

    // Gitにコミット（画像）
    await commitToGit('docs/images/new_diagram.png', imageUrl);

    // Slack通知
    await notifySlack('新しい図表を生成しました');
  }

  res.status(200).send('OK');
}
```

---

### **例2: Antigravityのレビュー → Claudeが修正**

```bash
# Antigravity側（Slackでコメント）
# Slack Botが docs/reviews/ に保存

# Slackメッセージ:
# "@claude-bot このアーキテクチャはメモリ不足のリスクがある。
#  VMを6GBに増やすべき。"

# → Slack Bot が自動処理
cat > docs/reviews/2026-01-19_antigravity.md <<'EOF'
# レビュー by Antigravity

**日付**: 2026-01-19
**対象**: NEW_DECISION.md

## コメント
このアーキテクチャはメモリ不足のリスクがある。
VMを6GBに増やすべき。
EOF

git add docs/reviews/
git commit -m "review: Antigravity feedback on NEW_DECISION"
git push

# → Webhook発火

# Claude側（MCP経由で自動読み込み）
# docs/reviews/ を監視
# 新しいレビューがあれば、元のドキュメントを修正
```

---

## 📊 効果測定

### **Before（現状）**

| 指標 | 値 |
|------|-----|
| AI間の情報共有時間 | 5-10分/回 |
| 1日のコピペ回数 | 10-20回 |
| 開発者の時間消費 | 50-100分/日 |
| 情報の鮮度 | 数時間遅延 |

### **After（理想）**

| 指標 | 目標値 |
|------|--------|
| AI間の情報共有時間 | **<1分/回** |
| 1日のコピペ回数 | **0回** |
| 開発者の時間消費 | **<10分/日** |
| 情報の鮮度 | **リアルタイム** |

**ROI計算**:
```
節約時間: 50-100分/日 → 40-90分/日節約
月間: 800-1800分（13-30時間）
年間: 9600-21600分（160-360時間）

= 年間で約200-360時間を開発に回せる
```

---

## 🛡️ セキュリティ・プライバシー考慮

### **データアクセス制御**

```yaml
# docs/architecture/.access_control.yml

files:
  - pattern: "CRITICAL_*.md"
    read: [claude, antigravity]
    write: [claude]

  - pattern: "AI_HANDOFF_*.md"
    read: [claude, gemini, antigravity]
    write: [claude]

  - pattern: "reviews/*.md"
    read: [claude, gemini, antigravity]
    write: [antigravity]

  - pattern: "images/*.png"
    read: [all]
    write: [gemini]
```

### **機密情報の除外**

```bash
# .gitignore に追加
docs/architecture/SECRETS.md
docs/architecture/*_PRIVATE.md
*.env
credentials.json
```

---

## 🎓 学習コスト

### **各AIが習得すべきスキル**

| AI | 必要スキル | 学習時間 | 優先度 |
|----|-----------|---------|--------|
| **Claude** | Git操作、MCP開発 | 2-4時間 | 🔴 高 |
| **Gemini** | Webhook受信、画像生成API | 1-2時間 | 🟡 中 |
| **Antigravity** | Slack操作、Markdown記法 | 30分-1時間 | 🟢 低 |

---

## 🚀 今すぐできる最小限の実装

### **ステップ1: 共有Notionページ作成（5分）**

```
1. Notionで新規ページ作成
   タイトル: "Posimai AI Collaboration Hub"

2. セクション作成:
   - 📋 Current Status
   - 🏗️ Architecture Decisions
   - 🎨 Generated Diagrams
   - 💬 Reviews & Feedback

3. 各AIに共有
   - Claudeに: ページURL + 編集権限
   - Geminiに: ページURL + コメント権限
   - Antigravityに: ページURL + 編集権限
```

---

### **ステップ2: Slack Workspace作成（10分）**

```
1. Slack Workspace作成
   Name: "Posimai Development"

2. チャンネル作成:
   #architecture - アーキテクチャ議論
   #deployments - デプロイ通知
   #reviews - レビュー依頼

3. Incoming Webhook設定
   https://api.slack.com/messaging/webhooks

4. Gitea Webhook と連携
   Gitea → Slack #deployments に通知
```

---

### **ステップ3: 開発者の役割を「承認者」に限定（即日）**

```
新しいフロー:

1. Claudeがアーキテクチャ決定
   → Notionに書き込み
   → Slackに通知

2. Geminiが図表生成
   → Notionに画像添付
   → Slackに通知

3. Antigravityがレビュー
   → Notionにコメント
   → Slackに通知

4. 開発者が最終承認
   → Slackで 👍 リアクション
   → または「修正が必要」とコメント

開発者の作業: コピペ不要、承認のみ
```

---

## 📝 チェックリスト

### **Week 1-2（基礎構築）**

- [ ] Notion Workspace作成
- [ ] Slack Workspace作成
- [ ] Gitea Webhook → Slack連携
- [ ] 各AIにアクセス権付与
- [ ] テスト運用開始

### **Week 3-4（自動化）**

- [ ] Gemini Webhook実装
- [ ] 自動図表生成テスト
- [ ] Claude MCP統合
- [ ] レビューフロー確立

### **Month 2-3（最適化）**

- [ ] Notion API統合
- [ ] リアルタイム同期実装
- [ ] エラーハンドリング強化
- [ ] パフォーマンス測定

---

## 🎁 ボーナス: 開発者向けダッシュボード

```html
<!-- docs/dashboard.html -->
<!DOCTYPE html>
<html>
<head>
  <title>Posimai AI Collaboration Dashboard</title>
</head>
<body>
  <h1>🤖 AI Activity Monitor</h1>

  <div class="stats">
    <div>Claude Commits: <span id="claude-commits">0</span></div>
    <div>Gemini Images: <span id="gemini-images">0</span></div>
    <div>Antigravity Reviews: <span id="antigravity-reviews">0</span></div>
  </div>

  <div class="timeline">
    <!-- リアルタイムでAIの活動を表示 -->
  </div>

  <script>
    // Gitea API経由でコミット履歴を取得
    // Slackの新着メッセージを取得
    // リアルタイム更新
  </script>
</body>
</html>
```

---

**最終更新**: 2026-01-19
**次回レビュー**: Week 2終了時
**目標**: Phase 2.0-B完了までに基礎実装完了