Habilidades para pruebas de sistemas distribuidos

Dos habilidades para agentes de codificación de IA que diseñan y ejecutan pruebas impulsadas por afirmaciones para sistemas distribuidos y con estado. Juntas producen un plan de pruebas Markdown estructurado y un informe de hallazgos con veredictos de 10 estados y una clasificación explícita de responsabilidad SUT / harness / checker / entorno. Un revisor lee los dos artefactos y decide si se publica; no es necesario volver a ejecutar nada más.

Funciona con Claude Code, Codex, Copilot CLI, Cursor, Gemini o cualquier agente que lea Markdown y ejecute shell. Las habilidades son simples archivos SKILL.md. El agente las ejecuta; el plan y el informe de hallazgos son el resultado.

Una habilidad diseña el plan. La otra lo ejecuta. Un plan parte de las afirmaciones del producto, genera hipótesis vinculadas a esas afirmaciones y escribe escenarios con el nombre de la afirmación que cada uno intenta refutar. Para escenarios críticos de consistencia, cada escenario también vincula un modelo abstracto (register | queue | log | lock | lease | ledger | …) a un esquema de historial de operaciones, un checker con nombre y un nemesis con evidencia observable de materialización del fallo. El plan termina con un argumento de adecuación de la cobertura y una declaración de confianza conservadora.

Por qué

La práctica habitual para probar sistemas distribuidos y con estado — escribir unas pocas pruebas de integración y darlo por terminado — encuentra una pequeña fracción de los errores que realmente rompen estos sistemas en producción: particiones de red parciales, concurrencia no determinista, recuperación de caídas, actualización/reversión, idempotencia bajo reproducción, ordenación sensible a tiempos.

Estas habilidades imponen un flujo de trabajo con criterio propio que aprovecha el conocimiento ganado con esfuerzo en este campo:

• Impulsado por las afirmaciones, no por los tests. Se parte de lo que promete el producto. Cada escenario refuta una afirmación bajo un fallo. Un test nombrado por su afirmación es más difícil de debilitar que uno nombrado por su preparación.
• La adecuación de la cobertura es un entregable. El plan termina con un argumento de que los escenarios elegidos son suficientes para publicar, más una lista honesta de lo que permanece sin verificar.
• Reutiliza el propio arsenal del SUT. La habilidad de ejecución descubre tests existentes, runbooks y andamiajes de inyección de fallos antes de inventar nada nuevo.
• Modelo + historial + checker, no solo caos. Para afirmaciones de seguridad, durabilidad, idempotencia, aislamiento, orden o membresía, cada escenario declara un modelo abstracto, un esquema de historial de operaciones, un checker con nombre (linearizabilidad, serializabilidad, consistencia de sesión, no-lost-ack, exactly-once, …) y cómo trata los resultados ambiguos (timeouts, commits desconocidos, reintentos). Caos más un modelo y un checker, no solo caos.
• Sin pases silenciosos. Cada PASS cita evidencia de ejecución del oráculo y la señal que demuestra que el fallo realmente se disparó. Los veredictos provienen de un conjunto de 10 estados, de modo que "el script de caos se ejecutó sin problemas" no puede interpretarse como "la afirmación sobrevivió al fallo". Cada FAIL lleva una etiqueta de responsabilidad SUT / harness / checker / entorno para que quienes reproducen el fallo lleguen a la cola correcta.

Lo que obtienes

De extremo a extremo, las dos habilidades producen:

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

La estructura del plan (un revisor puede leer esto y decidir si publicar sin volver a ejecutar los tests):

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

Ejemplo de bloque §7.M (extracto de un plan)

### 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

Ejemplo de fila de informe de hallazgos

(La plantilla completa de hallazgos incluye Oracle, evidencia de ejecución de Oracle, enlaces a artefactos, una sección de adecuación frente al plan y un delta de confianza — consulta skills/executing-distributed-system-tests/assets/findings-report-template.md.)

Instalación (una línea, cualquier agente)

Pega esto en cualquier agente de codificación de IA (Claude Code, Codex, Copilot CLI, Cursor, Gemini o cualquier otra cosa que lea Markdown y ejecute 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.

El agente obtiene INSTALL.md, clona el repositorio en ~/.local/share/distributed-testing-skills/ y conecta las habilidades (enlaces simbólicos en ~/.claude/skills/ para Claude Code, un bloque de puntero en ~/AGENTS.md para otros agentes).

Después, pide a cualquier agente de la máquina que "diseñe un plan de pruebas para este sistema" o "ejecute el plan en X" y seguirá el flujo de trabajo de SKILL.md.

Actualización

Pega la misma línea de nuevo. INSTALL.md es idempotente: si la ruta de instalación existe, hace git pull --ff-only; si no, hace git clone. Los enlaces simbólicos siempre apuntan al contenido clonado, por lo que recogen la nueva versión automáticamente. El bloque de puntero ~/AGENTS.md usa marcadores HTML y se reemplaza limpiamente en cada ejecución, sin duplicaciones.

Si tienes ediciones locales en las habilidades clonadas, git pull --ff-only fallará; el agente se detendrá y preguntará antes de descartarlas.

Instalación manual (si prefieres ver lo que está pasando)

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

Como plugin de Claude Code (alternativa)

El repositorio contiene un manifiesto de plugin y un manifiesto de marketplace en .claude-plugin/, de modo que Claude Code puede instalarlo como plugin en lugar de usar enlaces simbólicos:

/plugin marketplace add shenli/distributed-system-testing
/plugin install distributed-testing-skills@distributed-testing-skills

Ambas habilidades se detectan automáticamente desde skills/. El flujo de una línea INSTALL.md de arriba sigue siendo la vía independiente del agente (Codex, Copilot CLI, Cursor, Gemini).

Uso

Una vez instaladas las habilidades, tienes dos formas de manejarlas:

Petición informal (Claude Code con activación automática):

Design a project-wide test plan for this codebase.

Execute the plan at ./testing-plans/<slug>.md against this codebase.

Las descripciones de las habilidades captan frases naturales como "design a test plan", "execute the plan", "run stability tests", "design a release validation plan", etc.

Para un modo específico, una ruta de salida o un agente sin activación automática, USAGE.md tiene indicaciones de copiar y pegar para cada flujo de trabajo (diseño y ejecución, en sus respectivos modos), además de consejos sobre alcance, sondeo del entorno y puntos de control en ejecuciones largas.

Las dos habilidades

designing-distributed-system-tests

Recorre el repositorio, extrae las afirmaciones que hace el producto, genera hipótesis vinculadas a esas afirmaciones, elige técnicas del catálogo y escribe un plan Markdown estructurado con un argumento de adecuación de la cobertura y una declaración de confianza. Para escenarios críticos de consistencia, el plan rellena un bloque §7.M por escenario: modelo bajo prueba, esquema de historial de operaciones, checker con nombre, nemesis + evidencia de materialización, manejo de resultados ambiguos, plan de reducción. Detalles: history-discipline.md.

Dos modos: de alcance de cambio (un commit o PR específico) y de proyecto completo (un plan holístico con inventario de tests existentes y análisis de brechas).

executing-distributed-system-tests

Lee el plan, descubre el arsenal del SUT, sondea el entorno y ejecuta escenarios con disciplina de puntos de control. Por escenario: captura la evidencia de materialización del fallo, ejecuta las auditorías de "verde pero roto" y de oráculo débil, asigna un veredicto de la taxonomía de 10 estados en verdict-taxonomy.md y clasifica cada FAIL en SUT / harness / checker / entorno antes de registrarlo. Produce un informe de hallazgos con evaluación de adecuación frente al plan y delta de confianza.

Dos modos: por defecto (solo lectura sobre el SUT, harness efímeros bajo el directorio de sesión) y modo autor (escribe en el SUT los esqueletos de escenario declarados en el §7 del plan para su revisión).

Catálogo de técnicas

Ocho archivos de referencia destilados de la literatura del campo:

Cada uno sigue la misma forma: cuándo recurrir a él, qué detecta bien, qué se le escapa, herramientas concretas, artículos, señal de coste, lista de verificación del plan. El índice del catálogo empareja síntomas con referencias.

Estructura del repositorio

.
├── .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)

Estado

Temprano pero ya ejercitado. Ambas habilidades se han ejecutado de extremo a extremo contra AgentDB (un runtime de agentes distribuidos en Rust) varias veces, sacando a la luz seis hallazgos (un candidato a P0 ya cerrado, dos P1 enviados como PR, dos abiertos). Los cuerpos de las habilidades evolucionan a medida que se acumula experiencia con los harness; espera actualizaciones menores de los SKILL.mds y las plantillas en las próximas iteraciones.

Los planes de salida reales, los directorios de sesión y los informes de hallazgos de esas ejecuciones se guardan localmente en verification/ (un subdirectorio por ejecución). Ese directorio está gitignored (excluido por git): los artefactos brutos son grandes y específicos de la máquina, por lo que no forman parte de este repositorio. Las ejecuciones hasta la fecha incluyen un plan de alcance de cambio + ejecución para el commit fab7d9d de AgentDB (reproducción de anexos idempotentes y duraderos; un plan de 670 líneas con 16 hipótesis en las ocho categorías de modos de fallo), ejecuciones de consistencia + recuperación de caídas con verificación de linearizabilidad, planes de proyecto completo con una matriz de cobertura completa y una ejecución entre servidores de varios niveles contra LMCache.

El directorio evals/ contiene indicaciones de regresión manuales (evals.json separados para las habilidades de diseño y ejecución) que se usan para comprobar los cambios de comportamiento en los cuerpos de los SKILL.md entre iteraciones. Hacen referencia a los checkouts locales del SUT del autor, por lo que son indicaciones para volver a ejecutar a mano, no una suite automatizada — consulta evals/README.md.

Agradecimientos

El catálogo de técnicas se ha destilado del completo catálogo testing-distributed-systems de Andrey Satarin. Los artículos seminales que anclan el catálogo incluyen:

• 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)

Licencia

MIT.