meticulous-improve-test-env

Agent swarm がモックされたネットワーク応答ではなく、稼働中のバックエンドに対してプルリクエストをテストする場合、検証できるのはテスト環境からアクセス可能な範囲に限られます。環境が原因で検証できなかったケース（操作対象のレコードがない、テストユーザーに適切なロールがない、機能フラグがオフになっている、ログインに失敗する、バックエンドでエラーが発生するなど）はブロック中として報告され、Meticulous はカテゴリー、エージェントが確認した証拠、推奨される修正方法とともに、セットアップブロッカーとして記録します。このスキルでは、これらの記録をプロジェクトのテスト環境に対する具体的な変更につなげます。

開始する前に、meticulous-cli-update スキルを実行して、Meticulous CLI とスキルが最新であることを確認してください。ただし、この会話の前の段階ですでに実行済みの場合は、スキップしてください。

セットアップブロッカーが記録されるのは、Agent swarm の実行が稼働中のバックエンドに対して行われた場合のみです。プロジェクトの Agent swarm の実行でモックされたネットワーク応答が使われている場合、ブロッカーはありません。その旨をユーザーに伝え、終了してください。

Step 1 -- 記録されたセットアップブロッカーを読む

# CLI (default: the last 30 days, newest first, 100 per page)
meticulous agent agent-swarm-setup-blockers [--since=<date>] [--category=<category>] [--runId=<swarmRunId>] [--limit=<n>] [--offset=<n>] [--project=<project>]

# MCP
get_agent_swarm_setup_blockers(since="<date>", category="<category>", runId="<swarmRunId>", limit=<n>, offset=<n>)

CLI は、stderr に該当するすべてのブロッカーのカテゴリー別件数を出力し、その後に createdAt、swarmRunId、caseIndex、caseId、commitSha、category、blockedBy、caseTitle、summary、evidence、suggestedFix を含む TSV テーブルを出力します。--json と MCP は、{ since, counts, setupBlockers } として同じデータを返します。応答に結果がさらにあると示されている場合は、結論を出す前に --offset でページを切り替えるか、--category で絞り込んでください。

まず counts を確認します。ブロッカーの多いカテゴリーほど、修正によってブロックを解除できるケースが多くなります。次に、各カテゴリー内の行を根本原因ごとにグループ化します。同じ種類のレコードがない、同じロールがない、同じフラグがオフになっているなど、多くのブロッカーは通常、少数の原因に集約されます。evidence が不十分で対応できないブロッカーについては、エージェントが実行した手順も含め、ケースの詳細を読んでください。

meticulous agent agent-swarm-run-case --swarmRunId=<swarmRunId> --caseIndex=<caseIndex>
# MCP: get_agent_swarm_run_case(swarmRunId="<swarmRunId>", caseIndex=<caseIndex>)

セットアップブロッカーがない場合でも、ユーザーから Agent swarm がブロックされていると報告されたときは、meticulous agent agent-swarm-runs --includeCounts（MCP：get_agent_swarm_runs）で最近の実行を一覧表示し、ブロックされたケースが多数ある実行を meticulous agent agent-swarm-run --swarmRunId=<id> --status=blocked で開いて、該当ケースを読みます。application が原因でブロックされたケースはアプリ自体の動作によるもので、環境が原因ではありません。ここでは environment が原因のケースのみを候補として扱い、Step 2 の静的レビューで問題の可能性がある箇所を探してください。

Step 2 -- テスト環境のセットアップ方法を調べる

何かを提案する前に、テスト環境の各要素がどこで定義されているかを確認してください。コードベースを検索して、次の項目を調べます。

• シードデータとフィクスチャ：シードスクリプト、データを挿入するデータベースのマイグレーション、ファクトリー、フィクスチャファイル、および環境の作成時やリセット時にそれらを実行するコマンドや CI のステップ。
• テストユーザー：Agent swarm がサインインするアカウントの作成方法、そのアカウントに付与されるロール、権限、組織、プラン、および登録が必要な許可リスト。
• 機能フラグ：テスト環境でのフラグの評価方法（フラグサービス、環境変数、設定ファイルなど）と、そこでのデフォルト値。
• 認証：テストログインの仕組み（認証情報、SSO や MFA のバイパス、セッションの有効期間、参照される環境変数やシークレット）。
• バックエンド設定：テストデプロイで使用される環境変数、デプロイマニフェスト（Docker Compose、Helm チャート、Terraform、プラットフォーム設定ファイルなど）、サービス URL。サードパーティサービスのうち、実サービス、サンドボックス、スタブのどれが使われているかも含めて確認してください。

また、存在する場合は、プロジェクトの Agent swarm の手順書 .meticulous/agent-swarm-instructions.md も読んでください。テストアカウントや想定されるデータがすでに記載されている可能性があり、内容が古くなっている場合もあります。

Step 1 の各ブロッカーグループについて、その原因を管理しているファイルまたはシステムを記録します。ブロッカーの原因がコードベースの外部にある場合（フラグのダッシュボード、ID プロバイダー、シークレットマネージャー、ホスト型データベースなど）は、変更をそこで行う必要があることを記してください。

Step 3 -- 各グループの修正方法を考える

カテゴリを手がかりに調査箇所を判断し、ブロッカーの suggestedFix は最終的な回答ではなく出発点として使います。Step 2 で見つけた内容と照らし合わせてください。

カテゴリ	通常の意味	代表的な修正
missingTestData	フローで必要なレコードがテストユーザー用に存在しない	シードデータまたはフィクスチャを拡張し、フローで必要な各状態の代表的なレコードをテストユーザーに用意します（例：空のリストと入力済みのリスト、下書きと公開済みのアイテム）。リセットのたびにシードデータを再投入してください
testUserPermissions	テストユーザーがフローで必要なものを閲覧または実行できない	フローに必要なロールまたは権限をテストユーザーに付与するか、ロールごとにテストユーザーを追加し、それぞれについて Agent swarm の手順に記載します
featureFlag	テスト環境でオフになっているフラグによってフローが制限されている	テスト環境またはテストユーザーに対してフラグを有効にします。開発中のフラグは、テスト環境ではデフォルトで有効にしてください
authentication	エージェントがサインインできなかった、またはセッションの期限切れや拒否が発生した	テスト用の認証情報またはシークレットを修正する、テストユーザーの MFA／CAPTCHA を無効にする、またはテストセッションの有効期間を延長します。人の介入なしでログインできることを確認してください
backendError	バックエンドでエラー、タイムアウト、またはヘルス異常が発生した	createdAt 前後のテストバックエンドのログを確認し、障害のあるサービス、その設定、またはリソース上限を修正します。環境の不具合と、プルリクエストで発生した実際のバグを区別してください
externalDependency	サードパーティサービス（決済、メール、地図など）に接続できなかった、または実サービスに接続した	テスト環境をプロバイダーのサンドボックスに接続するか、テスト環境でそのサービスをスタブ化します
other	上記のカテゴリに当てはまらないセットアップの問題	summary と evidence を読み、ケースごとに判断してください

一時的な手作業での変更のように、時間とともに現状からずれていくものではなく、リセットのたびに実行されるシードスクリプトや設定でのフラグのデフォルト値など、環境を確実に再現できる修正を優先してください。テストを可能にするために本番環境のセキュリティを弱めないでください。ログイン、権限、フラグを緩和する場合は、テスト環境とそのテストユーザーに限定してください。

backendError またはその他のブロッカーが環境ではなくプルリクエスト自体に起因しているように見える場合は、環境の変更を提案せず、その旨を伝えてください。変更内で修正すべきバグです。

Step 4 -- 変更を提案する

ユーザーに短い計画を提示し、それぞれの修正で解消できるブロッカーの件数が多い順に並べます。

1. 修正ごとに、ブロッカーのカテゴリ、対応するブロッカーの件数（ケースタイトルの例を1つまたは2つ含めます）、根本原因、変更内容を示します。
2. コードベースの変更（シードデータ、フィクスチャ、テストユーザーのセットアップ、フラグのデフォルト値、環境設定）：ユーザーが同意した場合に実装し、どの Agent swarm セットアップのブロッカーに対応するかを説明するプルリクエストを作成します。
3. コードベース外の変更（フラグダッシュボード、ID プロバイダー、シークレット、ホスト型テストデータベース）：コードベースからは変更できないため、ユーザーが実行する正確な手順を列挙します。
4. Agent swarm の手順：エージェントが自力では発見できない知識（役割ごとに使用するテストアカウント、シードデータの場所、意図的に利用できないフロー）が不足していた場合は、同じプルリクエストで .meticulous/agent-swarm-instructions.md に追加します。そのファイルにシークレットを記載しないでください。

ユーザーから明示的な許可を得ずに、共有環境または本番環境に影響する変更を行わないでください。

Step 5 -- 検証する

変更がテスト環境にデプロイされたら、次回以降の Agent swarm の実行では、記録されるセットアップのブロッカーが減っているはずです。新しい実行が少なくとも1回完了した後、次の内容を比較します。

# Blockers recorded since the fix was deployed
meticulous agent agent-swarm-setup-blockers --since=<deploy time>

# Or a specific new run
meticulous agent agent-swarm-setup-blockers --runId=<swarmRunId>

修正したカテゴリの件数が減っていることを確認し、そのカテゴリに残っているブロッカーを読みます。一部しか機能しなかった修正や、新たに明らかになったブロッカーがあれば、ここに表示されます。修正前と修正後の件数をユーザーに報告します。