fix

fix skill 개요

fix skill이 하는 일

fix skill은 실패하거나 간헐적으로 흔들리는 Playwright 테스트를 디버깅하기 위한 집중형 워크플로입니다. AI 에이전트가 단순히 assertion error만 보고 추측하지 않고, 실패를 재현하고 trace 증거를 수집한 뒤 flaky-test taxonomy로 문제를 분류해 “이 테스트가 깨졌다”에서 가능성 높은 근본 원인까지 좁혀 가도록 돕습니다.

Playwright 테스트 디버깅에 가장 잘 맞는 경우

end-to-end 테스트를 관리하면서 “test failing”, “flaky test”, “passes locally but fails in CI”, “intermittent failure” 같은 메시지를 자주 본다면 이 skill을 설치할 만합니다. 특히 CI에서 Playwright를 사용하는 팀에 유용합니다. 이런 실패는 타이밍, 테스트 격리, 환경 차이, 인프라 부하에서 비롯되는 경우가 많기 때문입니다.

일반 프롬프트보다 더 유용한 이유

일반적인 디버깅 프롬프트는 곧바로 코드 수정으로 뛰어드는 경우가 많습니다. fix skill은 더 나은 순서를 강제합니다. 먼저 재현하고, 실패가 사라지면 burn-in을 돌리고, trace를 수집한 다음, 증상을 범주에 매핑합니다. 함께 제공되는 flaky-taxonomy.md에는 구체적인 진단 분기와 수정 패턴이 들어 있습니다. 예를 들어 누락된 await, 공유 상태, CI에서만 다른 viewport/font/timezone, 브라우저 크래시, worker 관련 불안정성 등을 다룹니다.

설치 전에 알아야 할 중요한 한계

이 skill은 범용 버그 수정 도구가 아닙니다. 범위는 Playwright 테스트로 제한되며, 에이전트가 테스트 파일을 살펴보고 Playwright 명령을 실행하며 trace, screenshot, log, CI 실패 텍스트 같은 출력을 읽을 수 있다는 전제를 둡니다. 별도의 helper script는 없으므로, 가치는 자동화가 아니라 워크플로와 taxonomy에서 나옵니다.

fix skill 사용 방법

fix 설치와 먼저 확인할 파일

호환되는 skills 환경에서 다음 명령으로 skill을 설치합니다.

npx skills add alirezarezvani/claude-skills --skill fix

설치 후에는 먼저 SKILL.md를 읽어 실행 워크플로를 확인하고, 이어서 flaky-taxonomy.md를 열어 decision tree와 흔한 수정 방법을 확인하세요. repository path는 engineering-team/playwright-pro/skills/fix이며, 유용한 source file은 의도적으로 작게 구성되어 있습니다. 설정해야 할 숨겨진 script, rule, metadata file은 없습니다.

fix skill에 필요한 입력

가장 좋은 결과를 얻으려면 아래 입력 중 하나 이상을 제공하세요.

• e2e/login.spec.ts 같은 test file path
• 정확한 test name 또는 --grep string
• Failure message, stack trace 또는 assertion error
• 실패가 local에서 발생하는지, CI에서 발생하는지, 또는 둘 다인지
• 단독 실행에서는 통과하지만 full suite에서는 실패하는지 여부
• 가능하다면 trace, screenshot, video 또는 CI artifact path
• 관련 Playwright config, 특히 workers, retries, projects, viewport, timezone, base URL

약한 프롬프트: “Fix my flaky checkout test.”

더 나은 프롬프트: “Use the fix skill for Debugging e2e/checkout.spec.ts, test should submit paid order. It passes locally alone, fails in CI about 30% of runs, and the failure is Timeout 5000ms exceeded waiting for getByRole('button', { name: 'Pay' }). CI uses 4 workers and retries=2. Suggest the reproduction commands, likely category, and minimal code/config changes.”

실제 fix 사용 워크플로

정확히 실패하는 파일부터 시작합니다.

npx playwright test <file> --reporter=list

통과한다면 flaky 가능성이 있다고 보고 burn-in을 실행합니다.

npx playwright test <file> --repeat-each=10 --reporter=list

동시 실행 상황에서만 문제가 드러난다면 parallelism을 켜고 실행합니다.

npx playwright test --fully-parallel --workers=4 --repeat-each=5

그다음 trace 증거를 수집합니다.

npx playwright test <file> --trace=on --retries=0

코드를 수정하기 전에 에이전트에게 실패를 먼저 분류하라고 요청하세요. 기대되는 범주는 timing/async, test isolation, environment, infrastructure입니다. 이렇게 하면 임의의 waitForTimeout을 추가하거나, global timeout을 늘리거나, 실제 race를 retries 뒤에 숨기는 흔한 나쁜 수정을 피할 수 있습니다.

더 나은 결과를 위한 프롬프트 패턴

증거와 요청을 분리한 프롬프트를 사용하세요.

“Use the fix skill. Diagnose before changing code. Test: <file> / <test name>. Reproduction result: <passes/fails command>. CI/local behavior: <details>. Trace or screenshot: <path or summary>. Current suspicion: <optional>. Please categorize using flaky-taxonomy.md, explain the evidence, propose the smallest safe fix, and list the command to verify it.”

이 구조는 skill이 추측성 패치가 아니라 검증 가능한 디버깅 계획을 만들도록 돕습니다.

fix skill FAQ

fix는 flaky test 전용인가요?

아닙니다. fix skill은 항상 실패하는 Playwright 테스트와 간헐적으로 실패하는 테스트를 모두 다룹니다. deterministic failure의 경우에도 재현과 trace 수집부터 시작합니다. intermittent failure의 경우에는 burn-in과 parallel-worker 확인을 추가해 timing, isolation, infrastructure 패턴을 드러냅니다.

이 skill을 쓰지 않는 편이 좋은 경우는 언제인가요?

unit test, backend integration test, Playwright coverage가 없는 production bug, 또는 광범위한 application architecture 디버깅의 주 도구로는 적합하지 않습니다. 일반적인 아이디어를 얻는 데는 도움이 될 수 있지만, 명령어와 taxonomy, 예시는 Playwright end-to-end 테스트를 기준으로 작성되어 있습니다.

Playwright trace viewer만 사용하는 것과 어떻게 다른가요?

Trace viewer는 무슨 일이 일어났는지를 보여 줍니다. fix skill은 그 trace가 무엇을 의미하는지 판단하도록 돕습니다. 예를 들어 element가 없다는 증상은 async race, 이전 테스트에서 누수된 state, CI viewport 차이, network dependency 중 하나일 수 있습니다. taxonomy는 artifact를 진단 경로와 권장 수정 유형으로 바꿔 줍니다.

fix는 초보자에게도 적합한가요?

네, 사용자가 Playwright 명령을 실행하고 error를 공유할 수 있다면 적합합니다. 초보자는 명확한 명령 순서와 category table 덕을 볼 수 있습니다. 다만 이 skill이 기본 프로젝트 설정 지식을 대체하지는 않습니다. Playwright가 이미 설치되어 있어야 하고, test suite를 실행할 수 있어야 하며, artifact에 접근할 수 있어야 합니다.

fix skill 개선 방법

fix에 더 강한 실패 증거 제공하기

가장 중요한 개선은 입력 품질을 높이는 것입니다. 이미 시도한 정확한 명령과 그 결과를 포함하세요. “Fails in CI”보다 “fails in CI with 4 workers, passes locally with one worker, fails locally with --fully-parallel --workers=4 --repeat-each=5”가 훨씬 유용합니다. 이 한 가지 정보만으로도 일반적인 timing 문제가 아니라 isolation 또는 parallelism 쪽으로 가설을 좁힐 수 있습니다.

흔한 디버깅 실패 패턴 피하기

진단 전에 패치를 요청하지 마세요. 흔한 나쁜 결과로는 fixed sleep 추가, global timeout 상향, retry 증가, 원인을 확인하지 않은 selector 재작성 등이 있습니다. 코드를 수정하기 전에 skill에게 category, evidence, minimal fix, verification command를 먼저 제시하라고 요청하세요.

첫 번째 수정 이후 반복 검증하기

제안된 변경을 적용한 뒤에는 의미 있는 가장 작은 verification command를 다시 실행하세요. 수정 대상이 timing이라면 burn-in을 사용합니다. isolation을 겨냥했다면 single-test 실행과 suite 실행 결과를 비교합니다. CI environment를 겨냥했다면 Docker, workers, timezone, viewport, mocked network services처럼 CI에 더 가까운 설정으로 재현하세요.

프로젝트에 맞게 fix 가이드 확장하기

팀은 skill workflow 근처에 프로젝트별 메모를 추가해 로컬 결과를 개선할 수 있습니다. 예를 들어 common CI settings, 알려진 flaky services, 필수 test data reset, standard fixtures, mock strategy, preferred locator conventions 등을 적어 두면 좋습니다. fix skill은 taxonomy가 repository의 실제 실패 패턴과 결합될 때 가장 잘 작동합니다.