# 分散システムテストスキル
**分散システムおよびステートフルシステム向けに、クレーム駆動のテストを設計・実行するAIコーディングエージェントのための2つのスキル。** この2つを組み合わせることで、構造化されたMarkdownテスト計画と、10状態の判定結果およびSUT/ハーネス/チェッカー/環境の明示的な責務分類を備えた調査レポートを生成します。レビュー担当者はこの2つの成果物を読んでリリース可否を判断します。その他の再実行は不要です。
Claude Code、Codex、Copilot CLI、Cursor、Gemini、またはMarkdownを読み取ってシェルを実行できるあらゆるエージェントで動作します。このスキルはプレーンなSKILL.mdファイルです。エージェントがこれを実行し、計画と調査レポートが出力となります。
一方のスキルが計画を設計し、もう一方がそれを実行します。計画は製品のクレームから始まり、そのクレームに紐づく仮説を生成し、それぞれが反証しようとするクレームにちなんで命名されたシナリオを記述します。一貫性が重要なシナリオでは、各シナリオは抽象モデル（`register | queue | log | lock | lease | ledger | …`）を操作履歴スキーマ、名前付きチェッカー、および観測可能な着地証拠を伴うネメシスに結び付けます。計画はカバレッジ妥当性の議論と保守的な信頼度ステートメントで締めくくられます。
## なぜ
分散システムおよびステートフルシステムのテストのデフォルト——統合テストをいくつか書いて完了とする——では、本番環境で実際にこれらのシステムを壊すバグのごく一部しか発見できません。部分的なネットワーク分断、非決定的な並行性、クラッシュリカバリ、アップグレード/ロールバック、リプレイ時の冪等性、タイミングに敏感な順序性などです。
これらのスキルは、この分野で苦労して得られた知見を活かした、信念に基づいたワークフローを強制します。
- **テスト駆動ではなくクレーム駆動。** 製品が約束することから始めます。すべてのシナリオは、1つの障害の下で1つのクレームを反証します。クレームにちなんで命名されたテストは、セットアップにちなんで命名されたテストよりも弱体化させにくいのです。
- **カバレッジ妥当性は成果物です。** 計画は、選択したシナリオがリリースに*十分*であるという議論と、未検証のまま残るものの正直なリストで締めくくられます。
- **SUT自身の道具箱を再利用します。** 実行スキルは、新しいものを発明する前に、既存のテスト、ランクブック、およびフォールトインジェクションの足場を発見します。
- **カオスだけではなく、モデル+履歴+チェッカー。** 安全性、永続性、冪等性、分離性、順序性、またはメンバーシップのクレームに対して、すべてのシナリオは抽象モデル、操作履歴スキーマ、名前付きチェッカー（線形化可能性、直列化可能性、セッション一貫性、no-lost-ack、exactly-once、…）、および曖昧な結果（タイムアウト、不明なコミット、リトライ）の扱い方を宣言します。カオス単独ではなく、カオス+モデル+チェッカーです。
- **暗黙のパスはありません。** すべてのPASSは、オラクル実行証拠*および*障害が実際に発生したことを証明するシグナルを引用します。判定は10状態セットから得られるため、「カオススクリプトが正常に実行された」ことを「クレームが障害を生き延びた」と読むことはできません。すべてのFAILにはSUT/ハーネス/チェッカー/環境の責務タグが付き、再現担当者が適切なキューに届くようになっています。
## 得られるもの
エンドツーエンドで、2つのスキルは以下を生成します：
```
docs/testing-plans/<slug>.md ← plan with §0–§9 (see below)
test-sessions/<slug>/<UTC>/
├── session-log.md ← timeline + toolbox + env probe
├── logs/ ← per-scenario stdout/stderr
├── metrics/ ← metric snapshots
├── artifacts/ ← ephemeral harnesses, dumps
└── findings/
├── <scenario>.md ← per-scenario verdict (written as run proceeds)
└── report.md ← summary + adequacy + confidence delta
```
計画の構造（レビュー担当者はこれを読めば、テストを再実行せずにリリース可否を判断できます）：
```
0. Architectural summary — system as it actually exists
1. Scope
1b. Claims under test — the spine
1c. Missing claims discovered — docs ↔ code drift
2. SUT model
3. Existing test inventory — what's already covered
4. Failure-mode hypotheses — tied to claim IDs
5. Coverage matrix — claim × hypothesis
6. Technique selection — from the catalog
6b. Environment requirements
7. Scenarios — each named after the claim, with
Target test file + Skeleton
7.M Model / history / — mandatory when the scenario falsifies
checker discipline a claim in {safety, durability,
idempotency, isolation, ordering,
membership}: model under test,
operation-history schema, named
checker, nemesis + landing evidence,
ambiguous-outcome handling, reduction
plan (SUT/harness/checker/env blame)
7b. Coverage adequacy argument — why these tests are enough
7c. Residual uncertainty — what stays unverified, and why ok
7d. Confidence statement — the reviewer's verdict
8. What this plan does NOT cover
9. Open questions / followups
```
### §7.Mブロックの例（計画からの抜粋）
```
### Scenario S3: linearizable_append_under_partition
- Falsifies if it FAILs: C1 (every acknowledged append is durable
and linearisable), C5 (leader election completes within 5s)
- Workload: 8 clients, 70% append / 30% read, 5min, key-skew zipf
- Faults: asymmetric partition isolating current leader at T+60s
for 30s
- Oracle: linearizability via Porcupine over per-key histories
§7.M (model / history / checker discipline)
- Model under test: log
- Operation history: default 11-field schema (op id, process id,
invoke/complete ts, op type, key, input,
output, error, timeout marker, node seen,
fault epoch). Recorded in-process + server-
side audit.
- Checker: linearizability (Porcupine) per-key, then
no-lost-ack against final state
- Nemesis + landing: asymmetric-partition (iptables drop one
direction). Landing evidence = iptables drop
counter goes 0 → 14,712 over the 30s window
AND raft log emits "leader-lost; starting
election" within 2s of injection.
- Ambiguous outcomes: timeouts → timeout_marker=true, complete_ts
=null, treated as could-have-succeeded;
retries are separate ops sharing input
- Reduction plan: if FAIL, bisect fault window + fix seed, then
classify SUT / harness / checker / environment
per references/test-case-reduction.md
```
### 調査レポート行の例
| ID | 判定 | ネメシスの着地証拠 | 削減クラス |
|----|---------------------|-------------------------------------------------------|-----------------|
| 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 |
（完全な調査結果テンプレートには、Oracle、Oracle実行証拠、成果物リンク、計画との妥当性比較セクション、および信頼度デルタが含まれます — `skills/executing-distributed-system-tests/assets/findings-report-template.md` を参照してください。）
## インストール（1行、任意のエージェント）
これを任意のAIコーディングエージェント（Claude Code、Codex、Copilot CLI、Cursor、Gemini、またはMarkdownを読み取ってシェルを実行するその他のツール）に貼り付けます：
```
Read https://raw.githubusercontent.com/shenli/distributed-system-testing/main/INSTALL.md
and follow the instructions to install and configure
distributed-testing-skills for this agent.
```
エージェントは[`INSTALL.md`](https://github.com/shenli/distributed-system-testing/blob/main/INSTALL.md)を取得し、リポジトリを`~/.local/share/distributed-testing-skills/`にクローンして、スキルを組み込みます（Claude Codeでは`~/.claude/skills/`配下にシンボリックリンク、その他のエージェントでは`~/AGENTS.md`内のポインターブロック）。
その後、マシン上の任意のエージェントに「このシステムのテスト計画を設計して」または「Xで計画を実行して」と依頼すると、SKILL.mdのワークフローに従います。
### 更新
**同じ1行を再度貼り付けます。** `INSTALL.md`は冪等です。インストールパスが存在すれば`git pull --ff-only`を実行し、存在しなければ`git clone`を実行します。シンボリックリンクは常にクローンされたコンテンツを指すため、新しいバージョンを自動的に取り込みます。`~/AGENTS.md`のポインターブロックはHTMLマーカーを使用しており、実行のたびに重複なくきれいに置き換えられます。
クローンしたスキルにローカルでの編集がある場合、`git pull --ff-only`は失敗します。エージェントは破棄する前に停止して確認を求めます。
### 手動インストール（何が起きているかを確認したい場合）
```bash
git clone https://github.com/shenli/distributed-system-testing.git \
~/.local/share/distributed-testing-skills
# Claude Code: symlink under ~/.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 / others: see INSTALL.md
```
### Claude Codeプラグインとして（代替手段）
リポジトリには`.claude-plugin/`配下にプラグインマニフェストとマーケットプレイスマニフェストが含まれているため、Claude Codeはシンボリックリンクの代わりにプラグインとしてインストールできます：
```
/plugin marketplace add shenli/distributed-system-testing
/plugin install distributed-testing-skills@distributed-testing-skills
```
両方のスキルは`skills/`から自動検出されます。上記の1行`INSTALL.md`フローは、エージェント非依存の経路（Codex、Copilot CLI、Cursor、Gemini）として残ります。
## 使い方
スキルがインストールされると、2つの方法でこれらを駆動できます：
**カジュアルな依頼（自動トリガー付きClaude Code）：**
```
Design a project-wide test plan for this codebase.
```
```
Execute the plan at ./testing-plans/<slug>.md against this codebase.
```
スキルの説明は、「テスト計画を設計」「計画を実行」「安定性テストを実行」「リリース検証計画を設計」などの自然な表現を拾い上げます。
特定のモード、出力パス、または自動トリガーではないエージェントの場合、[`USAGE.md`](https://github.com/shenli/distributed-system-testing/blob/main/USAGE.md)にはすべてのワークフロー（設計と実行、それぞれのモード）用のコピー&ペーストプロンプトに加えて、スコープ、環境プロービング、長時間実行のチェックポイントに関するヒントがあります。
## 2つのスキル
### `designing-distributed-system-tests`
リポジトリを調査し、製品が行うクレームを抽出し、そのクレームに紐づく仮説を生成し、カタログから手法を選び、カバレッジ妥当性の議論と信頼度ステートメントを備えた構造化Markdown計画を作成します。一貫性が重要なシナリオでは、計画はシナリオごとに§7.Mブロックを埋めます：テスト対象モデル、操作履歴スキーマ、名前付きチェッカー、ネメシス+着地証拠、曖昧な結果の扱い、削減計画。詳細：[`history-discipline.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/history-discipline.md)。
2つのモード：**変更スコープ**（特定のコミットまたはPR）と**プロジェクト全体**（既存テストの棚卸しとギャップ分析を伴う全体計画）。
### `executing-distributed-system-tests`
計画を読み、SUTの道具箱を発見し、環境をプローブし、チェックポイント規律でシナリオを実行します。シナリオごとに：障害の着地証拠を取得し、green-but-broken監査とweak-oracle監査を実行し、[`verdict-taxonomy.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/executing-distributed-system-tests/references/verdict-taxonomy.md)の10状態分類法から判定を割り当て、報告前にすべてのFAILをSUT/ハーネス/チェッカー/環境に分類します。計画との妥当性比較評価と信頼度デルタを備えた調査レポートを生成します。
2つのモード：**デフォルト**（SUTに対して読み取り専用、セッションディレクトリ配下の一時的なハーネス）と**オーサーモード**（計画の§7で宣言されたシナリオスケルトンをレビュー用にSUTに書き込みます）。
## 手法カタログ
この分野の文献から抽出された8つのリファレンスファイル：
| ファイル | どのようなときに使うか |
|---|---|
| [`catalog-index.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/catalog-index.md) | セレクターページ — ここから始める |
| [`jepsen-and-elle.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/jepsen-and-elle.md) | 障害下での線形化可能性/直列化可能性 |
| [`deterministic-simulation.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/deterministic-simulation.md) | シードから再現可能なバグ; 非同期処理の多いコード |
| [`chaos-and-fault-injection.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/chaos-and-fault-injection.md) | 実クラスターでの部分/非対称障害 |
| [`fuzzing.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/fuzzing.md) | サニタイザー下での入力または並行性ファジング |
| [`formal-methods-tla.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/formal-methods-tla.md) | 設計時におけるプロトコル正当性 |
| [`property-and-metamorphic.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/property-and-metamorphic.md) | 代数則/メタモルフィック関係テスト |
| [`performance-and-benchmarking.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/performance-and-benchmarking.md) | テールレイテンシ/スループット/公平性 |
| [`crash-recovery-and-upgrade.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/crash-recovery-and-upgrade.md) | 永続性、リプレイ、冪等性、バージョン混在 |
それぞれ同じ構成です：どのようなときに使うか、何をうまく検出するか、何を見逃すか、具体的なツール、論文、コストシグナル、計画チェックリスト。カタログインデックスは症状とリファレンスを対応付けます。
## リポジトリ構成
```
.
├── .claude-plugin/ ← plugin + marketplace manifests
├── README.md ← this file
├── INSTALL.md ← idempotent install / update (paste-this)
├── USAGE.md ← copy/paste prompts for every workflow
├── LICENSE
├── skills/
│ ├── designing-distributed-system-tests/
│ │ ├── SKILL.md ← the design workflow
│ │ ├── assets/plan-template.md ← §0–§9 incl. gated §7.M
│ │ └── references/ ← 8-file technique catalog + index,
│ │ common-distributed-systems-pitfalls,
│ │ history-discipline,
│ │ boundary-and-isolation-testing
│ └── executing-distributed-system-tests/
│ ├── SKILL.md ← the execute workflow
│ ├── assets/
│ │ ├── session-log-template.md
│ │ └── findings-report-template.md ← 10-state verdicts + landing evidence
│ └── references/ ← oracle-patterns (checker picker + 14
│ patterns), fault-injection-howto
│ (22-row nemesis taxonomy),
│ test-case-reduction (with blame
│ classification), green-but-broken-
│ red-flags (incl. weak-oracle audit),
│ finding-classification (TaxDC),
│ verdict-taxonomy (10-state)
├── evals/ ← manual regression prompts (see evals/README.md)
├── verification/ ← real local runs (gitignored — not in the repo)
└── specs/ ← original design spec (historical snapshot)
```
## ステータス
初期段階ですが、実践済みです。両方のスキルはAgentDB（Rust製の分散エージェントランタイム）に対してエンドツーエンドで複数回駆動され、6件の調査結果を表面化させました（P0候補1件は現在クローズ、P1が2件PRとしてリリースされ、2件はオープン）。スキル本体はハーネスの経験が蓄積されるにつれて進化します。今後数回のイテレーションでSKILL.mdとテンプレートに軽微な更新が入る見込みです。
それらの実行による実際の計画出力、セッションディレクトリ、調査レポートはローカルの`verification/`配下に保持されます（実行ごとに1つのサブディレクトリ）。このディレクトリは**gitignored**です。生の成果物は大きくマシン固有であるため、このリポジトリの一部ではありません。これまでの実行には、AgentDBコミット`fab7d9d`に対する変更スコープの計画+実行（永続的な冪等アペンドリプレイ; 8つの障害モードカテゴリすべてにわたる16の仮説を含む670行の計画）、線形化可能性チェックを伴う一貫性+クラッシュリカバリ実行、完全なカバレッジマトリックスを備えたプロジェクト全体の計画、およびLMCacheに対するクロスサーバー多層実行が含まれます。
[`evals/`](https://github.com/shenli/distributed-system-testing/blob/main/evals)ディレクトリには、イテレーション間のSKILL.md本体への動作変更を健全性チェックするための手動回帰プロンプト（設計スキルと実行スキル用の個別の`evals.json`）が保持されています。これらは作者のローカルSUTチェックアウトを参照するため、自動スイートではなく手動で再実行するプロンプトです — [`evals/README.md`](https://github.com/shenli/distributed-system-testing/blob/main/evals/README.md)を参照してください。
## 謝辞
手法カタログは、Andrey Satarinの包括的な[testing-distributed-systems](https://github.com/asatarin/testing-distributed-systems)カタログから抽出されました。カタログの基盤となる重要な論文は以下のとおりです：
- 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.
