Habilidades de Teste de Sistemas Distribuídos

Duas habilidades para agentes de codificação com IA que projetam e executam testes orientados a afirmações para sistemas distribuídos e com estado. Juntas, elas produzem um plano de teste estruturado em Markdown e um relatório de descobertas com veredictos de 10 estados e uma classificação explícita de culpa entre SUT / harness / checker / ambiente. Um revisor lê os dois artefatos e decide se deve fazer o deploy; nada mais precisa ser reexecutado.

Funciona com Claude Code, Codex, Copilot CLI, Cursor, Gemini ou qualquer agente que leia Markdown e execute shell. As habilidades são arquivos SKILL.md simples. O agente os executa; o plano e o relatório de descobertas são a saída.

Uma habilidade projeta o plano. A outra o executa. Um plano parte das afirmações do produto, gera hipóteses vinculadas a essas afirmações e escreve cenários nomeados de acordo com a afirmação que cada um tenta falsificar. Para cenários críticos para consistência, cada cenário também vincula um modelo abstrato (register | queue | log | lock | lease | ledger | …) a um esquema de histórico de operações, um checker nomeado e um nemesis com evidência observável de ativação. O plano termina com um argumento de adequação de cobertura e uma declaração de confiança conservadora.

Por quê

O padrão para testar sistemas distribuídos e com estado — escrever alguns testes de integração e considerar concluído — encontra uma pequena fração dos bugs que realmente quebram esses sistemas em produção: partições parciais de rede, concorrência não determinística, recuperação de falhas, atualização/rollback, idempotência sob repetição, ordenação sensível a tempo.

Essas habilidades impõem um fluxo de trabalho opinativo que se baseia no conhecimento duramente conquistado da área:

• Orientado a afirmações, não a testes. Comece pelo que o produto promete. Cada cenário falsifica uma afirmação sob uma falha. Um teste nomeado de acordo com sua afirmação é mais difícil de enfraquecer do que um nomeado de acordo com sua configuração.
• A adequação da cobertura é um entregável. O plano termina com um argumento de que os cenários escolhidos são suficientes para o deploy, além de uma lista honesta do que permanece não verificado.
• Reutilize a própria caixa de ferramentas do SUT. A habilidade de execução descobre testes existentes, runbooks e andaimes de injeção de falhas antes de inventar qualquer coisa nova.
• Modelo + histórico + checker, não apenas caos. Para afirmações de segurança, durabilidade, idempotência, isolamento, ordenação ou associação, cada cenário declara um modelo abstrato, um esquema de histórico de operações, um checker nomeado (linearizabilidade, serializabilidade, consistência de sessão, sem confirmação perdida, exatamente uma vez, …) e como ele trata resultados ambíguos (timeouts, commits desconhecidos, repetições). Caos mais um modelo e um checker, não caos sozinho.
• Sem aprovações silenciosas. Todo PASS cita evidência de execução do oráculo e o sinal que prova que a falha realmente disparou. Os veredictos vêm de um conjunto de 10 estados, então "o script de caos rodou sem erros" não pode ser interpretado como "a afirmação sobreviveu à falha". Todo FAIL carrega uma etiqueta de culpa SUT / harness / checker / ambiente para que os reprodutores cheguem à fila correta.

O que você obtém

De ponta a ponta, as duas habilidades produzem:

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

A estrutura do plano (um revisor pode ler isto e decidir se aprova sem voltar a executar os testes):

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

Exemplo de bloco §7.M (excerto de um plano)

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

Exemplo de linha do relatório de achados

ID	Veredito	Evidência de landing do Nemesis	Classe de redução
S3	PASS-hardening	iptables ctr 0→14,712; reeleição de raft em T+1.8s	n/a
S4	FAIL-reproducible	partição aplicada; Elle: anomalia G2-item na chave K17	SUT
S7	INCONCLUSIVE-fault-not-proven	regra iptables instalada mas o contador permaneceu 0 — cadeia errada	harness
S9	PARTIAL-model	landing ok; checker cobriu por chave, não entre chaves	n/a