antithesis-feature-workload

Antithesis 用の機能ワークロードを構築する

スキルのバージョン： 2026-10-21 4f8d80b

目的と目標

特定の機能を起点に、その機能をテストするワークロードを作成します。 成功とは、次の状態を意味します。

• テスト可能な特性を特定できる程度に、機能を理解している
• 特性が具体的かつ明確である。曖昧な目標ではなく、不変条件、到達可能な動作、障害モードが示されている
• 機能の動作を実際に検証する、自律駆動型のワークロードがある
• 到達性の主張が成立し、ワークロードが機能の重要な状態に到達していることが確認できる
• 機能の不変条件が、適切な SDK 型を使用するアサーションで検証されている
• オプション：ワークロードを Antithesis で実行し、検出事項を検証している

このスキルは、Antithesis ワークフローへの並行するエントリーポイントです。標準的なパイプラインが調査 → セットアップ → ワークロード（広範なカバレッジ）と進むのに対し、このスキルでは機能の分析 → 対象を絞ったワークロード → 反復（機能に焦点）と進みます。

エントリーポイント

このスキルでは、次の 2 つの開始点に対応します。

• 機能が完成している場合：ソースコードを利用できます。完全な分析と完全なワークロードを行い、すべてのアサーションが成功することを想定します。
• 機能を開発中の場合：コードの一部が存在する場合もあれば、仕様やアイデアだけの場合もあります。ワークロードには TDD スタイルのスタブが含まれます。機能の実装が追いつくまではアサーションが失敗し、コードが追加されるとアサーションが成功するようになります。「機能の変更に合わせてワークロードを更新する」ワークフローで、進化に対応します。

どちらのエントリーポイントも同じワークフローをたどります。異なるのは、初回実行時に成功するアサーションの数です。

前提条件

• テスト対象の機能（ソースコード、仕様、説明、またはそれらの組み合わせ）
• SUT のソースコードへのアクセス
• ローカル実行用の Docker Compose v2 とコンテナエンジン（Docker または Podman）
• Antithesis で実行する場合は、snouty CLI 0.8.0 以降がインストールされていること（ローカルのみの作業には不要です）

他のスキルとの関係

• antithesis-research：Feature-workload では、機能に絞った分析を行います。コードベースを調査する手法は同じですが、「システム全体にどのような特性があるか」ではなく、「この機能で何が問題になり得るか」に範囲を絞ります。調査の成果物がすでにスクラッチブックにある場合は、それをコンテキストとして利用しますが、必須ではありません。
• antithesis-workload：Feature-workload では、自律駆動型のワークロードを構築します。Test Composer のコマンドは構築しません。アサーションのパターン、値のメニュー、障害耐性のある設計、到達性の主張はどちらにも適用されます。このスキルには、機能に絞った作業に合わせて調整した独自の参考資料が含まれています。
• antithesis-setup：Feature-workload では、Antithesis のインフラがセットアップ済みかどうかを前提としません。ユーザーが Antithesis での実行を希望し、インフラが必要な場合は、antithesis-setup に委任します。
• antithesis-launch：Antithesis の実行を送信する際に使用します。snouty launch を直接実行しないでください。
• antithesis-triage：Antithesis での各実行後に、焦点を絞って使用します。幅広い特性のポートフォリオを確認するのではなく、「機能の特性は実際に検証されているか。失敗はあるか」を確認します。
• antithesis-debug：トリアージで、より詳細な調査が必要な特性の失敗が見つかった場合に使用します。失敗時点のコンテナ状態を調べ、タイムトラベルしてシーケンスを把握します。

定義

• SUT： テスト対象システム。
• 機能の特性： 機能がどのように動作するべきか、どの不変条件を維持するべきか、またはどのような動作に到達できるべきかについての、具体的かつ検証可能な主張。
• 到達性の主張： ワークロードが実際に機能の動作を検証することを確認する Sometimes アサーション。到達性の主張が成立しない場合、ワークロードが適切な状態に到達していないことを意味します。
• 自律駆動型ワークロード： SUT を操作し、不変条件をチェックし、外部のオーケストレーションなしで実行される単一のプログラム。Test Composer は使用しません。
• デュアルモード： ANTITHESIS_OUTPUT_DIR が設定されている場合（Antithesis）はワークロードが SDK のアサーションを使用し、設定されていない場合（ローカル）は同等のローカルチェックを使用します。

ドキュメントによる裏付け

Antithesis のドキュメントにアクセスするには、antithesis-documentation スキルを使用します。

• SDK リファレンス：https://antithesis.com/docs/reference/sdk.md
• プロパティとアサーション：https://antithesis.com/docs/concepts/properties_assertions/assertions.md
• フォールトインジェクション：https://antithesis.com/docs/product/fault_injection.md
• Docker Compose のセットアップ：https://antithesis.com/docs/getting_started/setup_guide/docker_compose.md

参考ファイル

参考資料	読むタイミング
references/feature-analysis.md	最初に読む — システムの全体像を把握し、機能を理解し、プロパティを見つける
references/self-driving-workload.md	ワークロードの構築時
references/assertions.md	機能のプロパティに対するアサーションと到達性の主張を書くとき
references/interesting-values.md	機能の境界をテストする値を選ぶとき
references/faults.md	この機能でフォールトインジェクションが重要かどうかを評価するとき
references/iteration.md	到達性の主張が発火しない場合や、プロパティがテストされない場合
references/verification.md	発見した問題が実際のものか検証するとき

推奨ワークフロー

機能のワークロードを設計して構築する

1. references/feature-analysis.md を読む
2. システムの全体像を把握します。既存の調査資料が antithesis/scratchbook/ にある場合はそれを読み、ない場合は機能の関連領域に絞って、 アーキテクチャ、データフロー、並行処理モデルの概要を把握します
3. コード、仕様、会話、またはそれらの組み合わせから、機能を理解します。 開発中の機能については、実装済みの部分と予定されている部分を特定します
4. 機能のプロパティ（不変条件、到達可能な動作、障害モード）を見つけます。 開発中の機能については、未実装部分のプロパティを TDD スタイルのスタブにします
5. references/faults.md を読み、この機能で重要となるフォールトの種類を評価します
6. 調査結果を antithesis/feature-workloads/<feature-slug>/analysis.md に記録します
7. references/self-driving-workload.md を読む
8. references/assertions.md を読む
9. references/interesting-values.md を読む
10. 機能のコードパスにおける境界値と設定可能な制限値の種類から、値のメニューを作成します
11. ワークロードを設計して構築します。自走型プログラムに、デュアルモードのアサーション、 フォールト耐性、操作の追跡、機能の主要な動作に対する到達性の主張を組み込みます
12. ローカル実行用の docker-compose を構築するか、既存のセットアップを使用します
13. ローカルで実行します。到達性の主張が発火しない場合や、プロパティがテストされない場合は references/iteration.md を読みます。まず到達性の主張を確認し、その後、 証拠に基づいてワークロード、アサーション、SUT の設定、またはプロパティを調整します
    • 到達性の主張が発火しない → ワークロードを調整するか、機能への理解を見直します
    • プロパティがテストされない → 操作、値、またはアサーションを調整します
    • 機能への理解が誤っているように思われる → 手順 3 に戻ります
14. Antithesis に移行する場合： a. 既存のセットアップを確認します。インフラストラクチャが必要な場合は antithesis-setup を使用します b. 実行には antithesis-launch を使用します c. 分析には antithesis-triage を使用します（「機能のプロパティはテストされているか？失敗はあるか？」という観点で分析します） d. トリアージの結果に応じて、プロパティが失敗した場合は手順 15 に進みます。到達性の主張が発火しない場合は「実行後の反復」に進みます。仕組みが不明な場合は antithesis-debug を使用して詳しく調査します
15. プロパティが失敗した場合は、references/verification.md を読みます。発見した問題を分類します。機能のテスト中に見つかった実際のバグは、どのようなものでも価値があります。
16. 発見した内容を antithesis/feature-workloads/<feature-slug>/analysis.md に記録します

実行後の反復

1. references/iteration.mdを読みます
2. アサーションを変更する必要がある場合は、references/assertions.mdを読みます
3. 到達性の主張を確認します — 機能の動作に到達できていますか？
4. 観察した内容に基づいて反復の方針を選びます：ワークロードの調整、 アサーションの調整、SUT の設定変更、またはプロパティの見直し
5. antithesis/feature-workloads/<feature-slug>/analysis.mdを更新し、 変更内容、観察結果、次に試すことを記録します

機能の変更に合わせたワークロードの更新

機能が進化し、ワークロードもそれに追随させる必要がある場合：

1. 機能を再確認します（コードまたは仕様で何が変わったか）
2. どのプロパティが引き続き有効か、新たに加わったか、不要になったかを確認します
3. ワークロード、アサーション、到達性の主張を更新します — 未実装部分には TDD 形式のスタブを用意し、実装済みでテストに合格した部分のスタブは削除します
4. ローカルで再検証します — 到達性の主張を確認し、結果に不足が見られる場合は、メインワークフローのステップ 13 と同様に反復します

一般的なガイダンス

• 一度に扱う機能は1つです。 複数の機能のワークロードを同時に構築しようとしないでください。各機能には、独自の分析、ワークロード、反復サイクルがあります。
• プロパティを基準にワークロードを構築します。 すべての操作、アサーション、値の選択は、発見した機能プロパティに関連付ける必要があります。プロパティに関連しない作業がある場合は、新しいプロパティを発見するか、その作業を中止してください。
• 到達性の主張を羅針盤にします。 発火していない到達性の主張は、ワークロードが機能の主要な動作を実行できていないことを示します。反復のたびに、まずこれを確認してください — ほかの調整を行う前に、ワークロードが適切な状態に到達していることを確かめます。
• まずはローカルから始めます。 機能のプロパティで Antithesis の機能（障害注入、スケジューリング制御）が明示的に必要とされていない限り、ローカルで開始します。ローカルでの反復はより速く、フィードバックサイクルも短くなります。
• 成功を宣言する前に検証します。 プロパティの失敗は不具合の候補であり、確認済みのバグではありません。反例を読み、シーケンスを把握し、その仕組みを確認してください。ハーネス、アサーション、ワークロードのバグも、すべてプロパティの失敗を引き起こします。
• すべて記録します。 feature-workloads ディレクトリには、「機能がある」状態から「動作するワークロードがある」状態までの経緯が記録されています。後から読む人が、どのようなプロパティが発見され、何がテストされ、何が判明したのかを理解できるようにしてください。
• 障害に耐えられるワークロードを設計します。 Antithesis の障害注入では、一時的なエラーが発生することを想定してください。ワークロードは障害が発生しても進行できる必要があります — バックオフして再試行し、切断時には再接続し、試行したことと確認応答を受けたことを追跡します。
• Antithesis 専用コードを本番環境の処理経路に持ち込まないでください。 アサーションのために共有コードに手を加える必要がある場合は、変更を最小限に絞ってください。SDK のアサーションは Antithesis 以外では何もしないため、本番環境への影響はごくわずかです。
• ワークロードコードはプロジェクトの言語で記述し、 プロジェクトのクライアント、ヘルパー、ライブラリを再利用できるようにしてください。
• ワークロードは機能とともに成長します。 開発中の機能では、未実装部分に TDD 形式のスタブを用意して、ワークロード全体を構築します。コードが追加されるにつれて、アサーションが成功するようになります。テストを始めるために、機能の完成を待たないでください。

出力

• antithesis/feature-workloads/<feature-slug>/analysis.md — 機能プロパティ、コードベースの調査結果、障害評価、反復履歴
• ワークロードコード（デュアルモードのアサーションを備えた自律実行プログラム）
• ローカル実行用のdocker-compose.yml（既存の設定で十分な場合を除く）
• 機能の不変条件を対象とするアサーションと、機能の動作に関する到達性の主張

セルフレビュー

このスキルが完了したと宣言する前に、以下の基準に照らして作業をレビューしてください。エージェントがサブエージェントに対応している場合は、新しいコンテキストでレビューする担当者を作成してください。

レビュー基準：

• システムの全体像を把握する作業を実施し、機能の周辺を把握するために、アーキテクチャ、データフロー、並行処理モデルを十分に理解している（または既存の調査資料を活用している）
• 機能の特性が analysis.md に記録され、コードベースの根拠とともに具体的なコードパスに結び付けられている（開発中の機能の場合は、計画された動作に結び付けられている）
• 各特性が具体的かつテスト可能であり、「機能をテストする」のような曖昧な目標ではなく、具体的な不変条件、到達可能な動作、または障害モードになっている
• ワークロードが機能の主要な動作を実行している（実際に発火する到達性の主張で検証されている。または開発中の機能の場合、実装済み部分の到達性の主張が発火し、未実装部分のスタブが明確に示されている）
• アサーションの意味に応じて適切な SDK 型を使用している（不変条件には Always ／ AlwaysOrUnreachable、到達性の主張には Sometimes、パスの到達可能性には Reachable）。references/assertions.md を参照してください
• Sometimes(true, ...) アサーションは Reachable(...) に書き換えられている
• ワークロードが単一のエントリーポイントを持つ自律実行プログラムであり、Test Composer コマンドではない
• ワークロードに耐障害性がある。一時的なエラーを再試行し、エラーが発生しても処理を進め、最初のエラーで終了しない
• ワークロードが試行した操作と確認済みの操作を追跡し、アサーションで正確な値ではなく範囲を検証できる
• ワークロードがデュアルモードである。ANTITHESIS_OUTPUT_DIR が設定されている場合は SDK アサーションを使用し、それ以外の場合はローカルチェックを行う
• 到達性の主張が違反ではなく前提条件を検証している。システムが正しいときに発火する
• 同じ箇所にある Always または AlwaysOrUnreachable アサーションの否定となる到達性の主張がない
• 値の選択に、任意の範囲ではなく、機能のコードパスに基づく境界値と設定済み制限の値群を使用している。references/interesting-values.md を参照してください
• アサーションのプロパティ名がインラインの定数文字列リテラルであり、プロジェクト全体で一意である。実行時に組み立てない
• ワークロードのランダム性には SDK のランダムモジュールを使用し、決定論的な再現を可能にしている（ローカルモードでは標準ライブラリのランダム機能を使用する）
• ワークロードのランダム性の形状が実行ごとに変化する（スウォームテスト）。確率とアクションの重みはハードコードせず、各実行の開始時に決定する
• まれで危険性の高い内部状態やタイミングに依存する内部状態について、SUT 側の的を絞ったアサーションが探索の指針を大幅に改善する場合に、ワークロードのみの計装を使用していない
• アサーションをワークロードコードまたは的を絞った SUT の箇所に置いている。本番パス全体に分散させていない
• Antithesis に移行する場合、場当たり的なセットアップではなく、インフラストラクチャに antithesis-setup スキルを使用している
• 機能の特性に障害の種類が関係する場合、それらの障害がテナントで有効になっていることを確認している。references/faults.md を参照してください
• feature-workloads ディレクトリに、分析した内容、見つかった特性、テストした内容、および各イテレーションで判明したことを記録している