allure-agent-mode

Allure エージェントモード

テストを変更する機能開発やバグ修正、既存テストのレビュー、カバレッジの監査、失敗したテストスイートのトリアージ、根拠が不十分な箇所の調査、または不安定なテストや環境依存の失敗のデバッグには、このスキルを使用します。

エージェントモードを使う理由

テストの実行は、単に成功か失敗かを拾うためのものではなく、調査に役立つ手段です。allure agent を使ってテストを実行すると、どのような実行でも、実際に起きたことを確認できる記録にできます。ステップ、HTTP のやり取り、SQL、ブラウザーセッション、添付ファイルに加え、アサーションなしで実行されたテストや、実行された証拠がない API 呼び出しなど、テスト自体に関する自動検出結果も確認できます。コンソールからはステータスがわかりますが、エージェントの出力からは状況の把握と評価が得られ、人が実際にレビューできるレポートも確認できます。作業の質を高められるため、活用してください。

• 目的を持って実行します。 allure agent --goal "<what this run should confirm>" -- <test cmd>。最近の allure agent は実行の概要を標準出力に表示します。件数、重大度付きの検出結果、期待結果、レポートへのリンク、出力内の参照先が含まれるため、ファイルを開かなくても要点を把握できます（パススルーのノイズを抑えるには --silent オプションを使用できます。効果は allure agent --help で確認してください）。概要を読み、さらに詳しく調べるにはエージェントの出力を開きます。出力ディレクトリの AGENTS.md ガイド、index.md、検出結果、テストごとの証拠を確認してください。レポートには証拠と並んで目標も記載されるため、自分自身や上流のエージェント、または人が、実行が本来証明すべきことを検証できます。
• 期待値を設定して、証拠を確認できるようにします。 API 呼び出し、添付ファイル、ステップなど、動作の証明が必要な場合は、対応する --expect-* オプションを追加します。期待した証拠が見つからない場合は、成功ではなく検出結果になります。つまり、その動作が実行されたと確信できないということです。
• 失敗を効率よくトリアージします。 出力には、適切なコンテキストとともに正確な失敗箇所が記載されるため、その場で修正できます。不安定さを確認するには、失敗したテストだけをエージェントモードで再実行します。allure agent --rerun-latest（または allure agent latest で前回の出力を取得して --rerun-from <prior-output>）に、対応する --rerun-preset を指定すれば、テスト名やこのフレームワークのフィルター構文を覚えておく必要はありません。正確なフラグは allure agent --help で確認してください。手当たり次第に再実行したり、ログを抜き出したりしないでください。
• ローカルで再現できなくても、CI からデバッグします。 ダウンロードした allure-results に対して allure agent inspect を実行すると、完全なコンテキストを含む同じレビュー画面が得られます。ローカルで再現できない失敗（Mac では再現せず、Windows だけで発生する失敗など）を修正するのに十分な情報が得られることもよくあります。
• テストをデバッグの手段として使います。 テストはすでに環境を準備し、動作を実行して証拠を取得します。そのため、アドホックな bash を使ったり、ブラウザー MCP を手動で操作したりする代わりに、エージェントモードで該当するテストを実行してください。
• 実際の機能を把握します。 allure agent capabilities を実行し、推測に頼らず、ローカルの CLI が実際にサポートしている機能を確認してください。

実行の概要はすでにダイジェストとして標準出力に表示されています。まずそれを読み、その後で完全な出力を開いてください。tail／grep／head で実行結果を絞り込んだり、>/dev/null にリダイレクトしたり、表示された件数だけで確認を終えたりすると、残りの情報が失われます。検出結果や証拠、場合によってはテストバイナリ全体も確認できなくなります。エージェントの出力にこそ、重要な情報があります。

最初に読むもの

プロジェクトに docs/allure-agent-mode.md がある場合は、テストを書いたりレビューしたりする前に読んでください。

ない場合は、このスキルのガイダンスに従い、後で $allure-configure-agent-workflow の使用を提案してください。

テストの追加、変更、削除、スキップ、抑制、レビューを行う前に、references/test-design.md を読んでください。

Allure のステップ、添付ファイル、パラメーター、ラベル、説明、または証拠が不十分という検出結果を追加、レビュー、修正する前に、references/allure-evidence.md を読んでください。

Allure エージェントの期待値を作成または評価する前に、references/expectations.md を読んでください。プロジェクトガイドまたは allure agent --help で、ローカルの期待値設定の仕組みを確認してください。

ワークフロー

1. 機能、課題、またはレビューの目的を把握し、意図するテスト範囲を決めます。
2. 今回の実行で期待値による制御が実際のリスクを軽減するか判断します。軽減する場合は、ローカルの Allure エージェントでサポートされている、必要最小限の新しい期待値を作成します。
3. テスト設計ルールに従ってテストを作成または更新します。レビューのみのタスクの場合は、現在のテストを変更しません。
4. 自分でテストを実行する場合は、生のコンソール出力を参照する前に、意図した範囲だけを allure agent で実行します。
5. すでに実行時に生の Allure 結果またはダンプアーティファクトが出力されている実行を調査する場合は、生ログや生成された HTML レポートを解析する前に、ローカルで確認済みの allure agent inspect フローを使って、これらのアーティファクトからエージェントが読み取れる出力を作成することを優先します。
6. エージェントのみで反復するループでは、サポートされている場合は --report off を優先します。最終検証やユーザー向けレビューの実行では、--report auto を優先するか、適切な HTML レポートモードを指定し、レポートが生成された場合はそのリンクを共有します。
7. 実行または調査した出力の index.md のパスを表示し、共同作業者が概要をすぐに開けるようにします。
8. ソースコードを調べる前に、index.md、manifest/run.json、manifest/test-events.jsonl、manifest/tests.jsonl、manifest/findings.jsonl、実行で期待値を使用した場合は manifest/expected.json、および関連するテストの Markdown ファイルを確認します。
9. エビデンスが不十分な場合は、実際の手順、添付ファイル、または最小限のメタデータを追加してテストを充実させます。
10. 実行結果が信頼できる判断材料であることを確認します。選択したプロファイルが目的に合っていること、重要なテストが暗黙に除外されていないこと、ゲート対象ではないローカルまたは CI のシグナルが明記されていることを確認します。
11. 同じ意図した範囲で期待値による制御が引き続き妥当な場合は、新しいエージェント出力ディレクトリと新しい期待値を使って再実行します。特定のパスが必要な場合を除き、CLI が提供する一時出力先を使用します。
12. 範囲が一致し、カバレッジに意味があり、エビデンスがレビューに十分で、実行上の制限が明示され、部分的なランタイムのモデル化があればその旨が明記されている場合にのみ、受け入れます。

タスクのバリエーション

これらはタスクごとのワークフローの主なバリエーションであり、別々の手順ではありません。実行後にエージェントの出力をレビューする同じループを適用します。（失敗のデバッグはすでに上記の失敗のトリアージループに含まれています。CI の失敗では、ローカルで再現するのではなく、ダウンロードした結果に対して allure agent inspect を使用します。）

• 小規模なテスト変更。 変更した範囲だけを allure agent で実行します。型の整理やモックのリファクタリングなど、機械的な変更の後でも、スモークテストはエージェントモードで実行します。エージェントの出力をレビューしてから、回帰安全性または正確性について判断します。
• テストの作成。 まず references/test-design.md と references/allure-evidence.md を読みます。テストを作成または変更し、変更した範囲を --goal 付きで実行した後、合否だけでなく検出結果とエビデンスをレビューします。弱い手順、添付ファイル、またはメタデータがあれば充実させてから、新しい出力で再実行します。
• カバレッジのレビュー。 コマンドまたはパッケージの監査を、範囲を限定したグループに分割します。各グループに既知の範囲がある場合に限り、それぞれ異なるエージェント出力と期待値を用意します。各グループを実行し、ソースを調べる前にランタイムアーティファクトをレビューします。すべてのグループが、一致する期待値、レビュー済みの実行範囲、またはパッケージ全体の健全性を明示した文書のいずれかによって検証されるまで、レビューは未完了とします。

カバレッジレビューの簡潔なパターン：

npx allure agent \
  <report mode: --report off for iterative loops, auto/awesome/config for final runs> \
  <minimal local expectation options when justified> \
  -- npm test -- <scope>

実行前に、何を実行し、何を実行しないか、その範囲で十分な理由、期待値オプションが実際のミスを検出できるかを決めます。デフォルトでは CLI が提供する一時出力先を使用し、特定のパスが必要な場合にのみ --output <path> を追加します。

要件

• エージェントモードの実行を完全に示すには、allure agent を備えた Allure CLI [email protected] 以降が必要です。
• エージェントモードの結論を根拠として用いる前に、ローカルのプロジェクトラッパーが allure agent に対応しており、最低バージョンを下回っていないことを確認してください。ラッパーが古いバージョンを報告する場合は、ユーザーに警告し、CLI がアップグレードされるまではエージェントモードの証拠を利用不可または不完全として扱ってください。
• 既存の結果を調査するには、ローカルの allure agent inspect 対応が必要です。この機能は [email protected] 以降で利用できます。プロジェクトラッパー経由で allure agent capabilities --json と allure agent inspect --help を実行して確認してください。
• ローカルまたはダウンロード済みの allure-results ディレクトリには allure agent inspect [<allure-results-dir-or-glob> ...] を使用し、allure run --dump で作成したダンプアーカイブには、--dump <archive-or-glob> を繰り返し指定してください。
• オプションのレポート生成を制御する場合は、--report auto|off|awesome|config を使用してください。デフォルトの auto モードでは、保存された結果数がローカル CLI のしきい値以内の場合、エージェント出力内の awesome/index.html と manifest/human-report.json に HTML レポートが書き込まれることがあります。
• ユーザーがその実行の HTML レポートを必要としない限り、非公開の反復実行では --report off を使用してください。最終検証または引き継ぎの実行では --report auto を優先し、単一ファイルの Awesome レポートを強制するには --report awesome を、プロジェクトで設定されたレポートプラグインを実行するには --report config を使用してください。
• allure agent inspect が利用できない場合、またはアーティファクトの形式に対応できない場合は、agent プラグインのみを有効にする一時的な Allure 設定を生成し、必要に応じて --dump <archive-or-glob> を繰り返し指定して allure generate --config <generated-config> --output <agent-output> <results...> を実行する、高度な代替手段を優先してください。明示的に指定した <agent-output> は、呼び出し側がクリーンアップを管理するものとして扱ってください。
• agent inspect も、生成した agent のみの設定を使う代替手段も利用できない場合は、より信頼性の低い代替手段として、生の Allure 結果、ダンプの内容、またはログを調べてください。allure log <allure-results> は、対応している場合、結果フォルダーに対するローカルコンソールの代替手段ですが、agent 出力ではありません。
• エージェントモードの実行には、一意の出力先が必要です。最近の allure agent では、出力先が指定されない場合、一時出力ディレクトリが作成され、そのパスが表示されます。特定のパスが必要でない限り、このデフォルトを使用してください。[email protected] 以降では、各 allure agent の実行時に、CLI が指定した前回の一時出力先が自動的に削除されるため、デフォルト出力で実行しても蓄積しません。
• エージェントモードでは、現在の実行で生成された結果ファイルのみが検出されるため、実行のたびに allure-results をクリアする必要はありません。どちらの場合も、新しい結果のみが取り込まれます。フレームワークの結果をクリアするか保持するかはプロジェクトの判断であり、エージェントモードの要件ではありません。
• デフォルトの出力先を使用する場合は、agent 出力、または利用可能であれば allure agent latest などの対応ヘルパーから、生成されたディレクトリを取得してください。
• 特定の出力ディレクトリを選ぶ場合は、対応している --output オプションを優先してください。明示的に指定した --output パスは、agent 自身がクリーンアップする必要のある唯一の対象です。自動クリーンアップでは呼び出し側が指定したパスには一切触れないため、完了後にその --output ディレクトリを削除するかアーカイブしてください。出力関連の環境変数は、ローカル CLI のヘルプ、ラッパー、または公式ドキュメントで明示的に説明されている場合にのみ使用してください。現在の CLI で対応している制御方法は --output です。
• agent 出力、フレームワークの Allure 結果、生成されたレポートは、それぞれ別のアーティファクトです。ALLURE_RESULTS_DIR などのフレームワークの結果設定を、agent 出力の制御に使用しないでください。
• プロジェクトガイド、ランナー設定、インストール済みのヘルプ、公式ドキュメント、またはアダプターの README／ソースで、この実行に必要だと確認できない限り、agent コマンドにフレームワークの結果ディレクトリを追加したり、上書きしたりしないでください。実行ごとに結果ディレクトリが必要な場合は、末尾のパス要素を allure-results にし、ローカルの Allure コマンドから検出できるようにしてください。
• もっともらしい名前から Allure の環境変数を決めつけないでください。正確な変数名またはフラグが確認できない場合は、文書化された allure agent オプションを使用するか、設定を不明のままにするか、公式ドキュメントでの確認を求めてください。
• 期待値を使用する実行では、対象範囲に合った新しい期待値を使用する必要があります。
• 並行して実行するエージェントモードの各実行では、呼び出し側が管理する個別の --output ディレクトリを指定してください。各 allure agent の実行で前回の一時出力先が削除され、並行実行に影響するため、デフォルトの一時出力先には依存できません。並行実行間で出力先や期待値の状態を共有しないでください。
• 最終実行で HTML レポートを生成した後は、manifest/human-report.json を読み取り、記録されたレポートのパスを agent 出力ディレクトリを基準に解決してから共有してください。
• ユーザー向けの出力では、アーティファクトは単にレポートと呼び、レポートのパスをインラインコードやコードブロックで囲まないでください。Codex や類似のクライアントでクリックまたはプレビューできるよう、Here is the report: <link> の形式で、絶対パスのローカルレポートファイルへの通常の Markdown リンク（例：[report](/absolute/agent-output/awesome/index.html)）を使用してください。awesome/index.html のような相対的なマニフェスト値を直接リンクしないでください。
• 期待値オプション名を決めつける前に、allure agent --help を確認してください。インラインオプションを優先し、ファイルベースの期待値は、大規模、生成済み、またはポリシーで管理された契約に対する高度なモードとしてのみ使用してください。
• 期待値のフラグを予防的に追加しないでください。期待値の制御が利用できない、または正当化できない場合は、出力から観測された範囲を確認し、範囲の確認が不十分であることを明示してください。
• 実行、ローカルコマンド、または CI ジョブがゲート対象外であるか、デフォルトで重要なテストが除外される場合は、それを証拠として使用する前に明示してください。
• メタデータの拡充は、このワークフローの一部であり、独立したワークフローではありません。

ガードレール

• ソースコードよりも、まずランタイムを確認します。
• テストは振る舞いの契約です。テストを通すためだけにアサーションを弱めたり、テストをスキップしたり、テストカバレッジを削除したりしないでください。
• テストは簡潔で明示的にしてください。数行の重複を省くことだけを主な目的とする条件分岐、ループ、ファクトリー、生成テストよりも、読みやすく安定した直線的なテストを優先してください。
• ランタイムの if 分岐、早期リターン、条件付きテスト登録、カバレッジの不足を隠すヘルパーエイリアスによってテストを強制的にスキップしないでください。明確な理由を添えて、テストランナー標準のスキップ、条件付きスキップ、またはアサンプションの仕組みを使用してください。
• ステップは実際の振る舞いを表すものにし、埋め草にしないでください。
• Allure の証跡を空でなくすためだけに、テスト本体全体を手動の単一ステップで囲まないでください。
• 添付ファイルは現在の実行から取得してください。
• メタデータは最小限にし、レビューやポリシーに役立つラベルのみを追加してください。
• テストごとの意図を示すメタデータは、テスト内にインラインで記述してください。説明、ラベル、リンク、パラメーター、意図を定義するステップ名は、それぞれのテスト箇所で明示してください。
• 呼び出し側で繰り返しラップするよりも、ヘルパーとの境界で計装することを優先してください。
• 再利用可能なヘルパーで処理の仕組みを扱うことはできますが、ラッパー、ルックアップテーブル、テスト名のマッピングにテストの意図を集約してはいけません。
• テストランナーで確認できる失敗が論理テストとして表現されていない場合は、グローバルな stderr を調べ、実行を部分的なランタイムレビューとして扱ってください。
• 無視、除外、握りつぶし、または合否判定に含まれないテストを、検証に合格した根拠として提示しないでください。