shenli/distributed-system-testing분산 시스템 테스트를 위한 AI 에이전트 스킬
데이터를 저장하거나 여러 프로세스 또는 머신에 걸쳐 실행되는 시스템을 위해 AI 코딩 에이전트가 의미 있는 테스트를 설계하고, 실행하며, 결과를 설명하도록 돕는 두 가지 스킬입니다.
"저장이 성공하면 재시작 후에도 데이터가 남아 있다"와 같은 제품 약속에서 시작하여, 에이전트가 실행하고 확인할 수 있는 테스트로 전환하세요. 재시도, 동시 요청 또는 장애로 인해 데이터가 유실되거나 중복될 수 있는 데이터베이스, 큐, 워크플로 엔진 및 서비스에 이 스킬을 사용하세요. 단일 머신에서 실행되는 서비스도 도움이 될 수 있습니다.
테스트 전문가가 될 필요는 없습니다. 기능과 무엇이 계속 참이어야 하는지 설명하면, 설계 스킬이 테스트를 선택하고 그것이 왜 중요한지 설명하는 데 도움을 줍니다.
스킬은 Markdown 지침, 템플릿 및 참고 자료입니다. 코딩 에이전트는 프로젝트의 테스트 도구와 런타임을 사용하여 이를 따릅니다. 이 저장소에는 데이터베이스 테스트 러너나 즉시 사용 가능한 클러스터가 포함되어 있지 않습니다.
| 스킬 | 제공할 것 | 생성물 |
|---|---|---|
| 테스트 설계 | 코드베이스와 테스트하려는 변경 사항 또는 기능 | 무엇을 테스트할지, 어떻게 확인할지, 얼마나 테스트할지 설명하는 계획 |
| 테스트 실행 | 계획과 테스트 환경 | 결과, 지원 로그 및 데이터, 실패 재현 단계, 보고서 |
설계 스킬은 단독으로 사용할 수 있습니다. 실행은 저장된 계획을 읽는 별도의 단계이므로, 실행하기 전에 작업과 비용을 검토할 수 있습니다.
빠른 시작, Codex 설정 또는 테스트 환경 가이드로 시작하세요.
코딩 에이전트에 다음을 붙여넣으세요:
Read https://raw.githubusercontent.com/shenli/distributed-system-testing/main/INSTALL.md
and follow the instructions to install or update
distributed-testing-skills for this agent.
설치 가이드는 ~/.local/share/distributed-testing-skills/에 있는 공유 체크아웃을 사용하며, 에이전트를 위한 포인터 또는 심볼릭 링크를 구성합니다. 업데이트하려면 동일한 프롬프트를 재사용하세요. 아래 프롬프트에 명시된 경로를 사용하면 자동 검색 없이도 스킬을 로드할 수 있습니다. 다른 위치를 선택한 경우 설치 경로를 대체하세요.
Claude Code의 경우, 저장소에는 플러그인 설치 옵션도 포함되어 있습니다:
/plugin marketplace add shenli/distributed-system-testing
/plugin install distributed-testing-skills@distributed-testing-skills
테스트하려는 저장소에서 에이전트를 시작하세요. 특정 변경 사항의 경우:
Use ~/.local/share/distributed-testing-skills/skills/designing-distributed-system-tests/SKILL.md
Design a test plan for the current branch's changes to adding log entries,
retrying failed requests, and recovering after a crash.
Reuse the existing tests and setup instructions.
Save the plan to docs/testing-plans/append-recovery.md.
예시 기능을 여러분의 것으로 교체하세요. 더 광범위한 검토를 원한다면 프로젝트 전체 계획을 요청하고 포함할 부분을 지정하세요. 이 모드는 단일 변경 사항이 아니라 기존 테스트를 검토하고 시스템 전반에서 누락된 커버리지를 식별합니다.
검사 중인 약속, 제안된 테스트, 필요한 도구, 실행 시간을 검토하세요. 문서 오타나 이와 유사하게 영향이 적은 변경에는 분산 테스트 계획 대신 가벼운 테스트 권장 사항이 제공되어야 합니다.
Use ~/.local/share/distributed-testing-skills/skills/executing-distributed-system-tests/SKILL.md
Run the small initial checks (the smoke tier) from
docs/testing-plans/append-recovery.md against this project's local test
environment. Keep temporary test scripts and results under
./test-sessions/. Use default mode; do not modify project source files.
Report what ran, what failed, and what remains untested.
실행 스킬은 기존 도구를 탐색하고, 환경에서 사용 가능한 것이 무엇인지 질문한 뒤, 요구 사항을 검증합니다. 누락된 의존성이나 효과가 없는 시뮬레이션 실패는 조용히 성공한 테스트로 집계되지 않고 반드시 보고되어야 합니다. 작게 시작한 뒤, 계획에 정의된 더 길고 철저한 실행을 요청하세요.
자세한 프롬프트, 사용자 지정 출력 경로, 작성자 모드에 대해서는 USAGE.md를 참조하세요.
위의 설치 프롬프트를 Codex에서 실행하세요. 이 가이드는 공유 체크아웃의 두 스킬 폴더를 ~/.agents/skills/로 링크하며, Codex는 이곳에서 해당 폴더를 탐색합니다. 프로젝트 전용 설치의 경우에는 해당 프로젝트의 .agents/skills/를 대신 사용하세요. 이러한 위치와 심볼릭 링크 지원은 공식 Codex 스킬 문서에 설명되어 있습니다.
테스트하려는 프로젝트를 여세요. Codex CLI 또는 IDE 확장에서 /skills를 사용하여 두 스킬이 모두 나타나는지 확인하거나, $를 입력하여 하나를 선택하세요. 새로 설치한 스킬이 나타나지 않으면 Codex를 재시작하세요. 빠른 시작에 있는 명시적 파일 경로 프롬프트를 사용할 수도 있습니다. 공식 호출 안내를 참조하세요.
예를 들어, Codex에 계획 설계를 요청하세요:
$designing-distributed-system-tests
Design a test plan for this project's retry and recovery behavior.
I have Docker locally and can run disposable containers.
Start with normal operation, then simultaneous requests and restarts.
Save the plan to docs/testing-plans/retry-recovery.md.
검토한 후 초기 테스트를 실행합니다:
$executing-distributed-system-tests
Run the smoke tier of docs/testing-plans/retry-recovery.md.
Use default mode and save results under ./test-sessions/.
Docker is available; use the project's documented container setup.
Report any missing tools or permissions and which tests they prevent.
스킬을 설치한다고 해서 Docker, 원격 접속, 테스트 클러스터가 제공되는 것은 아니며, 지침만 제공됩니다. Codex는 명령이 실행될 환경에 접근할 수 있어야 합니다. 원격 테스트를 위해서는 테스트 호스트, 기존 연결 방식, 프로젝트의 설정 명령을 알려주어야 합니다. 접근이 불가능한 경우에도 계획은 설계할 수 있지만, 원격 테스트가 실행되었다고 보고할 수는 없습니다.
질문에 답할 수 있는 가장 작은 구성부터 사용하세요. 다음은 애플리케이션에 맞게 조정할 출발점이며, 하드웨어 요구 사항이나 번들 배포 레시피가 아닙니다.
| 목표 | 권장 구성 | 알 수 있는 것 |
|---|---|---|
| 정확성 버그를 빠르게 찾기 | 노트북, 프로젝트 런타임, 일회용 로컬 프로세스 또는 컨테이너 | 해당 구성에서 요청, 재시도, 트랜잭션, 재시작이 올바르게 동작하는지 여부 |
| 버전 간 성능 비교 | 조용한 전용 테스트 머신, 서비스를 측정할 때 요청을 보낼 별도 머신 | 동일한 조건에서 변경이 속도나 리소스 사용에 영향을 주는지 여부 |
| 여러 머신에 걸친 장애 테스트 | 별도의 테스트 호스트 또는 VM, 호스트당 서버 인스턴스 하나, 별도의 테스트 컨트롤러 | 서버 하나가 중단되거나 서버 간 통신이 끊길 때 시스템이 어떻게 처리하는지 |
프로젝트의 기존 설정 지침부터 시작하세요. 필요한 언어/런타임을 설치하고, 컨테이너를 사용하는 경우 Docker 또는 지원되는 다른 컨테이너 런타임을 설치하세요. 각 인스턴스에 자체 포트와 데이터 디렉터리 또는 볼륨을 부여하세요. 전용 테스트 데이터베이스와 데이터를 재설정할 수 있는 반복 가능한 방법을 사용하세요.
이름으로 통신하는 컨테이너의 경우, 사용자 정의 Docker 네트워크가 컨테이너 간 이름 확인을 제공할 수 있습니다. Docker 네트워킹을 참조하세요. 노트북 하나에 여러 컨테이너를 두는 것은 통신을 시험하는 데 유용하지만, 여전히 호스트의 리소스와 장애 위험을 공유합니다. 별도 머신을 잃는 상황에 대한 복원력을 입증하지는 못합니다.
부하 생성기는 테스트 요청을 보내는 프로그램입니다. 프로젝트의 기존 벤치마크를 선호하세요. 예를 들어 PostgreSQL의 pgbench는 반복 트랜잭션과 사용자 정의 SQL 스크립트를 지원합니다. 도구의 기본 워크로드를 대표적인 것으로 간주하지 말고, 애플리케이션과 유사한 요청과 데이터 크기를 선택하세요.
설계 스킬에 목표 요청률, 데이터 크기, 허용 가능한 응답 시간, 사용 가능한 머신을 알려주세요. 아직 목표가 없다면 초기 측정 계획을 요청하세요. 판정 중인 동일한 실행에서 합격 기준을 임의로 만들어내지 마세요.
애플리케이션이 지원하는 클러스터 크기를 사용하세요. 세 개의 투표 복제본을 지원하는 서비스의 경우, 시작 레이아웃은 세 개의 서버 호스트와 요청을 보내고 결과를 수집하는 컨트롤러입니다. 3노드 과반수에는 두 개의 투표가 필요하므로, 이 레이아웃은 한 투표자의 손실을 시험할 수 있습니다. 다른 아키텍처에는 다른 레이아웃이 필요합니다. 하나의 물리적 호스트에 있는 별도의 VM은 여전히 물리적 호스트 손실을 테스트하지 못합니다.
테스트를 실행하기 전에:
정상 트래픽으로 시작한 다음, 서버 하나를 재시작하고, 그다음 요청이 계속되는 상태에서 연결을 끊으세요. 성공적인 복구와 데이터의 정확성을 모두 테스트하세요. 더 큰 클러스터, 리전 간 레이아웃, 스토리지 장애는 실제로 테스트해야 하는 보장 사항을 따라야 합니다.
Codex에 구체적인 환경 설명을 제공하세요. 예를 들어: