shenli/distributed-system-testingНавыки ИИ-агентов для тестирования распределённых систем
# Навыки тестирования распределённых систем
**Два навыка для ИИ-агентов, которые пишут код и занимаются
тестированием распределённых и stateful-систем, управляемым
утверждениями продукта (claim-driven).** Вместе они создают
структурированный Markdown-план тестов и отчёт о результатах с
вердиктами из 10 состояний и явной классификацией вины
SUT / harness / checker / environment. Ревьюер читает два артефакта
и решает, можно ли выпускать; ничего больше перезапускать не нужно.
Работает с Claude Code, Codex, Copilot CLI, Cursor, Gemini или любым
агентом, который читает Markdown и выполняет команды shell. Навыки
представляют собой обычные файлы SKILL.md. Агент выполняет их;
результатом являются план и отчёт о результатах.
Один навык проектирует план. Другой — выполняет его. План
начинается с утверждений, которые делает продукт, генерирует
гипотезы, привязанные к этим утверждениям, и описывает сценарии,
названные по утверждению, которое каждый из них пытается
опровергнуть. Для критичных к согласованности сценариев каждый
сценарий также привязывает абстрактную модель
(`register | queue | log | lock | lease | ledger | …`) к схеме
истории операций, именованному checker-у и немезису с наблюдаемыми
доказательствами срабатывания. План завершается обоснованием
достаточности покрытия и консервативной оценкой уверенности.
## Зачем
Подход по умолчанию к тестированию распределённых и stateful-систем —
написать несколько интеграционных тестов и считать задачу
выполненной — находит лишь малую долю багов, которые реально ломают
такие системы в проде: частичные сетевые разделения,
недетерминированная конкурентность, восстановление после сбоя,
апгрейд/откат, идемпотентность при повторном воспроизведении,
чувствительная к таймингам упорядоченность.
Эти навыки навязывают осознанный (opinionated) процесс, опирающийся
на нелёгкий опыт индустрии:
- **Управляемость утверждениями, а не тестами.** Исходите из того,
что обещает продукт. Каждый сценарий опровергает одно утверждение
при одном сбое. Тест, названный по своему утверждению, труднее
ослабить, чем тест, названный по своему окружению.
- **Достаточность покрытия — это измеримый результат.** План
завершается обоснованием того, что выбранных сценариев *достаточно*
для выпуска, плюс честным списком того, что остаётся непроверенным.
- **Используйте собственный инструментарий SUT.** Навык выполнения
сначала находит существующие тесты, runbook-и и каркасы для
инъекции сбоев, прежде чем изобретать что-то новое.
- **Модель + история + checker, а не просто хаос.** Для утверждений
о безопасности, долговечности, идемпотентности, изоляции,
упорядоченности или членстве каждый сценарий объявляет абстрактную
модель, схему истории операций, именованный checker
(линеаризуемость, сериализуемость, session-consistency, no-lost-ack,
exactly-once, …) и то, как трактуются неоднозначные исходы
(таймауты, неизвестные коммиты, ретраи). Хаос плюс модель и
checker, а не только хаос.
- **Никаких молчаливых PASS.** Каждый PASS ссылается на
доказательства выполнения оракула *и* на сигнал, подтверждающий,
что сбой действительно сработал. Вердикты берутся из набора из
10 состояний, так что «скрипт хаоса отработал чисто» нельзя
прочитать как «утверждение пережило сбой». Каждый FAIL несёт
метку вины SUT / harness / checker / environment, чтобы
воспроизводители попадали в нужную очередь.
## Что вы получаете
End-to-end два навыка создают:
```
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, доказательства
выполнения оракула, ссылки на артефакты, раздел «достаточность vs
план» и дельту уверенности — см.
`skills/executing-distributed-system-tests/assets/findings-report-template.md`.)
## Установка (одна строка, любой агент)
Вставьте это любому ИИ-агенту для программирования (Claude Code,
Codex, Copilot CLI, Cursor, Gemini или чему угодно ещё, что читает
Markdown и выполняет shell):
```
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/skills/` для Claude Code, блок-указатель в
`~/AGENTS.md` для остальных агентов).
После этого попросите любого агента на машине «разработай тест-план
для этой системы» или «выполни план из X» — и он выполнит процесс из
SKILL.md.
### Обновление
**Вставьте ту же однострочную команду ещё раз.** `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/`. Однострочный
процесс через `INSTALL.md` выше остаётся универсальным путём для
любых агентов (Codex, Copilot CLI, Cursor, Gemini).
## Использование
После установки навыков у вас есть два способа ими управлять:
**Неформальный запрос (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) есть готовые к копированию промпты для каждого
процесса (design и execute в соответствующих режимах), а также советы
по охвату, исследованию окружения и чекпоинтам при долгих прогонах.
## Два навыка
### `designing-distributed-system-tests`
Обходит репозиторий, извлекает утверждения, которые делает продукт,
генерирует гипотезы, привязанные к этим утверждениям, выбирает техники
из каталога и пишет структурированный Markdown-план с обоснованием
достаточности покрытия и оценкой уверенности. Для критичных к
согласованности сценариев план заполняет блок §7.M для каждого
сценария: модель под тестом, схема истории операций, именованный
checker, nemesis + доказательства срабатывания, обработка
неоднозначных исходов, план редукции. Подробности:
[`history-discipline.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/designing-distributed-system-tests/references/history-discipline.md).
Два режима: **change-scoped** (для конкретного коммита или PR) и
**project-wide** (целостный план с инвентаризацией существующих тестов
и анализом пробелов).
### `executing-distributed-system-tests`
Читает план, обнаруживает инструментарий SUT, исследует окружение и
запускает сценарии с дисциплиной чекпоинтов. Для каждого сценария:
фиксирует доказательства срабатывания сбоя, проводит аудиты
«green-but-broken» и «weak-oracle», присваивает вердикт из
10-состояниевой таксономии в
[`verdict-taxonomy.md`](https://github.com/shenli/distributed-system-testing/blob/main/skills/executing-distributed-system-tests/references/verdict-taxonomy.md)
и классифицирует каждый FAIL на SUT / harness / checker / environment
перед отправкой. Формирует отчёт о результатах с оценкой
«достаточность vs план» и дельтой уверенности.
Два режима: **default** (read-only по отношению к SUT, временные
harness-ы в каталоге сессии) и **author mode** (записывает в SUT
каркасы сценариев, объявленные в §7 плана, для ревью).
## Каталог техник
Восемь справочных файлов, дистиллированных из литературы по теме:
| Файл | Когда обращаться |
|---|---|
| [`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)
```
## Статус
Ранний, но уже опробованный. Оба навыка многократно прогонялись
end-to-end против AgentDB (распределённая агентная среда выполнения
на Rust), выявив шесть дефектов (один кандидат в P0 сейчас закрыт,
две P1 ушли PR-ом, два открыты). Тела навыков развиваются по мере
накопления опыта с harness-ами; в ближайших итерациях ожидайте
небольших обновлений SKILL.md и шаблонов.
Реальные планы, каталоги сессий и отчёты о результатах этих прогонов
хранятся локально в `verification/` (по одной поддиректории на прогон).
Этот каталог **в gitignore** — сырые артефакты большие и зависят от
машины, поэтому их нет в репозитории. Среди прогонов на сегодня: план
и выполнение в режиме change-scoped для коммита `fab7d9d` AgentDB
(долговечный идемпотентный повтор append; план на 670 строк с 16
гипотезами по всем восьми категориям режимов отказа), прогоны
согласованности и восстановления после сбоев с проверкой
линеаризуемости, планы project-wide с полной матрицей покрытия и
межсерверный многоуровневый прогон против LMCache.
В каталоге [`evals/`](https://github.com/shenli/distributed-system-testing/blob/main/evals) лежат ручные регрессионные промпты
(отдельные `evals.json` для навыков design и execute), используемые
для проверки поведенческих изменений в телах SKILL.md между
итерациями. Они ссылаются на локальные чекауты 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.