FAQ · よくあるエラーと解決法

各章に散らばっている警告・ヒントボックスを、実習中によく発生する順に一箇所にまとめました。まず症状で検索し、必要であれば「詳細」リンクから元の説明を確認してください。

セットアップ・環境

4章§2の実習準備スクリプトを実行したところ、一部の項目が❌と表示されます。

OSに関わらず、setup-common.tsがチェックリストを再検証します。Windowsではスクリプトを管理者権限で実行したかを、macOS/Linuxでは--wezterm/--dockerのようなオプションフラグを付け忘れていないかをまず確認してください。インストールログはWindowsの場合%USERPROFILE%\workshop-setup-logs\に残ります。

詳細: 4章§2-A 準備

Antigravityコマンドラインインターフェース(CLI)をnpmでグローバルインストールしようとしていますが、うまくいきません。

2026年6月18日をもってGemini CLIサービスが終了し、Antigravity CLI(agy)に置き換わりました。agyは別途ランタイムのインストールが不要な単一のコンパイル済みバイナリで、解凍してPATHに追加するだけで使用できます。npmインストールの案内は古い情報です。

詳細: 共通リファレンス§ツール比較

サブエージェント実行

writerサブエージェントにファイルを書かせたところ、reviewerが「ファイルが存在しない」と言います。

writerとreviewerを1つのメッセージで同時に(並列で)呼び出した可能性が高いです。writerがファイルを作成する前にreviewerがレビューを試みたため失敗しました。依存関係のあるタスクは「2つのステップを順番に進めて」のように、明示的に順次実行を指示する必要があります。

詳細: 4章§2-A D-1

Claude Desktop Appでファイルを保存した後、監査スクリプトが自動的に実行されません。

これは正常な動作です。PostToolUse/TeammateIdle/TaskCompletedのようなフックはClaude Desktop Appでは発火せず、Claude Code(CLI)セッションでのみ自動実行されます。Desktop Appを使用するチームは、フックが行うはずだった処理をセッション終了後に手動で実行する必要があります。これを知らずにいると、「監査が実行されたと思っていたが実際は実行されていなかった」という事故につながる可能性があります。

詳細: 共通リファレンス§1、3章§監査ログと観測性

reviewerにレビューだけを依頼したのに、ファイルを修正してしまいました。

toolsフィールドにWriteが含まれていないか確認してください。reviewerのような読み取り専用の役割には、最初からtools: Read, Grepのように必要最小限の権限だけを付与し、プロンプトの解釈が曖昧であっても修正そのものが不可能になるようにすべきです。

詳細: 3章§最小権限の原則

エージェントが同じ作業を繰り返し、いつまでも終わりません。

評価者・最適化者(Evaluator-Optimizer)ループにおいて、評価者が常に「不十分」と判断し、最適化者が再試行を続けるスピン(spin)状態です。解決法として、最大反復回数をあらかじめ決めておき、指定回数以内に基準を満たさなければ自動終了させます。2章§オーケストレーションパターンで説明されているようにパターン単位で解決しようとせず、9章の実行計画(Execution Plan)としてワークフロー全体を構造化すると予防しやすくなります。

詳細: 2章§オーケストレーションパターン、9章・ワークフローデザインパターン

サブエージェントがツールを呼び出そうとして失敗し、そのまま止まってしまいます。

最も多い原因は次の2つです。1つ目はネットワークタイムアウトで、API呼び出しやMCPサーバーへの接続が一時的に切断された場合です。Claude Codeの場合は/costコマンドでセッションの状態を確認し、Antigravityの場合はAgent Managerでエージェントの状態を確認してから再試行してください。2つ目はMCPサーバー未接続で、ローカルのMCPサーバーが起動しているかをclaude mcp list(Claude Code)、または各プラットフォームのサーバー状態確認コマンドで確認してください。一時的なエラーについては、コスト・パフォーマンスのタイムアウト解決法を参照してください。

詳細: FAQ・コスト・パフォーマンス、3章§監査ログと観測性

エージェントが実行した破壊的操作やファイル修正の履歴を、エンタープライズ環境で監視・監査(Audit)するには?

エージェントのターミナルコマンド実行およびツール使用履歴は、システムの監査ログ(Audit Log)としてリアルタイムに収集される必要があります。そのために、Sandbox環境内で監査デーモンやシェルフッキング(Shell Hooking)技術を使用し、実行記録をリモートログサーバーに送信します。また、重要な破壊的操作(例: DBの削除、Secret Keyの破棄)については、Human Approval Gateを強制し、システム管理者または担当者の最終承認なしには実行できないよう、隔離された構造を構築する必要があります。

詳細: 3章§監査ログと観測性

並列・チーム協業

Antigravity Agent Managerで2つのエージェントがそれぞれ別のファイルを修正しているのに、結果が混ざってしまいます。

2つのエージェントを同じWorkspace(同じフォルダ)に割り当てた可能性が高いです。同じコードベースを共有すると、一方のエージェントがもう一方のエージェントの作業コンテキストを自分のものと誤認する「認知的重複(cognitive overlap)」が発生することがあります。Workspaceまたはgit worktree単位で必ず分離してください。

詳細: 共通リファレンス§2、3章§隔離

Claude Desktop AppでAgent Teamsを有効にしましたが、tmuxオプションが表示されません。

これは正常な動作です。Desktop AppはteammateMode: in-processのみをサポートしており、tmux分割ウィンドウモードはClaude Code(CLI)でのみ追加でサポートされています。

詳細: 共通リファレンス§1

エージェントが作業を進める途中で、人間の最終承認や中間入力を受け取る必要がある場合、どのように処理しますか?

Human-in-the-Loop (HITL)パターンを使用します。オーケストレーターが作業を進める中で、重要な分岐点や権限が必要な地点(例: デプロイ、コードマージ)で処理を一時停止し、状態を保持したままユーザーにフィードバックを要求します。この際、エージェントは質問の文脈と必要な情報を構造化して伝える必要があり、承認が却下されたり修正要求があった場合は、エージェントチームが以前の作業状態にロールバックしてフィードバック内容を反映した上で、再度処理を試みるようフローを制御します。

詳細: 9章・ワークフローデザインパターン

workspace/variant

new-project.tsを実行したところ、スキャフォールディングが拒否されたり、パスがおかしくなったりします。

ワークスペースのルートではなく、別のプロジェクトフォルダの中で実行した可能性が高いです。ai-workspace-standardsは必ずワークスペース自体のルートにクローンして使用する必要があり(WindowsではC:\git、macOS/Linuxでは~/git)、別のプロジェクトフォルダの中にサブモジュールのように配置するとパス計算がずれてしまいます。

詳細: 6章§1

bun run agent:verifyの実行結果にある「Documented agents」の数値が予想と異なります。

AGENTS.mdの表と実際のagents/*.mdファイル一覧がずれています。ワークスペース専用のエージェント(auditor、lifecycle-managerなど)が表に残っていないか、新しく作成したエージェントが表から漏れていないかを再確認してください。

詳細: 6章 D-1

昇格パイプライン(l3-to-variant-pipeline.ts)を実行してもよいか確信が持てません。

このコマンドは実際のgit履歴に痕跡を残す、元に戻すのが難しい操作です。講義・ワークショップ環境であれば、参加者全員が実行するのではなく、講師が一度デモンストレーションするだけで十分です。講義進行ガイドに案内があります。

詳細: 12章実習

ai-workspace-standardsを実際の本番環境(Docker/Kubernetes)で使用するには?

現在、ai-workspace-standardsはローカルのAIコーディングツール(Claude Code/App、Antigravityなど)と直接連携する方式でのみ動作します。DockerまたはKubernetes環境でOpen WebUIのようなフロントエンドサービスと連携し、ユーザー単位でエージェントチームをサポートする形態は高度化の方向性として議論中であり、まだ実装されていません。詳細: 8章§5 高度化ロードマップ

複数のプロジェクトのmemory/YYYY-MM-DD.mdを一箇所にまとめて見ることはできますか?

現在は各プロジェクトごとに独立したmemory/YYYY-MM-DD.mdを維持する構造であり、ワークスペースレベルでメモリを集約・整理する機能は高度化の方向性として計画中です。プロジェクトが増えるほど個別のメモリファイルから全体のトレンドを把握しにくくなる点を改善する予定です。詳細: 8章§5 高度化ロードマップ

variantテンプレートが更新されると、既存のプロジェクトにも自動的に反映されますか?

いいえ。ai-workspace-standardsはフォークモデル(Fork Model)を採用しています。L1(共通テンプレート)の変更は、すでにスキャフォールディングされたL2 variant(templates/co-*/)やL3プロジェクト(Projects/*/、L2 variantからスキャフォールディングされる)に自動的に伝播しません。これは意図的な差分を保持するための設計ですが、セキュリティパッチやバグ修正を手動で反映しなければならないという運用負担を生みます。同意ベース(consent-based)の選択的受信モデルと非同期配布パイプラインが、高度化の方向性として検討されています。詳細: 8章§5 高度化ロードマップ

新規variant(バリアント)作成時にagent:verifyの検証やvalidate-templatesで失敗します。

最もよくある原因は、エージェント宣言間の**対称性(Symmetry)の不遵守**です。例えば、researcherエージェントのhandoff_toにwriterが指定されている場合、writerエージェントのhandoff_fromにも必ずresearcherが対になって定義されている必要があります。また、variant.jsonファイルのJSON構文エラーや、必須フィールド(エージェント一覧など)が有効な仕様になっているかも確認する必要があります。

詳細: 11章§新規variant作成

自分で設計・構築したエージェントチームが、実運用で常に意図した品質で動作しているかをどう検証しますか?

正常動作を評価するためにエージェントテストベンチ(Test Bench)を構築する必要があります。第一に、代表的な入力要件と期待される出力(Gold Dataset)を定義します。第二に、プロンプトやエージェントのルールを修正するたびに、データセットを投入して回帰テスト(Regression Test)を自動で実行します。第三に、定量評価が難しい自然言語出力については、高性能モデルを審判(LLM-as-a-Judge)として立て、事前に合意した定量スコアで評価するように実装します。

詳細: 13章§キャップストーン実習

コスト・パフォーマンス

マルチエージェントチームを稼働させると、トークンコストはどのくらいかかりますか?

コストはエージェント数×各エージェントのモデルティア×実行頻度によって決まります。5章で説明されているモデルティアリング(tier: high/medium/low)は、コスト管理の中核となる仕組みです。例えば、co-consultバリアントの10名のエージェントをすべてhighで動かすと1セッションで数万トークンを消費しますが、実際の実装役割をmedium/lowに下げることで、コストを40~60%削減できます。Claude Codeの/costコマンドで、現在のセッションの累積トークンをリアルタイムに確認できます。

詳細: 5章§templatesとvariant 11種

エージェントの応答が急に遅くなったり、タイムアウトしたりします。

コンテキストウィンドウが一杯になると、モデルの処理速度が急激に低下します。Claude Codeでは/compactコマンドで会話の長さを圧縮できます。また、複数のエージェントを並列に投入した際にAPIリクエストがキューに溜まって遅延する現象もよく見られます。この場合は順次実行に切り替えるか、WIP上限を下げて同時実行数を減らしてください。

詳細: 共通リファレンス§1

複数のエージェントループや長いワークフローを実行すると、APIトークンのコストがかかりすぎます。最適化方法は?

第一に、エージェントの役割ごとに**モデルティア(Model Tier)**を分けて指定します。単純なファイル書き込みやテスト実行にはmedium/lowモデルを、全体のフロー制御や総合設計にはhighモデルを配置することで、コストを40%以上削減できます。第二に、プロンプトキャッシング(Prompt Caching)が機能するよう、会話の文脈が一定である間はシステムプロンプトを変更せず、連続したセッションを維持します。第三に、オーケストレーターとスペシャリストの対話が無限にスピンしないよう、Max Turnsのようなハード上限値を明確に設定します。

詳細: 5章§templatesとvariant 11種

プラットフォーム別の問題

Windowsでnew-project.tsを実行すると、パス区切り文字のエラーが発生します。

ai-workspace-standardsのスクリプトはNode.js/Bunランタイム上でpathモジュールを使用してプラットフォームごとのパスを処理するため、基本的にWindowsとmacOS/Linuxの両方に対応しています。ただし、Claude Codeセッション内でgit cloneコマンドを直接実行する際に、Git BashではなくPowerShellのパス(C:\Users\...)が混ざると問題が発生することがあります。Claude Codeでは常に/形式のパスまたはGit Bash形式を使用し、ワークスペースのルートはC:\gitのように短く階層の浅い場所にクローンすることを推奨します。

詳細: 6章§1