qualiow-exploratory-testing
웹(web), 모바일(mobile) 및 백엔드/API를 위한 AI 기반 탐색 테스트—Claude Code 스킬, QA 지식 기반, 그리고 이를 프로젝트에 연결하는 CLI입니다.
Claude는 수석 QA 엔지니어 역할을 수행합니다: 비즈니스를 먼저 이해하고, 중요한 것을 위험도별로 순위화하며, 체계적으로 탐색하고, 임원이 조치할 수 있는 버그 보고서를 작성합니다. 테스트 스크립트나 프레임워크가 필요 없습니다—AI 추론, 브라우저/장치 명령어, 그리고 QA 휴리스틱만 사용합니다.
| 표면 (Surface) | 드라이버 (Driver) | 스킬 (Skill) |
|---|
| 데스크톱 브라우저의 웹 앱 | playwright-cli | /qa-explore, /qa-explore-quick |
| ... | | |
요구 사항 (Requirements)
- Node.js >= 22.4 (
node --version으로 확인 가능)
- Claude Code — 이 스킬들은 내부에서 슬래시 명령어(slash commands)로 실행됩니다.
playwright-cli는 이 패키지의 종속성으로 제공되므로, 웹 경로를 위해 추가 설치할 것은 없습니다. 모바일의 경우 iOS/Android 툴체인이 필요합니다—docs/MOBILE-SETUP.md 참조하세요.
설치 (Install)
세 가지 지원 경로가 있습니다. 하나를 선택하세요.
1. npm (프로젝트에 권장)
npm install -g qualiow-exploratory-testing
cd my-project
qualiow init
qualiow init은 현재 프로젝트에 다음 내용을 복사합니다:
| 복사되는 항목 | 위치 (To) |
|---|
| 11개의 스킬 | .claude/skills/qa-*/ |
| ... | |
또한 output/{sessions,bugs,context}, .auth/, 그리고 qa/ 디렉토리를 생성하고, .gitignore에 # Qualiow 블록을 추가합니다 (.auth/, .env, qa/.env, output/sessions/*/, !output/sessions/INDEX.md, output/context/*.md, data/targets/local-*.yml, .playwright-cli/, *.trace.zip, *.webm).
init을 다시 실행하는 것은 아무런 변화가 없습니다—기존 파일은 유지되며, --force를 전달하지 않는 한 변경되지 않습니다. 그리고 --dry-run은 아무것도 작성하지 않고 계획만 출력합니다. 프로젝트에 세 개의 가드 훅(guard hooks)을 설치하려면 --hooks를 추가하세요—Hooks 참조.
cp qa/.env.example qa/.env
npx playwright-cli install --skills
/qa-explore https://your-app.com
2. Claude Code 플러그인
claude plugin marketplace add willcoliveira/qualiow-exploratory-testing-skills
claude plugin install qualiow@qualiow
이 저장소는 자체 마켓플레이스(.claude-plugin/marketplace.json)를 가지고 있으므로, 위 두 명령어만으로 설치가 완료됩니다. 로컬 체크아웃을 이용해 개발할 경우에는 대신 Claude Code를 해당 디렉터리에 지정해야 합니다:
claude --plugin-dir /path/to/qualiow-exploratory-testing-skills
스킬은 네임스페이스(namespaced) 형태로 나타납니다: /qualiow:qa-explore, /qualiow:qa-verify-backend 등입니다. 데이터(지식, 도메인, 템플릿, 타겟)는 사용자가 위치한 프로젝트에 자체 data/ 또는 qa/ 디렉터리가 없는 경우 ${CLAUDE_PLUGIN_ROOT}/data/에서 해결됩니다. 다만, 해당 프로젝트가 자체 data/나 qa/ 디렉터리를 가지고 있다면 그것이 우선합니다.
bin/ 경로는 마켓플레이스 설치 시에만 PATH에 추가됩니다. --plugin-dir를 사용할 경우에는 드라이버를 전체 경로인 ${CLAUDE_PLUGIN_ROOT}/bin/mcli로 호출해야 합니다.
플러그인 설치 하에서는 qualiow CLI가 래퍼 쉼(launcher shim)인 bin/qualiow를 통해 실행됩니다. 이는 체크아웃에 로컬 빌드가 있는 경우 이를 사용하고, 그렇지 않은 경우에는 .claude-plugin/plugin.json에 지정된 버전으로 npx를 사용하여 게시된 npm 패키지를 가져옵니다. 플러그인 설치에는 dist/가 없기 때문에, 해당 경로의 첫 실행 시 네트워크 연결이 필요합니다.
3. Git 체크아웃 (기여자, 자체 테스트)
git clone https://github.com/willcoliveira/qualiow-exploratory-testing-skills.git
cd qualiow-exploratory-testing-skills
npm install
...
.claude/skills/와 .claude/agents/가 표준적인(canonical) 위치입니다. skills/와 agents/는 생성된 미러(generated mirrors)이며 (npm에 배포되고 플러그인에서 사용됨), npm run sync:plugin을 통해 동기화됩니다. CI에서는 드리프트(drift) 발생 시 실패하므로, 이 미러들을 수동으로 수정해서는 안 됩니다.
CLI
CLI는 스킬 주변의 인프라스트럭처입니다 — 프로젝트 설정, 구성 유효성 검사, 세션 목록화, 보고서 내보내기 등이 포함됩니다. 탐색 세션 자체는 셸(shell)에서 실행되는 것이 아니라 Claude Code 내부에서 실행됩니다.
| 명령어 | 플래그 | 기능 설명 |
|---|
qualiow init | --include-examples --force --dry-run --hooks | 스킬, 서브 에이전트(sub-agents), 데이터, qa/bin/, 그리고 출력 트리를 현재 프로젝트에 설치합니다. 반복 실행해도 문제가 없습니다(Idempotent). --hooks는 또한 가드 스크립트를 qa/hooks/로 복사하고 훅 및 권한 항목을 .claude/settings.json에 병합합니다. |
| ... | | |
qualiow gather는 2.0.0 버전에서 제거되었습니다. 이 명령어는 아무것도 쓰지 않는 더미(stub)였습니다. 실제 작업을 수행하는 /qa-gather 스킬을 사용하십시오. | | |
전역 설치(global install)를 하면 모바일 도우미들이 PATH에 추가됩니다: mcli, wadb, wk-ios, qualiow-doctor-mobile, qualiow-setup-mobile.
토큰 라우팅 (Token routing)
고정된 계약(fixed contract)을 다루는 것은 모델이 아니라 CLI에 속합니다. 세션은 data/knowledge/manifest.yml과 다섯 개의 항상 로드되는 항목(~964줄) 전체를 읽는 대신 qualiow kb digest를 통해 지식 기반(knowledge base)을 로드하고, qualiow session finalize로 마무리됩니다. 따라서 INDEX 및 all-bugs.md 행과 메트릭 라인은 수동으로 작성되지 않습니다. /qa-knowledge-list와 /qa-explore-cleanup은 각각 list knowledge 및 session ...을 감싸는 래퍼(wrapper)입니다. contract-2 세션의 커버리지 수준은 qualiow session level에 의해 동일한 방식으로 계산되며, 보고서가 이를 그대로 복사합니다.
CLI 아래에는 두 번째 계층이 있으며, 이는 2.2.0 버전에서 새로 추가되었습니다. 가벼운 판단(light judgement)이 필요한 대량 읽기 작업은 전체 파일 대신 경계가 지정되고 인용된 요약본(digest)을 반환하는 저렴한 서브 에이전트(sub-agent)로 전달됩니다.
판단이 필요한 모든 것은 그 자리에 남아 있습니다. 즉, 심각도(severity), 우선순위(priority), 비즈니스 영향도(business impact), 버그 보고서 자체, 헌장 및 위험 등급(charter and risk ranking), 누락된 부분, AC 판정(AC verdicts), 요약 보고서(executive summary) 및 성찰입니다. 유일하게 경계가 설정된 예외는 버그 심사관(bug judge)(아래)입니다. 이는 후보 버그가 발견된 맥락을 전혀 보지 못한 상태에서 재현되는지에 대한 두 번째 의견을 제시하는 것입니다. 위임되지 않는 항목 목록과 나머지 작업을 라우팅하는 판독 임계값은 [skills/qa-explore/references/delegation-rules.md]에 있습니다.
서브 에이전트(Sub-agents)
패키지에는 다섯 개의 서브 에이전트가 포함되어 있으며, .claude/agents/ (이는 agents/와 미러링됨)에서 사용할 수 있습니다. 각 에이전트는 세션에 대신하여 작업을 수행하고 경계가 설정된 결과를 반환합니다:
| 서브 에이전트 | 모델 | 반환 내용 | 호출 주체 |
|---|
qa-gather-agent | sonnet | 소스에서 침묵한 부분이 있는 경우 [GAP] 및 [ASSUMPTION] 마커가 포함된 요구사항 컨텍스트 파일 | /qa-gather, 이 내부에서 완전히 실행됨 |
| ... | | | |
이 중 네 개의 에이전트는 결론을 반환하지 않습니다. 심각도, 우선순위, 비즈니스 영향도, “이는 버그다”라는 진단, PASS/FAIL 같은 것은 없습니다. 이들은 추출하고, 인덱싱하며, 조립합니다. 최종 결정은 세션에서 내립니다. 판단을 자원하는 위임자는 자신의 임무를 초과한 것이며, 그 답변의 해당 부분은 폐기됩니다.
qa-bug-judge만이 경계가 설정된 예외입니다. 이 에이전트는 오직 두 가지에 대해서만 판정합니다. 즉, 카드에 제시된 주장이 재현되는지 또는 증거를 통해 뒷받침되는지 여부와 조언으로서 주장된 심각도가 심각도 가이드라인에 적합한지 여부입니다. 배포할지 여부, 최종 심각도, 비즈니스 영향도 및 배포된 보고서의 모든 단어는 세션에 남아 있으며, 이 세션은 반박을 무효화할 수 있습니다. 버그 검증(Bug verification)을 참조하십시오.
빠른 세션은 자체 보고서를 작성합니다. 에이전트를 가동하는 비용은 15분짜리 세션에서 절약되는 비용보다 더 많이 들기 때문입니다.
자문 분류 (Advisory triage) (선택 사항)
/qa-explore의 Phase 7은 또한 **결정 모델(decision model)**을 요청할 수 있습니다. 이 결정 모델은 산문이 아닌 텍스트에 대한 유형화된 확률값(typed probabilities)을 반환하며, 심사위원(judge)이 실행하기 전에 클레임 카드(claim card)가 어떻게 보일지 예측하고 그 답변을 심사위원의 평결 옆에 기록합니다. 이 기능은 기본적으로 비활성화되어 있으며 엄격하게 자문용입니다. 즉, 심사위원은 여전히 모든 클레임을 동일한 순서와 예산으로 확인하며, 트리아지 파일(triage files)을 읽지 않으며, 트리아지의 결정에 따라 어떤 것도 전송되거나 건너뛰어지지 않습니다. 사용자가 다음 설정을 통해 이 기능을 활성화할 수 있습니다:
verification:
mode: triage-shadow
triage_providers: [laya]
...
laya: /v1/systemone에서 작동하는 셀프 호스팅 Laya 서버입니다. 이 엔드포인트는 어떤 것이 전송되기 전에 루프백(loopback)이어야 하며, 리디렉션은 거부되므로 아무것도 외부로 나가지 않습니다.typesafe: TypeSafe가 호스팅하는 Jev입니다. 후보 버그당 한 개의 정리된 클레임 카드만 기계를 벗어나며, 정확한 요청 내용은 verification/JEV-NNN.json으로 저장됩니다. 이 정리는 패턴 기반이며 공백(IP 주소, 단일 레이블 호스트, URL 경로, 자유 텍스트 이름)이 존재하므로, 먼저 --dry-run을 실행하여 확인하는 것이 좋습니다.--provider는 오직 대상 시스템 자체의 목록만 좁힐 뿐입니다. 사용자가 명시하지 않은 제공업체(provider)를 추가할 수는 없습니다.
각 실행은 verification/JEV-NNN.* 또는 LAYA-NNN.* 파일을 작성합니다. 여기에는 예측된 평결, 기록된 판독값(refute-risk, unclear, likely-confirmed), 심각도 적합성(severity fit), 그리고 전송되었거나 전송되지 않은 증거가 포함됩니다. 예측된 평결은 심사위원의 평결에 대한 추측일 뿐, 결코 평결 자체가 아닙니다. 전체 참조: skills/qa-explore/references/evidence-triage.md.
후크 (Hooks)
세 가지 PreToolUse 후크는 위임(delegation) 및 보안 규칙에서 요구하는 사항을 강제합니다. 읽기 및 쓰기 가드(read and write guards)는 qualiow가 소유한 경로로 범위가 제한되며, bash 가드는 모든 Bash 명령을 확인하지만 아래의 몇 가지 패턴에 대해서만 작동하므로, 동일 프로젝트 내에서의 일반적인 코딩 작업에는 영향을 미치지 않습니다.
read-guard.mjs (매처(matcher) Read)는 오직 data/knowledge/manifest.yml, data/knowledge/releases/**, output/sessions/*/phase-*.md, 그리고 output/sessions/*/snapshots/*에 대해서만 작동합니다. 이 파일들 중 하나를 QUALIOW_READ_MAX_LINES 라인(기본값 300)을 초과하여 전체 읽기(whole-file read)를 시도하는 경우 접근이 거부되며, 그 이유는 더 비용 효율적인 경로(예: qualiow kb digest, qualiow list knowledge --entry <id>, offset/limit을 사용한 Grep 및 Read, 또는 qa-page-mapper-agent)가 명시됩니다. 이미 offset이나 limit을 포함하고 있는 Read 요청은 수정 없이 통과합니다.write-guard.mjs (매처(matcher) Write|Edit|MultiEdit|NotebookEdit)는 오직 output/ 디렉토리 아래의 파일에 대해서만 작동하며, 절대 snapshots/ 내부에서는 작동하지 않습니다. 이 가드는 포맷터(formatters)와 qualiow session finalize가 적용하는 것과 동일한 마스킹 목록(redaction list)과 일치하는 콘텐츠를 거부합니다. Edit의 경우, 편집 후 읽힐 파일 자체를 검사하며, 어떤 카테고리의 내용이 일치했는지 이름을 지정하여 비밀 정보가 디스크에 도달하기 전에 포착되도록 합니다.bash-guard.mjs (매처(matcher) Bash)는 playwright-cli run-code 실행 전(이는 브라우저 샌드박스가 아닌 Playwright 노드 프로세스에서 실행됨), 쉘을 실행할 수 있는 옵션(-c, --upload-pack, --ext-diff 등)이 포함된 git 사용 전, 그리고 playwright-cli, @playwright/cli, qualiow-exploratory-testing 외부에 있는 패키지에 대한 npx -c 및 npx -y/-p를 거부합니다. 이는 샌드박스가 아니라 안전장치(safety net)입니다.
세 가지 가드를 모두 비활성화하려면 QUALIOW_HOOKS=off를 설정하고, 라인 제한 임계값을 조정하려면 .claude/settings.json의 env 섹션에 QUALIOW_READ_MAX_LINES를 지정합니다:
{ "env": { "QUALIOW_HOOKS": "off", "QUALIOW_READ_MAX_LINES": "500" } }
플러그인 설치 시 기본적으로 훅(hooks)이 적용됩니다 — hooks/hooks.json은 플러그인과 함께 제공되며, 별도의 설정 없이 자동으로 발견됩니다. npm 프로젝트는 qualiow init --hooks를 통해 옵트인(opt in) 방식으로 진행하며, 이 명령어는 스크립트를 qa/hooks/에 복사하고 세 개의 훅 항목(Bash(playwright-cli:*), Bash(npx playwright-cli:*), Bash(qualiow:*))과 permissions.allow 규칙을 .claude/settings.json에 병합합니다. 이 병합은 정확한 문자열 기반으로 이루어지므로, 두 번 실행해도 아무 변화가 없으며 이미 존재하는 훅은 그대로 유지됩니다. docs/GETTING-STARTED.md에는 수동으로 작성하려는 사용자를 위해 동일한 코드 스니펫이 포함되어 있습니다.
하나의 프로젝트에서 이 둘을 모두 활성화하지 마십시오. 플러그인의 훅과 프로젝트가 복사한 훅이 모두 실행되는데, 이는 아무런 효과 없는 중복 거부(double deny)이며 도구 호출당 두 개의 node 프로세스가 불필요하게 작동합니다.
세션 실행 (Running sessions)
전체 세션 (45분, 8단계)
/qa-explore https://www.saucedemo.com/
/qa-explore --target company-staging
/qa-explore --target company-staging --context output/context/TICKET-123-context.md
...
설정(Setup) 2분 · 인증(Auth) 2분 · 차터(Charter) 5분 · 탐색(Discovery) 6분 · 여정(Journeys) 10분 · 기능(Features) 10분 · 예외 사례(Edge cases) 6분 · 보고서 작성(Reporting) 4분, 그리고 최대 15분의 버그 검증 시간이 포함됩니다. 발견된 내용은 단계별로 디스크에 기록되므로 컨텍스트가 넘치는 일이 없습니다.
커버리지 레벨 및 --continue
2.4.0 버전부터 /qa-explore와 /qa-explore-quick은 **세션 계약 2(session contract 2)**를 작성합니다. 차터의 위험 등급에 있는 모든 행에는 영구 ID(A1, A2, …)가 부여되며, stats.json에는 각 행마다 하나의 coverage.areas 항목이 기록됩니다 — 테스트됨(tested), 부분적(partial), 차단됨(blocked), 테스트 안 됨(not-tested) 또는 연기됨(deferred)(시간 제한 내에 도달하지 않음)과 함께 증거 파일 및, 테스트되지 않은 경우 그 이유가 기록됩니다. 모든 버그는 해당 영역을 명시합니다. 보고서가 취합되기 전에 CLI는 이 모든 것을 확인하고 레벨을 계산합니다:
qualiow session level latest --write