Навыки тестирования распределённых систем

Два навыка для ИИ-агентов, которые пишут код и занимаются тестированием распределённых и 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

Пример строки отчёта о результатах

(Полный шаблон отчёта о результатах содержит 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, клонирует репозиторий в ~/.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 завершится ошибкой; агент остановится и спросит, прежде чем удалить их.

Установка вручную (если хотите видеть, что происходит)

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 есть готовые к копированию промпты для каждого процесса (design и execute в соответствующих режимах), а также советы по охвату, исследованию окружения и чекпоинтам при долгих прогонах.

Два навыка

designing-distributed-system-tests

Обходит репозиторий, извлекает утверждения, которые делает продукт, генерирует гипотезы, привязанные к этим утверждениям, выбирает техники из каталога и пишет структурированный Markdown-план с обоснованием достаточности покрытия и оценкой уверенности. Для критичных к согласованности сценариев план заполняет блок §7.M для каждого сценария: модель под тестом, схема истории операций, именованный checker, nemesis + доказательства срабатывания, обработка неоднозначных исходов, план редукции. Подробности: history-discipline.md.

Два режима: change-scoped (для конкретного коммита или PR) и project-wide (целостный план с инвентаризацией существующих тестов и анализом пробелов).

executing-distributed-system-tests

Читает план, обнаруживает инструментарий SUT, исследует окружение и запускает сценарии с дисциплиной чекпоинтов. Для каждого сценария: фиксирует доказательства срабатывания сбоя, проводит аудиты «green-but-broken» и «weak-oracle», присваивает вердикт из 10-состояниевой таксономии в verdict-taxonomy.md и классифицирует каждый FAIL на SUT / harness / checker / environment перед отправкой. Формирует отчёт о результатах с оценкой «достаточность vs план» и дельтой уверенности.

Два режима: default (read-only по отношению к SUT, временные harness-ы в каталоге сессии) и author mode (записывает в SUT каркасы сценариев, объявленные в §7 плана, для ревью).

Каталог техник

Восемь справочных файлов, дистиллированных из литературы по теме:

Каждый устроен одинаково: когда обращаться, что хорошо обнаруживает, что пропускает, конкретные инструменты, статьи, сигнал стоимости, чек-лист для плана. Индекс каталога сопоставляет симптомы со справочниками.

Структура репозитория

.
├── .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/ лежат ручные регрессионные промпты (отдельные evals.json для навыков design и execute), используемые для проверки поведенческих изменений в телах SKILL.md между итерациями. Они ссылаются на локальные чекауты SUT автора, так что это промпты для ручного перезапуска, а не автоматический набор — см. evals/README.md.

Благодарности

Каталог техник дистиллирован из обширного каталога Andrey Satarin 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.