antithesis-research

Antithesis Research

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

目的と目標

対象システムを調査し、後続のワークフローを進めるためのスクラッチブック成果物を作成します。成功とは、次の状態を指します。

• antithesis/scratchbook/sut-analysis.md にアーキテクチャ、状態、並行処理、障害が発生しやすい領域が記録されている
• antithesis/scratchbook/property-catalog.md に、優先度を付けた具体的でテスト可能なプロパティが一覧されている
• antithesis/scratchbook/deployment-topology.md に、最小限で有用なコンテナ構成が記述されている
• antithesis/scratchbook/properties/{slug}.md に、プロパティごとの証拠の追跡とコンテキストが記録されている
• antithesis/scratchbook/property-relationships.md に、プロパティ間の推定されるクラスターと関連性がまとめられている
• antithesis/scratchbook/evaluation/synthesis.md に、分類された評価結果と実施した対応が記録されている

前提条件とスコープ設定

各調査の開始時に、外部の参照資料についてユーザーに尋ねます。

開始する前に、参照すべき、このディレクトリツリー外のドキュメント、設計メモ、関連リポジトリ、課題トラッカーなどはありますか？「このディレクトリだけ」で構いません。

回答はそのまま記録します。外部参照はそれぞれ、path（または URL）と簡単な why メモとして記録します。オーケストレーター（このスキル）は、実行中ずっと回答を保持し、トップレベルの成果物を作成する各参照ワークフロー（sut-discovery.md、sut-analysis.md、property-discovery.md、deployment-topology.md、property-evaluation.md）への入力として渡します。各参照のエージェント指示セクションは、このリストを入力として受け取ります。また、このリストはすべてのトップレベル成果物の出所情報を示すフロントマターにも記録されます（references/scratchbook-setup.md を参照）。外部参照を受け取ったエージェントは、各参照を事実ではなく検証すべき手がかりとして扱います（references/validating-claims.md を参照）。

スコープに関する質問以外では、安全に推測できないブロッカーやスコープ上の判断事項についてのみ尋ねます。

• リポジトリまたはコードベースの場所（まだ明確でない場合）
• 作業範囲がリポジトリ全体より狭い場合、最も重要なサブシステムまたはコンポーネント
• 対象とすべき既知のインシデント、クローズ済みのバグ、または特定の障害モード

スクラッチブック成果物がすでに存在する場合は、ユーザーから新たな調査を求められない限り、書き換えるのではなく入力として扱い、内容を拡張します。

定義と概念

• SUT： テスト対象システム。
• ワークロード： 対象システムに負荷をかけるために設計された合成ワークロード
• 安全性プロパティ（正確性）： 悪いことが決して起きない
• 活性プロパティ（進行）： 良いことがいずれ起きる
• 到達可能性プロパティ： コードパスまたは動作に到達できるか、到達できないか
• テストテンプレート： /opt/antithesis/test/v1/{name}/ にあるテストコマンドのディレクトリ。テストテンプレートは複数ある場合があります。各タイムラインは、単一のテストテンプレートからコマンドを実行します。helper_ で始まるファイルまたはサブディレクトリは Antithesis によって無視されます。
• テストコマンド： 有効なプレフィックスが付いた、テストテンプレート内の実行可能ファイル。有効なプレフィックス：parallel_driver_、singleton_driver_、serial_driver_、first_、eventually_、finally_、anytime_
• タイムライン： 対象システムとワークロードを線形に実行したもの。Antithesis は多数のタイムラインを並列実行し、興味深い動作を探索するために分岐させます。

ドキュメントに基づく指針

Antithesis 固有の用語や実装に関するアドバイスの根拠として、antithesis-documentation スキルを使用します。

• プロパティとアサーション：https://antithesis.com/docs/concepts/properties_assertions/assertions.md
• 場合によって成立するアサーション：https://antithesis.com/docs/concepts/properties_assertions/sometimes_assertions.md
• テストプロパティの定義：https://antithesis.com/docs/reference/sdk/define_test_properties.md
• SDK の実行モードと本番環境での動作：https://antithesis.com/docs/reference/sdk.md
• テストに向けた最適化：https://antithesis.com/docs/best_practices/optimizing.md

参照ファイル

参照	読むタイミング
references/scratchbook-setup.md	常に最初に読み、ワークスペースを初期化します
references/sut-discovery.md	構造化された注目ポイントを通じて、システムの特性を発見するとき
references/sut-analysis.md	コードベースを分析し、コンポーネントを理解するための一般的な方法論
references/property-discovery.md	構造化された注目ポイントを通じて、プロパティを発見するとき
references/property-catalog.md	プロパティを文書化する形式と方法論
references/validating-claims.md	ドキュメントや課題の主張の扱い方 — その主張を根拠にする前に検証します
references/faults.md	フォールトの種類、静穏期間、プロセスフォールトが発生しうる状況の理解
references/deployment-topology.md	Antithesis 用のコンテナートポロジーの設計
references/property-evaluation.md	プロパティカタログをポートフォリオとして評価する方法

推奨ワークフロー

全体的な調査（新規プロジェクト）

1. references/scratchbook-setup.md を読む
2. references/sut-discovery.md と references/sut-analysis.md を読む
3. references/sut-discovery.md のアンサンブルまたは単一エージェントのワークフローを使ってシステムを分析する
4. コードベースを調べ、既存の Antithesis SDK アサーションを確認します。Antithesis SDK のインポートと、アサーション関数の呼び出し（assert_always!、assert_sometimes!、assert_reachable!、assert_unreachable!、またはそれらに相当するマクロを使わない形式）を検索します。見つかったアサーションごとに、ファイルパス、行番号、アサーションの種類、メッセージ文字列を記録します。結果を antithesis/scratchbook/existing-assertions.md に書き込みます。references/scratchbook-setup.md に従い、プロヴェナンスのフロントマターをファイルの先頭に記述します。アサーションが見つからなかった場合は、コードベースに既存の計測機能がないことを確認する注記をファイルに記載します。
5. references/property-discovery.md と references/property-catalog.md を読む
6. references/property-discovery.md のアンサンブルまたは単一エージェントのワークフローを使ってプロパティを発見する
7. references/deployment-topology.md を読む
8. デプロイメントトポロジーを設計し、antithesis/scratchbook/deployment-topology.md に記述する
9. references/property-evaluation.md を読む
10. references/property-evaluation.md のアンサンブルまたは単一エージェントのワークフローを使ってプロパティカタログを評価する
11. 評価で見つかった課題に対処します。改良を適用し、不足を補い、バイアスをユーザーに報告します
12. 残りの調査結果をすべて antithesis/scratchbook/ 以下に書き込むか、更新する

対象を絞ったプロパティ調査

1. システムモデルがない、または古くなっている場合は、references/sut-discovery.md と references/sut-analysis.md を読む
2. references/property-discovery.md と references/property-catalog.md を読む
3. references/property-discovery.md のアンサンブルまたは単一エージェントのワークフローを使ってプロパティを発見する
4. 主張されている保証を明示的なプロパティにする。インシデントやバグ報告については、報告された欠陥が実際のシステム上の欠陥であることを確認してからプロパティにします（references/validating-claims.md を参照）。それぞれに適した Antithesis アサーションの種類を選びます
5. antithesis/scratchbook/property-catalog.md を更新し、前提や未解決の疑問を記録する
6. 新しいプロパティのエビデンスファイルを antithesis/scratchbook/properties/{slug}.md に作成する
7. 新しいクラスターや関連性があれば、antithesis/scratchbook/property-relationships.md を更新する
8. references/property-evaluation.md を読む
9. references/property-evaluation.md のアンサンブルまたは単一エージェントのワークフローを使って、更新したプロパティカタログを評価する
10. 評価で見つかった課題に対処します。改良を適用し、不足を補い、バイアスをユーザーに報告します

プロパティの拡張（トリアージ後）

1. references/property-discovery.md と references/property-catalog.md を読みます
2. antithesis-triage スキルのトリアージ結果を確認します
3. references/property-discovery.md の注目点を使い、トリアージ結果から着想を得た新しいプロパティを探します
4. スクラッチブック内の関連ファイルを更新します
5. 新しいプロパティのエビデンスファイルを antithesis/scratchbook/properties/{slug}.md に作成します
6. 新しいクラスターや関連性があれば、antithesis/scratchbook/property-relationships.md を更新します
7. 拡張が大規模な場合（新しいプロパティカテゴリ、または新しいプロパティが 3 件を超える場合）は、references/property-evaluation.md を読み、更新後のカタログを評価します。既存カテゴリ内の 1〜3 件の小規模な拡張では、評価をすべてやり直す必要はありません。

一般的なガイダンス

• 「フェイルオーバーをテストする」のような曖昧な目標よりも、具体的で検証可能な保証を優先します
• システムのドキュメントやコメントで保証が主張されている場合は、テスト対象のプロパティにします。そのプロパティで主張を検証し、分析の中で保証が成り立つと断言しないでください
• イシューのバグ報告は手がかりであり、事実ではありません。その報告された不具合が実際にシステムの不具合であることを確認してから、それを基に作業してください（references/validating-claims.md を参照）
• 不変条件だけでなく、そのプロパティに選んだ Antithesis のアサーションタイプが意味的に適切である理由も記録します
• Sometimes(cond) は、活性や自明でない意味上の状態に使用します。すべての評価で成り立つ必要がある不変条件には使用せず、Reachable(...) の代用にも使用しないでください
• 特にまれな状態、危険な状態、タイミングに左右される状態、外部から見えない状態について、SUT 側に的を絞ったアサーションを置くことで、ワークロードのみのチェックよりも探索の指針が大幅に改善される箇所を特定します
• Antithesis SDK のアサーションは、失敗してもプログラムをクラッシュさせません。本番コードでも安全に使えるよう設計されており、通常は Antithesis の外では低オーバーヘッドのフォールバックまたは何もしない処理になります
• Antithesis が特に得意とする、タイミング、並行処理、部分的な障害に関わるシナリオに注力します
• デプロイのトポロジーは最小限に保ちます。コンテナーが増えるたびに状態空間が広がります
• 暗黙のままにせず、前提条件と未解決の疑問をスクラッチブックに書き留めます
• 調査の一部だけが依頼された場合でも、関連するスクラッチブックのファイルを更新し、未完了の項目を記載します

出力

• antithesis/scratchbook/sut-analysis.md
• antithesis/scratchbook/existing-assertions.md
• antithesis/scratchbook/property-catalog.md
• antithesis/scratchbook/deployment-topology.md
• antithesis/scratchbook/property-relationships.md
• antithesis/scratchbook/properties/{slug}.md（カタログに記載したプロパティごとに 1 ファイル）
• antithesis/scratchbook/evaluation/synthesis.md
• antithesis/scratchbook/evaluation/{lens}.md（評価レンズごとに 1 ファイル）

上記の一覧にある最上位のスクラッチブック成果物はすべて（プロパティごとのエビデンスファイルを除く）、sut_path、commit、updated、external_references を記録したプロベナンスのフロントマターを含めます。プロパティごとのエビデンスファイルは property-catalog.md からコンテキストを引き継ぐため、個別のフロントマターは不要です。references/scratchbook-setup.md を参照してください。

これらの出力は、antithesis-setup スキルと antithesis-workload スキルが直接利用できるほど具体的なものにしてください。

自己レビュー

このスキルの完了を宣言する前に、以下の基準に照らして作業を確認します。エージェントがサブエージェントを起動できる場合は、新しいエージェントを新鮮なコンテキストで起動し、このスキルファイルのパスを伝えて、すべての出力成果物を読ませてレビューさせてください。新鮮なコンテキストでのレビューは、同じコンテキスト内でのレビューでは見落とされる点を発見できます。サブエージェントを利用できない場合は、自分でレビューします。ファイルの冒頭にある成功基準を読み直し、実際の出力を以下の各項目に照らして体系的に確認してください。

レビュー基準：

• antithesis/scratchbook/sut-analysis.md が存在し、アーキテクチャ、状態管理、並行性モデル、障害が発生しやすい領域を扱っている
• antithesis/scratchbook/existing-assertions.md が存在し、コードベースで見つかった Antithesis SDK のアサーションをすべて列挙している（または、見つからなかったことを明記している）
• エビデンスファイルでは、コードベースにすでに存在するインストルメンテーション、一部存在するインストルメンテーション、不足しているインストルメンテーションが正しく区別されている。すでに存在するアサーションの追加を提案するエビデンスファイルはない
• antithesis/scratchbook/property-catalog.md が存在し、references/scratchbook-setup.md に従ったプロベナンスのフロントマターがあり、「フェイルオーバーをテストする」のような曖昧な目標ではなく、具体的でテスト可能なプロパティが列挙されている
• すべてのトップレベルの成果物に、references/scratchbook-setup.md に従ったプロベナンスのフロントマターがある
• external_references のリストは、ユーザーが示したスコープに関する回答を反映している。参照された項目には、その用途を説明する why の注記がある
• スコープに関する質問は実行開始時に行われ、分析を担当したすべてのサブエージェントにユーザーの回答が渡されている
• 各プロパティには、正規 ID として内容を表す kebab-case のスラッグが付いている
• 各プロパティには優先度があり、選択した Antithesis のアサーションタイプ（Always、Sometimes、Reachable など）の根拠が記載されている
• 内部の分岐制御やリプレイアンカーが必要なプロパティでは、ワークロードから確認できるチェックだけでなく、SUT 側でのインストルメンテーション候補箇所も挙げられている
• antithesis/scratchbook/deployment-topology.md が存在し、最小限のコンテナートポロジーを説明している。各コンテナーには存在理由がある
• カタログに登録された各プロパティに対応するエビデンスファイル antithesis/scratchbook/properties/{slug}.md があり、エビデンスの経緯、関連するコードパス、重要な観察事項が記録されている
• 各プロパティのカタログ項目には、そのエビデンスファイルにある未解決の質問を反映した「Open Questions」リストが含まれている（簡潔な要約のみとし、詳しい内容はエビデンスファイルに記載する）。解決済みの質問は削除され、残りの質問には references/property-catalog.md の「Open Questions Conventions」に従ったタグが付いている
• 各 (partial: ...) または (needs human input) タグは、エビデンスファイルの調査ログ項目（references/property-catalog.md の「Investigation Log」を参照）で裏付けられている。調査ログには、調査した内容、判明したこと、判明しなかったことが記録されている。タグのない（未調査の）質問には、ログ項目は不要。人間の入力が必要な未解決の質問は許容される結果だが、エビデンスファイルに埋もれさせず、カタログの概要に表示されている
• 調査によって無効と判明したプロパティには、その理由がカタログに記載されている
• antithesis/scratchbook/property-relationships.md が存在し、関連するプロパティをクラスターにまとめ、推測される関連性と優位性について簡潔な注記がある
• property-relationships.md で参照されているすべてのプロパティスラッグが、カタログ内のプロパティに対応している
• プロパティは、Antithesis が特に得意とする、タイミング依存、並行性依存、部分障害のシナリオに焦点を当てている
• ドキュメントやコメントに記載された保証は、テスト対象のプロパティとして表現されており、分析ではいかなる保証も確立済みの事実として述べていない
• バグ報告に基づき特定の不具合が存在すると述べる場合は、その不具合が実在し、報告者の環境や設定が原因ではないことを示す一次エビデンスが引用されている。イシューへのリンクや症状の一致だけでは不十分
• プロパティ評価が行われており、分類された調査結果を含む antithesis/scratchbook/evaluation/synthesis.md が存在する
• 評価で得られた改善点がカタログに反映されている
• 評価で見つかった不足を対象を絞った調査で補い、その結果得られたプロパティがエビデンスファイルとともにカタログに登録されている
• 評価に偏りがある場合は、裏付けとなるエビデンスを添えてユーザーに提示されている
• 出力は antithesis-setup と antithesis-workload がそのまま使えるほど具体的であり、曖昧な手順や不足している詳細がない