분산 시스템 테스트 스킬

분산 및 상태 저장 시스템을 대상으로 클레임 기반 테스트를 설계·실행하는 AI 코딩 에이전트용 두 가지 스킬. 두 스킬은 함께 10가지 상태 판정과 명시적인 SUT / 하니스 / 체커 / 환경 책임 분류가 포함된 구조화된 Markdown 테스트 계획과 발견 보고서를 생성한다. 리뷰어는 두 산출물을 읽고 출시 여부를 결정한다. 그 외에 다시 실행할 것은 없다.

Claude Code, Codex, Copilot CLI, Cursor, Gemini 또는 Markdown을 읽고 셸을 실행하는 모든 에이전트에서 동작한다. 스킬은 단순한 SKILL.md 파일이다. 에이전트가 이를 실행하며, 계획과 발견 보고서가 출력물이다.

왜 필요한가

분산 및 상태 저장 시스템 테스트의 기본 방식 — 통합 테스트 몇 개를 작성하고 끝내는 것 — 은 실제 프로덕션에서 이 시스템을 망가뜨리는 버그의 극히 일부만 찾아낸다: 부분 네트워크 분할, 비결정적 동시성, 크래시 복구, 업그레이드/롤백, 리플레이 하에서의 멱등성, 타이밍에 민감한 순서.

이 스킬들은 현장의 값진 경험에서 얻은 지식을 활용하는 확고한 방식의 워크플로우를 강제한다:

클레임 기반, 테스트 기반이 아님. 제품이 약속하는 것에서 시작한다. 모든 시나리오는 하나의 장애 하에서 하나의 클레임을 반증한다. 클레임 이름을 딴 테스트는 셋업 이름을 딴 테스트보다 약화시키기 어렵다.
커버리지 적정성은 산출물이다. 계획은 선택한 시나리오가 출시하기에 충분하다는 논증과, 검증되지 않은 채 남는 것에 대한 정직한 목록으로 끝난다.
SUT 자체의 도구 상자를 재사용한다. 실행 스킬은 새로운 것을 발명하기 전에 기존 테스트, 런북, 장애 주입 스캐폴딩을 발견한다.
혼돈만이 아니라 모델 + 이력 + 체커. 안전성, 지속성, 멱등성, 격리, 순서, 멤버십 클레임의 경우 모든 시나리오는 추상 모델, 작업 이력 스키마, 명명된 체커(linearizability, serializability, session-consistency, no-lost-ack, exactly-once, …), 그리고 모호한 결과(타임아웃, 알 수 없는 커밋, 재시도)를 처리하는 방식을 선언한다. 혼돈 단독이 아니라 혼돈 + 모델 + 체커다.
조용한 통과 없음. 모든 PASS는 오라클 실행 증거 그리고 장애가 실제로 발생했음을 증명하는 신호를 인용한다. 판정은 10가지 상태 집합에서 나오므로, "혼돈 스크립트가 깨끗하게 실행되었다"는 "클레임이 장애에서 살아남았다"로 읽힐 수 없다. 모든 FAIL은 재현자가 올바른 큐에 도달할 수 있도록 SUT / 하니스 / 체커 / 환경 책임 태그를 갖는다.

얻을 수 있는 것

엔드투엔드로 두 스킬은 다음을 생성한다:

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, Oracle 실행 증거, 아티팩트 링크, 계획 대비 적정성 섹션, 신뢰도 델타를 포함한다 — skills/executing-distributed-system-tests/assets/findings-report-template.md 참조.)

설치(한 줄, 모든 에이전트)

이 한 줄을 아무 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를 가져와 저장소를 ~/.local/share/distributed-testing-skills/에 클론하고 스킬을 연결한다(Claude Code는 ~/.claude/skills/ 아래 심링크, 다른 에이전트는 ~/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에 모든 워크플로우(각각의 모드에서 설계 및 실행)를 위한 복사/붙여넣기 프롬프트와 범위, 환경 프로빙, 장기 실행 체크포인트에 대한 팁이 있다.

두 가지 스킬

`designing-distributed-system-tests`

저장소를 탐색하여 제품이 하는 클레임을 추출하고, 해당 클레임에 연결된 가설을 생성하며, 카탈로그에서 기법을 선택하고, 커버리지 적정성 논증과 신뢰도 진술이 포함된 구조화된 Markdown 계획을 작성한다. 일관성 중요 시나리오의 경우 계획은 시나리오별로 §7.M 블록을 채운다: 테스트 대상 모델, 작업 이력 스키마, 명명된 체커, 네미시스 + 착지 증거, 모호한 결과 처리, 축소 계획. 자세한 내용: history-discipline.md.

두 가지 모드: 변경 범위(특정 커밋 또는 PR)와 프로젝트 전체(기존 테스트 인벤토리와 갭 분석을 포함한 종합 계획).

`executing-distributed-system-tests`

계획을 읽고, SUT의 도구 상자를 발견하며, 환경을 프로빙하고, 체크포인트 규율로 시나리오를 실행한다. 시나리오별로: 장애에 대한 착지 증거를 수집하고, green-but-broken 및 weak-oracle 감사를 실행하며, verdict-taxonomy.md의 10가지 상태 분류에서 판정을 할당하고, 제출 전에 모든 FAIL을 SUT / 하니스 / 체커 / 환경으로 분류한다. 계획 대비 적정성 평가와 신뢰도 델타가 포함된 발견 보고서를 생성한다.

두 가지 모드: 기본(SUT에 대해 읽기 전용, 세션 디렉터리 아래 임시 하니스)과 작성자 모드(검토를 위해 계획의 §7에 선언된 시나리오 스켈레톤을 SUT에 작성).

기법 카탈로그

현장 문헌에서 정제된 8개의 참조 파일:

각 파일은 동일한 형식을 따른다: 언제 사용할지, 무엇을 잘 탐지하는지, 무엇을 놓치는지, 구체적인 도구, 논문, 비용 신호, 계획 체크리스트. 카탈로그 인덱스는 증상을 참조 파일과 짝지어 준다.

저장소 구조

.
├── .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/ 아래에 로컬로 보관된다(실행마다 하위 디렉터리 하나). 이 디렉터리는 gitignore 처리되어 있다 — 원본 아티팩트는 크고 머신별로 다르므로 이 저장소에 포함되지 않는다. 지금까지의 실행에는 AgentDB 커밋 fab7d9d에 대한 변경 범위 계획 + 실행(지속적·멱등적 append 리플레이; 8가지 장애 모드 범주 전체에 걸친 16개 가설이 있는 670줄 계획), 선형화 가능성 검사가 포함된 일관성 + 크래시 복구 실행, 전체 커버리지 매트릭스가 포함된 프로젝트 전체 계획, LMCache를 대상으로 한 서버 간 다중 계층 실행이 포함된다.

evals/ 디렉터리는 반복 사이에 SKILL.md 본문의 동작 변경을 검증하는 데 사용되는 수동 회귀 프롬프트(설계 및 실행 스킬 각각에 대한 별도의 evals.json)를 보관한다. 이 프롬프트는 작성자의 로컬 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.

S3	`PASS-hardening`	iptables ctr 0→14,712; T+1.8s에 raft 재선거	n/a
S4	`FAIL-reproducible`	분할 착지; Elle: key K17에서 G2-item anomaly	SUT
S7	`INCONCLUSIVE-fault-not-proven`	iptables 규칙은 설치됐지만 카운터가 0에 머물음 — 잘못된 체인	harness
S9	`PARTIAL-model`	착지 정상; 체커는 key별로만 적용, key 간 미적용	n/a

`catalog-index.md`	선택 페이지 — 여기서 시작
`jepsen-and-elle.md`	장애 하에서 선형화 가능성 / 직렬화 가능성
`deterministic-simulation.md`	시드에서 재현 가능한 버그; 비동기 부하가 큰 코드
`chaos-and-fault-injection.md`	실제 클러스터의 부분 / 비대칭 장애
`fuzzing.md`	새니타이저 하에서 입력 또는 동시성 퍼징
`formal-methods-tla.md`	설계 시점의 프로토콜 정확성 검증
`property-and-metamorphic.md`	대수 법칙 / 메타모픽 관계 테스트
`performance-and-benchmarking.md`	꼬리 지연 시간 / 처리량 / 공정성
`crash-recovery-and-upgrade.md`	지속성, 리플레이, 멱등성, 혼합 버전

distributed-system-testing

인기