分散型および状態保持システム向け AI コーディングエージェントのテストスキル

AI コーディングエージェントが、分散型および状態保持システムに対してクレーム駆動（Claim-driven）なテストを設計・実行できるようになるには、以下の 2 つのスキルが必要です。これらを組み合わせることで、構造化された Markdown テスト計画と、9 つの状態を持つ判定結果を含む発見レポート（Findings Report）、そして明確な SUT（被験システム）/ ハネス / チェッカー / 環境に対する責任の分類を生成します。レビュー担当者はこれらの 2 つのアートを閲覧し、リリースを許可するかどうかを決定すればよく、これ以外に再実行する必要はありません。

本スキルのセットは、Claude Code、Codex、Copilot CLI、Cursor、Gemini、あるいは Markdown を読み込みシェルを実行できるあらゆるエージェントと互換性があります。スキル本体は単なる

SKILL.md

ファイルであり、エージェントがそれらを実行し、計画および発見レポートが出力となります。

1 つのスキルは計画を設計し、もう 1 つがその計画を実行します。計画プロセスでは、製品のクレームから出発し、それらのクレームと紐付いた仮説を生成し、各シナリオを「反証しようとするクレームの名前」で命名して記述します。整合性がcritical なシナリオにおいては、各シナリオが抽象的なモデル（レジスタ | クイュー | ログ | ロック | リース | 台帳 | …）に結合されるようになり、操作履歴スキーマ、命名されたチェッカー、そして観測可能な着陸証拠を持つネメシスを導入します。計画は、カバレッジ適正性の議論と保守的な信憑性ステートメントで終了します。

なぜ必要なのか（Why）

分散型および状態保持システムのデフォルトのテスト手法である「数個の統合テストを書くと呼び込み完了」というアプローチでは、実際にプロダクションでこれらのシステムを破壊してしまうバグのごく一部しか発見できません（部分的ネットワークパーティション、非決定論的な同時実行、クラッシュ・リカバリ、アップグレード/ロールバック、再生における冪等性、タイミング感受性の順序付けなど）。

本スキルは、業界の苦心して得られた知見を基盤とした意見ありき（Opinionated）なワークフローを強制します：

• テスト駆動ではなく、クレーム駆動。 製品の約束事から出発します。各シナリオは、1 つの障害下で 1 つのクレームを反証します。「セットアップ」の名前がついたテストよりも、「クレーム」の名前がついたテストの方が弱くされにくいという原則です。
• カバレッジ適正性が成果物である。 計画は、選択したシナリオがリリースに適していることを証明する議論で終了し、検証されていない事項について正直なリストを付記します。
• SUT のツールボックスを再利用する。 「新しいもの」を発明する前に、実行スキルは既存のテスト、runbooks（操作マニュアル）、および障害注入のスキャファルディングを自動的に発見します。
• **単なる混沌ではなく、「モデル ＋ 履歴 ＋ チェッカー」。安全性、耐久性、冪等性、隔離性、順序付け、あるいはメンバーシップに関するクレームにおいては、各シナリオで抽象モデル、操作履歴スキーマ、命名されたチェッカー（線形化可能性、シリアライゼビリティ、セッション一貫性、ACK 欠落なし、正確に一度実行など）、そして曖昧な結果の扱い方（タイムアウト、不明なコミット、リトライなど）を宣言します。単なる混沌ではなく、モデルとチェッカー付きの混沌です。
• サイレントな通過は許さない。 各 PASS は、オラクルの実行証拠および障害が実際に発火したことを示すシグナルを引用します。判定は 9 つの状態のセットから来るため、「カオス脚本がクリーンに走った」と読むことは「クレームが障害を生き延びた」ことにはなりません。各 FAIL は SUT / ハネス / チェッカー / 環境の責任分類タグを伴うため、再現担当者が必要とされるキューに到達できます。

受け取れる成果物（What you get）

エンドツーエンドにおいて、2 つのスキルは以下のものを生成します：

• testing-plans/<slug>.md

  — §0–§9 を含む計画

• test-sessions/<UTC>/

  • session-log.md

    — タイムライン＋ツールボックス＋環境プローブ

  • logs/

    — シナリオごとの stdout/stderr

  • metrics/

    — メトリックのショット

  • artifacts/

    — 一時的なハネス、ダンプファイル

  • findings/

    • <scenario>.md

      — シナリオごとの判定（実行進行中に記述）

    • report.md

      — サマリー＋適正性＋信憑性デルタ

計画の構造（The plan structure） （レビュー担当者はこの文書を読み、テストを再実行せずにリリース可否を判断できます）

1. アーキテクチャサマリー — 実際のシステム状態
2. スコープ 1b. テスト対象のクレーム — 主軸 1c. 発見された未対応のクレーム — ドキュメントとコードのドリフト
3. SUT モデル
4. 既存テストのインベントリ — 既にカバされている範囲
5. 障害モード仮説 — クレーム ID に紐付く
6. カバージオス行列 — クレーム × 仮説
7. テクニック選択 — キャタログから 6b. 環境要件
8. シナリオ — クレームの名前で命名され、対象テストファイル＋スケルトンを含む 7.M モデル／履歴／チェッカー規律 — シナリオが {安全性、耐久性、冪等性、隔離性、順序付け、メンバーシップ} のいずれかにおいてクレームを反証する場合に必須：被験モデル、操作履歴スキーマ、命名されたチェッカー、ネメシス＋着陸証拠、曖昧結果の扱い、削減計画（SUT/ハネス/チェッカー/環境責任分類） 7b. カバージオス適正性の議論 — これらのテストが十分である理由 7c. 残余の不確実性 — 検証不能な事項とその許容理由 7d. 信憑性ステートメント — レビュー担当者の判定
9. この計画でカバーしていないこと
10. 未解決の課題／フォローアップ

§7.M ブロックの例（計画からの抜粋）

シナリオ S3: パーティション下での線形化可能な追加

• FAIL の場合、以下を反証する: C1（すべての ACK 付与された追加は永続的かつ線形化可能）、C5（リーダー選出が 5 秒以内に完了）
• ワークロード: クライアント 8、追加 70% / リード 30%、5 分間、キー歪み Zipf
• 障害: T+60s で 30 秒間、現在のリーダーを孤立させる非対称パーティション
• オラクル: キーごとの履歴に基づき Porcupine を介した線形化可能性

§7.M（モデル／履歴／チェッカー規律）

• 被験モデル: log
• 操作履歴: デフォルト 11 フィールドスキーマ（op id、process id、invoke/complete ts、op type、key、input、output、error、timeout marker、node seen、fault epoch）。インプロセス＋サーバーサイド監査にて記録。
• チェッカー: キーごとの線形化可能性（Porcupine）、そして最終状態に対する no-lost-ack
• ネメシス＋着陸: 一方通行のダロップを行う非対称パーティション（iptables）。着陸証拠 = 30 秒ウィンドウ内で iptables ドロップカウンターが 0→14,712 となり、RAFT ログが「leader-lost; starting election」を注入から 2 秒以内に出力すること。
• 曖昧結果の扱い: タイムアウト → timeout_marker=true、complete_ts=null、成功し得たと見なす。リトライは入力共有する別々のオペレーションとする。
• 削減計画: FAIL の場合、障害ウィンドウをバイセクト＋シード修正、その後 references/test-case-reduction.md に従って SUT / ハネス / チェッカー / 環境を分類。

発見レポートの例（行）

ID	Verdict (判定)	Nemesis landing evidence (ネメシスの着陸証拠)	Reduction class
S3	PASS-hardening	iptables ctr 0→14,712; raft re-election at T+1.8s	n/a
S4	FAIL-reproducible	partition landed; Elle: G2-item anomaly on key K17	SUT
S7	INCONCLUSIVE-fault-not-proven	iptables rule installed but counter stayed 0 — wrong chain	harness
S9	PARTIAL-model	landing ok; checker covered per-key, not cross-key	n/a

（完全な発見レポートテンプレートには、オラクル、オラクル実行証拠、アーツリンク、適正性対計画セクション、信憑性デルタが含まれます——スキル/eexecuting-distributed-system-tests/assets/findings-report-template.md を参照。）

インストール（1 行で任意のエージェント向け）

以下を任意の AI コーディングエージェント（Claude Code, Codex, Copilot CLI, Cursor, Gemini, など Markdown を読みシェルを実行するもの）に貼り付けてください： https://raw.githubusercontent.com/shenli/distributed-system-testing/main/INSTALL.md を読み、指示に従ってこのエージェント用に distributed-testing-skills をインストール・設定してください。

エージェントは INSTALL.md を取得し、リポジトリを

~/.local/share/distributed-testing-skills/

にクローンし、スキルをワイヤーします（Claude Code の場合は

~/.claude/skills/

下にシンボリックリンク、他のエージェントの場合は ~/AGENTS.md 内のポインタブロック）。その後、マシン上の任意のエージェントに「このシステムのテスト計画を作成」または「X で計画を実行」と指示すれば、SKILL.md ワークフローに従います。

更新

同じワンライナーを再度貼り付けると OK です。INSTALL.md は冪等性あり：インストール経路が存在する場合

git pull --ff-only

を、存在しない場合は

git clone

を実行します。シンボリックリンクは常にクローンされたコンテンツを指し示すため、新バージョンが自動的に拾われます。~/AGENTS.md のポインタブロックは HTML マーカーを使用し、各実行でクリーンに置換されるため重複不会产生しません。 クローンしたスキルに対してローカルでの編集を行っているのであれば、

git pull --ff-only

は失敗し、エージェントは破棄前に問いかけます。

手動インストール（何が起こっているかを目視したい場合）

git clone https://github.com/shenli/distributed-system-testing.git ~/.local/share/distributed-testing-skills

# Claude Code: ~/.claude/skills/ 下にシンボリックリンクを作成
mkdir -p ~/.claude/skills
ln -snf ~/.local/share/distributed-testing-skills/skills/designing-distributed-system-tests ~/.claude/skills/designing-distributed-system-tests
ln -snf ~/.local/share/distributed-testing-skills/skills/executing-distributed-system-tests ~/.claude/skills/executing-distributed-system-tests

# Codex / Copilot CLI / Cursor / Gemini / その他: INSTALL.md を参照

使用方法

スキルがインストールされると、2 つのドライブ方法があります：

• カジュアルな問いかけ（Claude Code での自動トリガー）:
  • このコードベース向けのプロジェクト全体計画を設計。
  • ./testing-plans/.md でこのコードベースに対して計画を実行。
  • スキル説明は、「テスト計画を設計」「計画を実行」「安定性テストを実行」「リリース検証計画を設計」などの自然な表現を拾い上げます。
• 特定のモード、出力パス、または自動トリガーしないエージェント向け: USAGE.md には、すべてのワークフロー（設計・実行それぞれのモード）のためのコピー＆ペーストプロンプト、スコープ、環境プローブ、長期実行のチェックポイントングに関するヒントが含まれています。

2 つのスキル

1. designing-distributed-system-tests

   • リポジトリを歩きながら製品のクレームを抽出し、それらのクレームと紐付いた仮説を生成し、カタログからテクニックを選び、カバージオス適正性の議論と信憑性ステートメントを含む構造化された Markdown 計画を作成します。
   • 整合性が critical なシナリオにおいては、各シナリオごとに §7.M ブロックを埋め：被験モデル、操作履歴スキーマ、命名されたチェッカー、ネメシス＋着陸証拠、曖昧結果の扱い、削減計画。詳細は history-discipline.md を参照。
   • 2 つのモード: change-scoped（特定のコミットまたは PR）と project-wide（既存テストインベントリとギャップ分析を含むホリスティックな計画）。

2. executing-distributed-system-tests

   • 計画を読み込み、SUT のツールボックスを発見し、環境をプローブし、チェックポイント規律を持つシナリオを実行します。
   • シナリオごとに：障害の着陸証拠をキャプチャ、グリーンだが壊れている（green-but-broken）および弱オラクル監査を実行、verdict-taxonomy.md の 9 ステート分類から判定を割り当て、各 FAIL を SUT / ハネス / チェッカー / 環境に分類して提出します。適正性対計画評価と信憑性デルタを含む発見レポートを生成します。
   • 2 つのモード: default（SUT に対する読み取り専用、セッションディレクトリ下の一時的なハネス）と author mode（計画の §7 に宣言されたシナリオスケルトンを SUT に書き込むためにレビュー用）。

テクニックカタログ

業界の文献から抽出された 8 つのリファレンスファイル：

ファイル	何の状況で使用するか
catalog-index.md	セレクターページ — ここから始める
jepsen-and-elle.md	障害下での線形化可能性／シリアライゼビリティ
deterministic-simulation.md	シードからの再現可能なバグ；非同期重いコード
chaos-and-fault-injection.md	リアルクラスタの部分的/非対称な障害
fuzzing.md	サンタイザー下の入力または同時実行ファズング
formal-methods-tla.md	デザイン時のプロトコル正当性
property-and-metamorphic.md	代数的法則／メタモρφic関係テスト
performance-and-benchmarking.md	テイルレイテンシー / スループット / フェアネス
crash-recovery-and-upgrade.md	耐久性、再生、冪等性、ミックスバージョン

各ファイルは「使用タイミング」「得意なこと」「見落としやすいこと」「具体的なツール」「論文」「コストシグナル」「計画チェックリスト」に従います。カタログインデックスは症状をリファレンスにマッピングします。

リポジトリ構造

.
├── plugin.json                                 ← 任意のプラグイン manifests
├── README.md                                   ← このファイル
├── INSTALL.md                                  ← 冪等性のインストール/更新（貼り付ける）
├── USAGE.md                                    ← すべてのワークフローのためのコピー＆ペーストプロンプト
├── LICENSE
├── skills/
│   ├── designing-distributed-system-tests/
│   │   ├── SKILL.md                            ← 設計ワークフロー
│   │   ├── assets/plan-template.md             ← §0–§9 含むゲート付き §7.M
│   │   └── references/                         ← テクニックカタログ（8 ファイル）＋インデックス、共通分散システム陷阱点、history-discipline
│   └── executing-distributed-system-tests/
│       ├── SKILL.md                            ← 実行ワークフロー
│       ├── assets/
│       │   ├── session-log-template.md
│       │   └── findings-report-template.md     ← 9 ステート判定＋着陸証拠
│       └── references/                         ← オラクルパターン（チェッカーペイカー＋13 パターン）、障害注入ハウツー（ネメシス分類 22 行）、テストケース削減（責任分類付き）、グリーンだが壊れている赤フラグ（弱オラクル監査含む）、発見分類（TaxDC）、判定分類（9 ステート）
├── evals/                                      ← 両方のスキル向けの評価スイート
├── verification/                               ← AgentDB に対する実際の実行（具体的な出力）
└── specs/                                      ← オリジナル設計仕様書

ステータス

初期段階ですが、既に exercised です。両方のスキルは Rust で実装された分散型エージェントランタイムである AgentDB を対象に、エンドツーエンドで複数回駆動され、6 つの発見を表面化しました（1 つの P0 候補は現在クローズ済み、2 つの P1 は PR として出荷済み、2 つは未解決）。スキル本体はハネスの実経験に伴って進化するため、来週の数回のイテレーション間で SKILL.md ファイルやテンプレートにマイナーな更新が期待されます。

実際の計画出力、セッションディレクトリ、そしてそれらの実行からの発見レポートは

verification/

下に存在します（各実行ごとにサブディレクトリがあり、README.md が何通过了ったか、何が失敗したか、スキル自身がプロセスで表面化したことは記述）。顕著な実行例：

• verification/agentdb-fab7d9d/

  — AgentDB コミット fab7d9d 向けの change-scoped プラン＋実行（永続的冪等性追加再生）；8 つの障害モードカテゴリを横断した合計 16 の仮説を持つ 670 行の計画。

• verification/agentdb-jepsen/

  — 線形化可能性チェック付きの整合性＋クラッシュ・リカバリ実行。

• verification/agentdb-projectwide-lidev/

  と

  -v2

  — 完全なカバージオス行列＋適正性議論＋信憑性ステートメントを含むプロジェクト全体計画。

また、

evals/

下には評価スイート（設計スキルと実行スキルそれぞれに対して別々の evals.json）があり、SKILL.md 本体の行動変更にわたる検証に使用されます。

謝辞

テクニックカタログは、Andrey Satarin の包括的な「distributed-systems-testing」カタログから抽出されたものです。カタログを根幹づける seminal な論文は以下の通りです：

• Yuan et al., "Simple Testing Can Prevent Most Critical Failures" (OSDI'14)
• Gunawi et al., "What Bugs Live in the Cloud?" (SoCC'14)
• Zheng et al., "Torturing Databases for Fun and Profit" (OSDI'14)
• Kingsbury & Alvaro, "Elle: Inferring Isolation Anomalies from Experimental Observations" (VLDB'20)
• Alfatafta et al., "Toward a Generic Fault Tolerance Technique for Partial Network Partitioning" (OSDI'20)
• Lou et al., "Understanding, Detecting and Localizing Partial Failures in Large System Software" (NSDI'20)
• Gao et al., "An Empirical Study on Crash Recovery Bugs in Large-Scale Distributed Systems" (FSE'18)
• Zhang et al., "Understanding and Detecting Software Upgrade Failures in Distributed Systems" (SOSP'21)
• Bornholt et al., "Using Lightweight Formal Methods to Validate a Key-Value Storage Node in Amazon S3" (SOSP'21)
• Newcombe et al., "How Amazon Web Services Uses Formal Methods" (CACM'15)

ライセンス

MIT。