E.3 AIエージェント連携Tips — GeminiとClaude Codeの連携による改善効果

Gemini（アーキテクト/レビュアー）と Claude Code（コーダー）が連携することで、以下の改善効果が得られます。

1. 「仕様の穴」による手戻り・バグの撲滅

Claude Code は仕様書を忠実にコード化しますが、仕様に論理的な穴（例：計算元データがない等）があるとバグになります。Geminiが事前に仕様の論理的整合性をレビュー・担保することで、Claude Code は迷いなく正確なコードを一発で出力できるようになります。

2. 実務・ビジネス要件に強いコードの生成

Claude Code はコードレベルの最適化は得意ですが、実務上のエッジケース（例：過去の仕訳修正時の運用ルール等）までは気が回らないことがあります。GeminiがFP&Aや会計の実務視点から運用ルールを補完することで、実用性の高い堅牢なシステムを構築できます。

3. ユーザー視点（UI/UX）の向上

Geminiが「視線が分断される」「直感に反する」といったUI/UXのフィードバックを与えることで、Claude Code はより洗練されたUI/UXを実装するための選択肢を持てるようになります。

4. プロンプト（実装指示）の最適化

Geminiが仕様書を「Claude Code が読みやすく、実装しやすい形（具体的なコード例や明確な条件分岐）」に整理することで、Claude Code への指示の質が向上し、期待通りのコードが生成される確率（First Time Right）が飛躍的に高まります。

5. Claude Code のトークン消費を抑える運用Tips

Claude Code はセッション内の全入出力がトークンとして累積する。以下の対策でプラン消費を抑制できる。

git diff の2段階戦略

PR作成時にブランチの差分を確認する際、全ファイルの全文diffを一括取得するとトークンを大量消費する。特に新規ファイルは全行が + 付きの差分になるため影響が大きい。

# Step 1: --stat で概要だけ確認（数行で済む）
git diff main...ブランチ名 --stat

# Step 2: 精査が必要なファイルだけ個別に確認
git diff main...ブランチ名 -- path/to/specific_file.md

実測データ（2026-04-16）

• タスク: git pull + 仕様書PR作成・マージ × 4 + テンプレート修正PR × 3
• 結果: セッション使用量 85%
• 主因: git pull のRPA分割diff（2,000行超）+ _config.json のsystem-reminder全文挿入

7. UX 方針: スライダー禁止・離散単位ドロップダウン優先（2026-04-25 確定）

本プロジェクトのシミュレーション系 UI（MAS-057 Solo-CEO Cockpit / MAS-058 必要年商シミュレーター / MAS-059 成長計画ワークスペース 等）では、連続値スライダーを使わず、離散単位のドロップダウン or ±ボタンを優先する方針で確定。

背景・理由

1. パフォーマンス懸念: 連続値スライダーはドラッグ中のピクセル単位で再描画 + 再計算が走り、GAS 環境下では google.script.run のラウンドトリップが詰まりやすい
2. GAS クォータ: スライダー連動でクライアント計算するとしても、マスタ再取得や永続化トリガーが頻発するとクォータ消費が早い
3. 一人社長の意思決定では離散単位の方が判断しやすい: 年収 600 万と 601 万の違いを検討しても意味がなく、50 万 / 100 万刻みで選ぶ方が認知負荷が低い
4. 税務・社保の等級境界との整合: 標準報酬月額等級は離散（50 万 → 等級 30・53 万 → 等級 31）のため、連続スライダーより離散選択の方が「どの等級を狙うか」の意思決定と合致

推奨ドロップダウン粒度（仕様起草時の参考値）

実装ガイド

• <select> 要素 or カスタム dropdown コンポーネントを基本とする
• ±ボタン（increment/decrement）を併用可。キーボード矢印キーでも移動可
• 連続スライダーが必要なケースは UX 合意後に例外として明記（例: MAS-057 Phase 3 で「サンキーダイアグラムの流量感」をアニメーション表示する演出用途はあり）
• Chart.js / D3.js のサンキーダイアグラム自体は維持（スライダーと別概念・離散値の結果を流量で可視化する用途は OK）

影響を受ける既存仕様書（次セッションで一括書換予定）

以下の PR で「スライダー」を「ドロップダウン」に一括書換:

• docs/brd_solo_ceo_financial_navigator.md §6 UX Strategy
• docs/dev/dev_mas-057_solo_ceo_cockpit.md（アンブレラ名称 + Phase 3）
• docs/dev/dev_mas-058_required_revenue_solver.md（MAS-057 Phase 3 統合部分）
• docs/_internal/TODO_future.md MAS-057 / MAS-058 / MAS-059 エントリの「スライダー」言及

本 §7 は仕様書起草時の SSoTとして参照する。スライダー記述を新規に書く場合は本方針に反していないか確認する。

6. Stream idle timeout への対処（長文仕様書・大規模編集）

Claude Code CLI 実行中に以下のエラーで生成が途中停止することがある:

API Error: Stream idle timeout - partial response received

原因

モデル側でトークン送出が一定時間（既定 ~60 秒）途切れるとクライアントが接続を切る。以下の状況で発生しやすい:

• 長文ファイルを 1 回の Write で出力（仕様書 400-600 行など）
• 大きな Edit 操作を連発する前後の内部推論中
• 長い system-reminder を参照しながらの生成（CLAUDE.md 全文 + 大テーブル等）
• モデル側のステール（低確率・リトライで回復）

対処: 長文生成は分割する

対処: CLI 側のタイムアウト延長

ANTHROPIC_API_TIMEOUT_MS 等の環境変数で延長可能（Claude Code バージョン依存）。claude --help または .claude/settings.json で確認。ただし根本解決にはならないため、分割が第一選択。

事例（2026-04-25）

• タスク: docs/dev/dev_mas-058_*.md 新規仕様書（想定 400-600 行）を 1 回の Write で出力
• 結果: Stream idle timeout 発生、partial response で中断
• 復旧手順:
  1. Step 1: 骨組み（全セクション見出し + 概要テーブルのみ）を Write
  2. Step 2-4: 修正方針 / エッジケース / 実装プロンプト を個別の Edit で追記
• 教訓: 新規仕様書は骨組み先出し → 章単位で Editをルール化する

8. LangGraph / Agentic AI 採用前のチェックリスト（2026-04-25 確立・MAS-333 知見反映）

MAS-059 等の Agentic AI を本格採用する前に、以下の落とし穴を回避するためのチェックリスト。MAS-333（Claude Research × Gemini Deep Research 突合）から抽出。

致命的アンチパターン 5 つ（いずれも一人法人を破綻させうる）

1. Recursion 暴走による課金事故 ⭐ 最優先

   • GitHub Issue #6731/#1524/#5883 で複数事例。Claude Sonnet 4 で recursion limit 25 まで走ると 1 リクエスト $0.10-0.30。bot 経由で1 晩で数百ドル請求の現実例あり
   • 対策: ① Anthropic API spend cap・② GCP Budget Alert + 自動 disable・③ recursion_limit=10 デフォルト・④ tool_choice=required 回避・⑤ Prompt caching 有効化（Sonnet 4 で 1 時間 cache）

2. Firestore checkpointer の自前実装（bizlp E 案で罠化していた箇所）

   • langgraph-checkpoint-firestore 公式パッケージは 2026/04 時点で存在しない
   • 自前実装すると GitHub Issue #6533/#3380 で報告済の並列ブランチ race condition を再発明するリスク大
   • 対策: 公式 langgraph-checkpoint-postgres（Cloud SQL Postgres db-f1-micro 月 $7-10）を採用。Firestore はアプリ用ユーザーデータのみに限定

3. LLM への直接計算委譲

   • Financial Planning Gone Wrong 事例（ローン月額を 1,350 → 850 と誤算した）
   • 対策: 税率・社会保険料・採用 TCO 等は**Python 純粋関数（Function Calling Tool）**で実装。LLM に数値を復唱させない

4. conditional_edge を LLM 判断で全任せ

   • octomind「Why we no longer use LangChain」、Aerospike「LangGraph in Production」で警鐘
   • 対策: ルーティングは rule-based decision function 優先。LangSmith Studio で trajectory 確認・Annotation Queue で評価データ蓄積

5. HITL バイパスでの責任発生

   • Air Canada v. Moffatt（2024 BCCRT 149）でチャットボット出力に運営者責任認定
   • 対策: 金額閾値 + Autonomy Slider（Conservative/Balanced/Autonomous）。$5,000 超 / 役員報酬 ±20% 以上 / 資金調達は強制 HITL

採用すべき設計パターン

1. Stateful Graph Orchestration（LangGraph + Cloud SQL Postgres + LangSmith）
2. 計算は決定論的エンジン、LLM は説明・推奨理由提示のみ
3. 観測性は OpenTelemetry 経由で送信先抽象化（LangSmith primary + Langfuse self-host で保険）
4. HITL = 金額閾値条件分岐 + Autonomy Slider
5. 並列ブランチは公式 Postgres/Redis Checkpointer + Pure Python Graph 定義

規制・コンプライアンス上の留意点

• EU AI Act: 2026/8/2 完全施行。SMB 一般財務計画 AI の高リスク該当性は Annex III ガイドライン（2026/2 予定）待ち・予防的設計
• 税理士法 52 条 / 金商法 28-3: 「個人の判断材料」フレーミング徹底・税理士・財務アドバイザーの代替を明示否定する Disclaimer 必須
• 個情法 32 条: 個人金融資産はローカル/サーバーサイド計算で完結・LLM 送信しない
• 監査ログ: 最低 6 ヶ月（EU AI Act）・J-SOX は 7 年。LangSmith + BigQuery で構造化保存
• HSB AI Liability Insurance 等の AI 専用保険を商用化時に検討

コスト試算（月間 1,000 セッション規模）

E.3.4 Vertex AI 利用可能モデル ID メモ

2026-05-01 時点・dev (bizlp-gas-accounting-dev) 環境での実 curl rawPredict / generateContent テスト結果 (※ 2026-04-30 → 2026-05-01 に Gemini 3 Pro Preview 検証を追記):

呼出コード: Utils.callGeminiForReasoningOnVertex_(prompt, options) (mas/000_infra/004_utils.js)。F-67 Phase D の generateF67Suggest は AI モデル selector で GEMINI_PRO / GEMINI_FLASH / CLAUDE_SONNET / CUSTOM を切替可能 (PR #448)。

認証経路の区別 (ADC vs API キー)

bizlp で利用する 2 系統の Google 認証は別物。混同しないこと:

重要: GEMINI_API_KEY は .env (.gitignore で除外済) に保管・curl 手動相談での利用に限定。本番 GAS コードからは Vertex AI ADC 経路を使用 (ADR-0008「本番 AI API を Vertex AI に集約」準拠)。

Anthropic Claude quota 申請手順:

1. Console > IAM & Admin > Quotas で anthropic-claude-sonnet-4-5 等を検索
2. online_prediction_input_tokens_per_minute_per_base_model を増加申請 (各リージョン別)
3. 通常 1-3 営業日で承認
4. 承認後に F67_AI_SUGGEST_MODEL = CLAUDE_SONNET で本番利用切替可能
5. 本番 Workspace 利用時は dev とは別途 quota 申請が必要

接続テストコマンド (zsh ペースト時は 1 行に収めること・複数行 \ 継続は壊れやすい):

Anthropic Claude (Vertex AI 経路・ADC)

ACCESS_TOKEN=$(gcloud auth print-access-token)
PROJECT="bizlp-gas-accounting-dev"
REGION="us-east5"
MODEL="claude-sonnet-4-5@20250929"
curl -sS -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/${REGION}/publishers/anthropic/models/${MODEL}:rawPredict" -d '{"anthropic_version":"vertex-2023-10-16","max_tokens":256,"messages":[{"role":"user","content":"ping"}]}'

Google Gemini (Vertex AI 経路・ADC)

ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
PROJECT="bizlp-gas-accounting-dev"
REGION="us-central1"
MODEL="gemini-2.5-pro"
curl -sS -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" "https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT}/locations/${REGION}/publishers/google/models/${MODEL}:generateContent" -d '{"contents":[{"role":"user","parts":[{"text":"ping"}]}],"generationConfig":{"maxOutputTokens":8}}'

Google Gemini 3 Pro Preview (Generative Language API 経路・API キー・curl 手動経路のみ)

注意: 本経路は本番 GAS では非利用 (ADR-0008 不整合)・curl 手動相談 (RQ-XXX 助言相談等) のみ。Vertex AI で 3.x が公開されたら本経路は退役予定。

source .env  # GEMINI_API_KEY を読込 (.gitignore 済)
MODEL="gemini-3-pro-preview"
curl -sS -X POST -H "Content-Type: application/json" "https://generativelanguage.googleapis.com/v1beta/models/${MODEL}:generateContent?key=${GEMINI_API_KEY}" -d '{"contents":[{"role":"user","parts":[{"text":"ping"}]}],"generationConfig":{"maxOutputTokens":8,"thinkingConfig":{"thinkingLevel":"high"}}}'

Deep Think モード: generationConfig.thinkingConfig.thinkingLevel: "high" を指定すると深い推論が走る (応答時間は長くなる・約 28KB 応答取得実績 = RQ-037)。"low" / "medium" も指定可能。

実検証経路 (RQ-037・2026-05-01):

版数 suffix について: Vertex Anthropic publisher のモデルは版数 suffix 形式が必須 (例: claude-sonnet-4-5@20250929)。alias のみだと 404。利用可能版数は Vertex Model Garden Console または gcloud ai models list で確認。

よくあるエラー:

詳細は docs/_internal/research_prompts/RQ-035_*_synthesis.md を参照。MAS-059 仕様書 v1.0 起草時の SSoT として活用すること。

9. フロントエンド UI 生成 — v0.dev + Tailwind + Tremor ワークフロー（MAS-356 確立）

前提条件

• Phase 1 完了 (MAS-356): webapp_client に Tailwind v4 + Tremor v3 が導入済みであること
  • @tailwindcss/vite プラグインが vite.config.ts に追加済み
  • tremor-scope.css で preflight 除外・CSS層（@layer）によるスコープ分離済み
• Tremor コンポーネントを使用する場合: <div className="tremor-root"> でラップ必須（既存 cockpit.css との衝突防止）
• バンドルサイズ注意: Tremor は Recharts を含むため、cockpit HTML が ~800KB 増加する。体感速度が許容範囲なら問題なし（GAS 技術上限は数 MB）

v0.dev コンポーネント生成フロー

1. v0.app でプロンプト入力（下記テンプレート使用）
2. 産物コードをコピー
3. 外部 CDN 参照を除去（import 'https://...' 等を削除）
4. <div className="tremor-root"> ラッパーを追加
5. Props 型定義を既存エンジン戻り値型に合わせる
6. VITE_BUILD_TARGET=cockpit npx vite build でサイズ確認
7. 動作確認（npm run dev:cockpit または GAS dev 環境）

cockpit パネル向け v0.dev プロンプトテンプレート

以下の仕様で React + Tailwind + Tremor のダッシュボードパネルを生成してください。

## コンテキスト
- GAS Web App 内の iframe で動作する SPA（vite-plugin-singlefile でインライン化）
- 外部フォント・外部 CDN の参照禁止（import 文でのみ依存解決）
- 既存: 背景色 #f5f5f5 のメインコンテンツ・ダークナビ (#1e2330)
- すべての Tremor コンポーネントは <div className="tremor-root"> でラップする

## 生成するコンポーネント
[コンポーネント名と要件をここに記述]

## 使用可能なコンポーネント
- Tremor: Card, Metric, Badge, ProgressBar, Callout, List, ListItem, AreaChart
- shadcn/ui: Button, Select, Tabs

## 制約
- Props 経由で全データを受け取る（fetch 禁止・google.script.run は呼ばない）
- className は既存の cockpit-section クラスと共存できる形で
- TypeScript 型定義を Props interface として出力する

Tremor コンポーネント対照表（MAS-356 Phase 2 実績）

注意事項

• color prop の動的生成禁止: Tailwind JIT は動的クラスを認識しないため color={\${status}`}` 等は不可。条件分岐で静的な文字列を渡す
• darkMode: tailwind.config.ts で darkMode: 'class' を設定済み。.dark クラスが付与されない限りダークモードは適用されない
• multiyear_cockpit には適用しない: tremor-scope.css は cockpit.css のみ import。multiyear は未使用のまま