antithesis-workload

Antithesis ワークロード

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

目的と目標

Antithesis ワークロードを実装または改善します。成功の条件は次のとおりです。

• antithesis-research スキルのプロパティが、プロパティカタログと各プロパティのエビデンスファイルの両方を使って、具体的なアサーションに対応付けられている
• antithesis/test/ の下にテストコマンドがあり、適切な動作を検証する
• セットアップ後に最初の実テスト用テンプレートが作成されている、または既存のテンプレートが拡張されている
• トリアージで見つかった事項が暗黙のまま残らず、ワークロードまたはプロパティの更新につながっている

まず antithesis-research スキルを使ってプロパティカタログを作成してください。antithesis-setup スキルを使ってインフラストラクチャを構築してください。antithesis-triage スキルを使って実行結果を確認した後、ここに戻ってワークロードを改善してください。ユーザーが実行の送信または開始を求めた場合は、antithesis-launch スキルを使ってください。snouty launch を直接実行してはいけません。

前提条件

• Antithesis のスクラッチブック（通常は antithesis/scratchbook/）が存在しない場合は、作業を進めてはいけません。antithesis-research スキルを使って作成してください。
• Antithesis 用の docker-compose.yaml が存在しない場合は、作業を進めてはいけません。antithesis-setup スキルを使って作成してください。
• snouty がインストールされていない場合は、作業を進めてはいけません。インストール方法については https://raw.githubusercontent.com/antithesishq/snouty/refs/heads/main/README.md を参照してください。
• snouty が 0.8.0 より古い場合は、作業を進めてはいけません。snouty --version でバージョンを確認してください。更新するには snouty update を使ってください。

対象範囲の設定

以下の「次のプロパティを実装する」ワークフローを実行するたびに、コンテキストを管理しやすく、品質を高く保つため、対象は1つのプロパティに絞ります。（トリアージ後の反復では、トリアージで見つかった事項に応じて独自に対象範囲を設定します。）

ユーザーが複数のプロパティを求めた場合は、1つずつ進めることを推奨してください。コンテキストが蓄積すると実装品質が低下し、各プロパティに必要な作業量も予測できないことを説明します。どのプロパティから始めるかを尋ねてください。ユーザーが複数の実装を希望し続ける場合は進めてもかまいませんが、事前に注意を促してください。

ユーザーが作業対象のプロパティを指定した場合は、カタログ全体のスキャンを省略します。ただし、作業を進める前に、そのプロパティのエビデンスファイルを確認し、実装状況を評価してください。すでに完全に実装されている場合は、作業をやり直すのではなく、その旨をユーザーに伝えてください。

ユーザーがプロパティを指定しなかった場合は、以下の検出と推奨の全フローを実行してください。

実装状況の検出

以下の検出作業では、すべてのエビデンスファイルを読み、コードベース全体でアサーションを検索するため、多くのコンテキストを使用します。エージェントがサブエージェントを利用できる場合は、プロパティごとの要約（状況と簡潔な根拠）を返すサブエージェントに委任してください。これにより、メインの実装エージェントのコンテキストをすっきり保てます。

検出タスク：カタログ内の各プロパティについて、既存のテストコードと SUT コードから Antithesis SDK のアサーション呼び出しを検索し、プロパティのエビデンスファイル antithesis/scratchbook/properties/{slug}.md と照合します。既存のアサーションが、エビデンスファイルに記載されたコードパス、障害シナリオ、計測ポイントを網羅しているかを評価します。各プロパティを次のいずれかに分類します。

• 実装済み — アサーションがエビデンスファイルの記述内容を網羅している
• 一部実装済み — アサーションは存在するが、網羅性が不十分
• 未実装 — 関連するアサーションが見つからない

状況を提示して推奨する

カタログに存在する来歴のフロントマターを読み取り、状況を提示する際に含めてください。見つかったフィールドを使ってください。スキーマは時間とともに変化する可能性があるため、一部のフィールドがない、あるいは古いフロントマターを不備として扱わないでください。記録されている内容を平易な言葉で説明してください。例：

• 完全なスキーマ：「カタログのコミット abc12345abcd（2026-05-05）を基に作業しています。SUT のパスは /foo、外部参照は A、B です。」
• 一部のみ：「カタログのコミット abc12345abcd（2026-05-05）を基に作業しています。SUT のパスと外部参照は記録されていません。」
• 記録なし：「カタログを基に作業しています（来歴の記録はありません。規約ができる前のものです）。」

ワークロードはプロパティの各サイクルで実行されるため、実行のたびに来歴の再確認をユーザーに求めないでください。状況として表示し、そのまま続行してください。作業対象のシステムと一致しなくなった場合は、ユーザーから伝えてもらいます。ユーザー向けのコミット表示では読みやすさを考慮して短縮ハッシュ（先頭12文字）を使いますが、フロントマターには完全な SHA が保存されています。

推奨するプロパティは一度に1つだけにしてください。カタログ全体を一度に表示しないでください。 カタログには数十、数百のプロパティが含まれることがあり、網羅的な状況一覧は圧倒されやすく、ユーザーが必要としている情報とは限りません。これをデフォルトとします。プロパティを1つ選び、選んだ理由を説明して、確認を待ってください。

例外は、ユーザーが単一の推奨を求めるのではなく、作業内容について話し合いたいと明示的に依頼した場合です。その場合は、全体像の概要（ステータス別の件数、注目すべきまとまり、特筆すべき点）を示して、会話を続けてください。個別のプロパティは、会話の流れに応じて提示してください。

推奨するプロパティの選び方：

• 始めたばかりの場合 — 実装済みのプロパティがほとんどない、またはまだない場合は、シンプルなプロパティを推奨します。テストの構成要素が多くないものを選びます。優先度が最も高いプロパティは、セットアップや調整に最も手間がかかる傾向にあるため、最初に取り組む対象としては適していません。シンプルなプロパティから始めると勢いがつき、SDK とテストハーネスをエンドツーエンドで動かし、ユーザーとともにワークフローの感覚をつかめます。この戦略を採用していることと、その理由をユーザーに伝えてください。
• 軌道に乗ってきたら — 複数のプロパティが実装され、ハーネスがエンドツーエンドで検証された後は、優先度に基づく順序に切り替えます。まず、完了が必要な一部実装済みのプロパティを選び、次に最近実装したものと関連する未実装のプロパティ（antithesis/scratchbook/property-relationships.md を参照）、続いてその他の優先度の高い未実装プロパティを選びます。この切り替えを行う際は、ユーザーに伝えてください。

選んだプロパティを推奨した理由を説明し、作業を進める前に、ユーザーが承認するか別のものを選ぶのを待ってください。

選んだプロパティについては、カタログの項目とその証拠ファイルの両方を読んでください。

その他のスコープに関する質問

安全に推測できない、ブロッカーやスコープの決定に関する質問だけをユーザーにしてください。例：

• 標準の antithesis/scratchbook/property-catalog.md 以外の場所にプロパティカタログがある場合、その場所
• リポジトリから明らかでない場合の、プロジェクトの言語または SDK の選択
• 既存のワークロードを反復している場合の、トリアージ結果や既知の不足点

定義と概念

• SUT： テスト対象システム。
• テストテンプレート： /opt/antithesis/test/v1/{name}/ にあるテストコマンドのディレクトリです。各タイムラインでは、1 つのテストテンプレートからコマンドが実行されます。helper_ が接頭辞に付いたファイルやサブディレクトリは Antithesis に無視されるため、コマンドと同じ場所に補助スクリプトを置く場合は、この接頭辞を使用してください。
• テストコマンド： 有効な接頭辞 parallel_driver_、singleton_driver_、serial_driver_、first_、eventually_、finally_、anytime_ のいずれかが付いた、テストテンプレート内の実行可能ファイルです。
• タイムライン： SUT とワークロードを線形に実行したものです。Antithesis は多数のタイムラインを並列で実行し、興味深い挙動を探索するために分岐させます。
• Always / AlwaysOrUnreachable： 安全性と正当性の特性に対するアサーションです。
• Sometimes(cond)： 少なくとも 1 回は発生すべき、生存性または自明でない意味的状態に対するアサーションです。
• Reachable / Unreachable： 意味のある結果または禁止された経路が実行されるかどうかに関するアサーションです。

ドキュメントに基づく情報

これらのページにアクセスするには、antithesis-documentation スキルを使用してください。snouty docs を優先してください。

• テストコマンドのリファレンス：https://antithesis.com/docs/product/test_templates/test_composer_reference.md
• 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

リファレンスファイル

リファレンス	読むタイミング
references/component-implementation.md	ワークロード側のコンポーネントまたはラッパーを実装するとき
references/assertions.md	プロパティを SDK アサーションに変換するとき
references/test-commands.md	コマンドを作成し、テストテンプレートを構成するとき
references/interesting-values.md	テスト対象のプロパティに対する値のメニューを選ぶとき
references/iteration.md	トリアージ後にカバレッジとアサーションを改善するとき

推奨ワークフロー

次のプロパティを実装する

1. 実装状況を検出し、プロパティを 1 つ推奨して、その理由を説明します（上記の「実装状況を検出する」と「提示して推奨する」を参照）
2. 実装するプロパティについてユーザーの確認を得ます
3. references/component-implementation.md を読みます
4. references/assertions.md を読みます
5. references/test-commands.md を読みます
6. references/interesting-values.md を読みます
7. プロパティの値のメニューを特定します。境界値に加え、設定された制限値の範囲を含めてください。発見手順と具体例については interesting-values.md を参照してください
8. 選択したプロパティを実装します。アサーション、テストコマンド、およびサポートコードを実装します
9. ワークロードが実行するよう設計されている挙動について、到達性の主張として Sometimes アサーションを記述します（references/assertions.md の「Sometimes Assertions as Workload Reach Claims」を参照）。違反ではなく、事前条件をアサートしてください。テストの実行には antithesis-launch を使用し、その後 antithesis-triage でどのアサーションが発火したかを確認します。発火しなかったアサーションは、ワークロードが目標に到達していない証拠であり、反復改善の出発点となります

トリアージ後の反復改善

1. references/iteration.md を読みます
2. アサーションを変更する必要がある場合は、references/assertions.md を読みます
3. コマンドのカバレッジを変更する必要がある場合は、references/test-commands.md を読みます
4. ワークロードと関連する Antithesis スクラッチブックの成果物を一緒に更新します

一般的なガイダンス

• Antithesis 専用のコードを本番環境のパスに含めないでください。共有コードに手を加える必要がある場合は、変更を最小限に抑え、簡単に切り離せるようにしてください。
• 高度に設定可能な抽象化よりも、シンプルなワークロードコードを優先してください。
• ワークロードは障害に耐えられるように設計してください。エラーがバグを示す正常系テストとは異なり、ワークロードは障害注入や並行アクティビティの下で実行されるため、一時的なエラーは例外ではなく想定内です。最初の失敗で中断するのではなく、目標に向けて処理を進めてください。
• antithesis-setup によって、システムはほぼアイドル状態で実行可能になっているものとします。このスキルが担当するのは、システムの起動後にワークロードが行う処理です。
• antithesis-setup によって、該当する SDK がインストールされ、SUT に最小限のブートストラップアサーションが追加されているものとします。このスキルが担当するのは、その最初の統合確認を超える、より広範なプロパティカタログです。
• テストコマンドは Bash ではなく、プロジェクトで使われている言語で記述し、プロジェクトのクライアント、ヘルパー、ライブラリを再利用できるようにしてください。

出力

• 対象範囲のすべてのプロパティに対するアサーション（ワークロードコード内、または適切に選定した SUT 内の箇所）
• antithesis/test/ 以下のテストコマンドと、それを支えるワークロードコード
• 実装したプロパティが変更された場合の antithesis/scratchbook/property-catalog.md の更新

セルフレビュー

このスキルの作業完了を宣言する前に、以下の基準に照らして成果物を確認してください。エージェントがサブエージェントを起動できる場合は、新しいエージェントを新鮮なコンテキストで起動してこのレビューを実施してください。そのエージェントにはこのスキルファイルのパスを渡し、すべての出力成果物を読むよう指示してください。新鮮なコンテキストでのレビュアーは、同じコンテキスト内でのレビューでは見落としがちな点を発見できます。サブエージェントを起動できない場合は、自分でレビューしてください。まず、このファイルの先頭にある成功基準を読み直し、次に以下の各項目を実際の成果物と照らし合わせて、一つずつ確認してください。

レビュー基準：

• スコープ内の各プロパティについて、実装では、エビデンスファイルに記載されたコードパス、失敗シナリオ、計測ポイントを網羅しています。「アサーションがある」だけでなく、「エビデンスで網羅が必要とされている内容をアサーションが網羅している」必要があります
• 各アサーションでは、そのプロパティの意味に適した SDK アサーション型を使用しています（安全性には Always／AlwaysOrUnreachable、活性や意味のある状態には Sometimes(cond)、パスや結果の確認には Reachable／Unreachable）
• Sometimes(true, ...) アサーションは Reachable(...) に書き換えてください。
• アサーションのプロパティ名は、プロジェクト全体で一意なインラインの定数文字列リテラルです。実行時に生成したり、変数経由で渡したりしてはいけません（静的解析で事前にカタログ化できるようにしてください。references/assertions.md の「Naming」を参照してください）。広範なプロパティを、無関係な複数の呼び出し箇所で同じメッセージを再利用して実装してはいけません
• まれな内部状態、危険な内部状態、またはタイミングに左右される内部状態について、SUT 側のピンポイントなアサーションが検索を大幅に改善できる場合に、ワークロードのみの計測を使用してはいけません
• ワークロードコードは、最初の失敗で中断するのではなく、一時的なエラーが発生しても明示された目標に向けて進行します
• ワークロードでは、試行した操作と確認応答を受け取った操作の両方を記録し、後続のアサーションで上限を確認できるようにします（例：「カウンターの変化量が [acknowledged, attempted] の範囲内」）
• リトライを使用する場合、SUT の冪等性契約と整合させてください
• Reachable(...) マーカーは、同じ直線的なフロー上で重複する早い段階のパス開始位置ではなく、異なる結果または分岐の結果に付与します
• テストコマンドの入力範囲が限定されている場合、任意の範囲ではなく、プロパティ固有の値メニュー（入力型の境界値に加え、そのプロパティのコードパスで設定された上限値の系列）から値を選びます。または、そのテストコマンドで該当する軸が適用されないことを明記します。interesting-values.md を参照してください。
• テストコマンドは antithesis/test/ 配下に配置し、有効なプレフィックス（parallel_driver_、singleton_driver_、serial_driver_、first_、eventually_、finally_、anytime_）を使用します
• テストコマンドは Bash ではなくプロジェクトの言語で記述し、可能な限りプロジェクトのクライアントとライブラリを再利用します
• テストコマンドで Antithesis のライフサイクル通知を行ってはいけません。テストコマンドの開始前に setup_complete を出力します
• テストテンプレートは、コンテナ内の /opt/antithesis/test/v1/{name}/ に対応するパスに正しい構成で配置します
• Antithesis が無視するよう、ヘルパーファイルやディレクトリには helper_ をプレフィックスとして付けます
• カタログに存在する出所情報のフロントマターは、ステータスの提示時にすべて表示し、ユーザーが作業中のシステムと食い違いがないか確認できるようにします
• antithesis/scratchbook/property-catalog.md を更新して、スコープ内のすべてのプロパティの実装状況を反映します。出所情報のフロントマターには、現在のコードベースの状態を反映させてください（commit と updated を更新し、既存のカタログにある sut_path と external_references は維持します）。フロントマターの形式は、antithesis-research スキルの references/scratchbook-setup.md で定義されています。
• ワークロードが発生させるよう設計されている動作について、到達性の主張として Sometimes アサーションを配置します。また、テスト実行で発火しなかった到達性の主張を、反復の指標として使用します（references/assertions.md の「Sometimes Assertions as Workload Reach Claims」を参照してください）
• 到達性の主張を、同じ箇所にある Always または AlwaysOrUnreachable の否定にしてはいけません。また、システムが正しい場合にも各到達性の主張が発火するようにします（references/assertions.md の「A Reach Claim Asserts The Precondition, Never The Violation」を参照してください）
• アサーションはワークロードコードまたはピンポイントな SUT の箇所に配置し、本番コードのパス全体に散在させてはいけません
• antithesis/config に対して snouty validate を実行し、compose のセットアップがセットアップ完了まで到達できることと、設定済みのテストテンプレートが機能することを確認します。validate の実行前に、最新のイメージをビルドしてください。