Debugger

DEBUGGER 워크플로우

$ARGUMENTS 를 파싱하여 모드와 플래그를 결정한다.

플래그 파싱

플래그	모드
(없음)	기본 모드 — 4단계
--pw	Playwright MCP 모드 — 5단계
--pw --headless	Playwright MCP headless 선호
--pw --record	Playwright MCP trace/video 기록 선호

--pw 모드는 이 플러그인에 동봉된 Playwright MCP 서버(.mcp.json)를 사용한다.

---

안티-트리거 확인

아래 조건에 해당하면 스킬을 실행하지 않고 즉시 중단한다:

• 단순 코드 리뷰 요청 ("이 코드 어때?")
• 신규 기능 구현 요청 (버그가 아닌 경우)
• 원인이 이미 특정된 상태에서 수정만 요청 → 수정만 진행, 로그 삽입 스킵
• 성능 최적화 요청

---

기본 모드 (4단계)

[1/4] 분석

1. 관련 코드 파일 읽기 — 버그 현상·에러 메시지·재현 조건 파악
2. sequential_thinking 툴로 가설 도출 (필수)
   • 각 Thought에서 하나의 가설을 검토하고 근거/반례를 기술
   • 가설이 기각되면 isRevision: true로 수정하거나 다음 가설로 이동
   • nextThoughtNeeded: false가 되면 상위 가설 최대 5개 확정
3. 의심 지점을 최대 5개까지 목록화 (우선순위 상위 5개만)
4. 출력 형식:

[1/4] 분석
의심 지점:
1. 파일:라인 — 근거
2. 파일:라인 — 근거
...

[2/4] 로그 삽입

의심 지점 각각에 디버그 로그를 파일에 직접 삽입한다.

**로그 삽입 규칙 (§로그 규칙 참조)**를 엄격히 준수.

삽입 완료 후:

• 사용자에게 실행 명령과 결과 붙여넣기 요청을 명시
• 대기 — 사용자가 로그를 붙여넣기 전까지 [3/4]로 절대 진행하지 않음
• 도중에 사용자가 다른 질문을 하면 → 해당 질문에 답한 뒤 로그 결과 대기 상태임을 재고지

[3/4] 원인 특정

사용자가 붙여넣은 로그를 읽고 의심 지점 중 실제 원인을 특정한다.

출력 형식:

원인: 파일:라인 — 설명

로그로 특정 불가 시:

• 추가 로그를 삽입하고 [2/4]로 복귀 (최대 2회)
• 2회 초과 시 → 사용자에게 추가 정보(재현 조건·환경 등) 요청 후 중단

[4/4] 수정 + 정리

1. 범위 판정 게이트 (§범위 판정 게이트) → 수정 범위 확정
2. 확정 범위에 버그 수정 적용 — 기본은 원인 파일. 범위 판정에서 ⚠️ 변경필요로 나온 인접 경계는 같은 원인의 다른 발현이므로 함께 수정. stub→제대로 권고가 있으면 반영
3. 사용자에게 재실행 요청 → 결과 확인
4. 회귀 게이트 → 프로젝트 검증 스크립트(verify.sh, npm test, npm run build, pytest 등)가 있으면 실행. 재현 증상은 사라졌어도 수정이 다른 곳(tsc/lint/단위테스트)을 깨뜨리지 않았는지 확인. FAIL → 회귀 수정 후 재검증
5. 해결됨(증상 해소 + 검증 스크립트 PASS) → §정리 단계 실행 후 수정 요약 출력 + 종료
6. 미해결 → [3/4]로 복귀 (최대 2회 반복). 2회 초과 시 상황 보고 후 중단

---

--pw 모드 (5단계)

사전 조건 체크 (필수)

1. Playwright MCP 서버 연결 여부 확인 (이 플러그인에 동봉됨)
   • 미연결 → 연결 안내 제안. 사용자 거부 시 기본 모드(4단계) 폴백 여부 질문
2. 대상 프로젝트가 웹 UI 프로젝트인지 확인 (package.json, index.html, 사용자 명시)
3. 재현 URL과 재현 시나리오 확인 — 없으면 사용자에게 1회 질문
4. 백엔드 의존성이 있는 프로젝트라면, 재현/수정 사이클이 운영 데이터에 영향을 주지 않도록 로컬·테스트 환경(테스트 DB·개발 서버)을 사용하도록 사용자에게 안내한다

[1/5] 분석

기본 모드 [1/4]와 동일. (sequential_thinking 툴 필수 실행 포함)

[2/5] 로그 삽입

기본 모드 [2/4]와 동일. 단 클라이언트 코드는 console.log 사용 (브라우저 콘솔 가시성 확보).

[3/5] Playwright MCP 자동 실행

Playwright MCP 도구로 지정된 URL/시나리오를 실행한다:

• 콘솔 로그, 네트워크 로그, 스크린샷 수집
• --record 시 trace 기록 옵션 선호
• 출력: 수집 로그 요약 + 스크린샷 경로 (MCP 반환 경로 그대로)

수집 대상별 Playwright MCP 도구:

• 콘솔 에러: browser_console_messages
• 네트워크 요청·응답: browser_network_requests / browser_network_request
• 스크린샷: browser_take_screenshot
• DOM 스냅샷: browser_snapshot

[4/5] 원인 특정

수집된 로그·스크린샷 기반으로 원인 특정. 기본 모드 [3/4]와 동일 형식.

[5/5] 수정 + 검증 + 정리

1. 범위 판정 게이트 (§범위 판정 게이트) → 수정 범위 확정 후 수정 코드 적용
2. Playwright MCP로 동일 시나리오 재실행 → 로그·스크린샷으로 해결 검증
3. 회귀 게이트 → 프로젝트 검증 스크립트(verify.sh, npm test, npm run build, pytest 등)가 있으면 실행. 시나리오 재현은 동일 증상만 보므로, 정적+단위 게이트로 회귀를 추가 확인. FAIL → 회귀 수정 후 재검증
4. 해결됨(증상 해소 + 검증 스크립트 PASS) → §정리 단계 실행 + before/after 스크린샷 경로 출력 + 종료
5. 미해결 → [4/5]로 복귀 (최대 2회). 2회 초과 시 가설·수정 이력·수집 로그 요약 보고 후 중단

---

범위 판정 게이트

원인 특정([3/4]·[4/5]) 직후, 수정을 적용하기 전에 실행한다. 단편적 수정(이 화면만 막고 넘어가 나중에 들어내는 것)과 부적절한 stub를 잡는 단계다.

판정 기준

특정된 원인(파일:라인 + 설명)과 계획된 수정안(무엇을 어떻게 — 아직 미적용)을 놓고, 직접 인접한 경계를 각각 점검한다:

• 호출부: 이 함수/모듈을 부르는 쪽이 수정 후 계약을 그대로 유지하는가?
• API/데이터 계약: 반환 타입·스키마·에러 형태가 바뀌면 소비자가 깨지지 않는가?
• 공유 상태: 전역·캐시·DB 등 공유 자원의 다른 사용처에서 같은 버그가 재발현하지 않는가?

임시구현(stub/fallback/하드코딩)을 넣으려 한다면 2×2로 평가한다:

• 형태가 known인가? (제대로 된 구현의 모양을 지금 아는가)
• 되돌리기 비용이 낮은가? (나중에 제대로 바꿀 때 파급이 작은가)
• 둘 다 "아니오"에 가까우면 stub 대신 처음부터 제대로 구현한다.

별도의 범위 검토용 read-only 서브에이전트가 설치·사용 가능한 환경이라면, 위 기준으로 판정을 위임해 교차검증할 수 있다. 없으면 위 기준으로 인라인 자기검토를 수행한다.

결과 처리

판정 결론	동작
수정안 그대로 OK	계획대로 [4/4]·[5/5] 수정 적용
범위 확대 필요	⚠️ 경계를 수정 범위에 포함 (같은 원인의 발현 = 인스코프, 리팩토링 아님)
stub→제대로 권고	stub 대신 제대로 구현

• 단일 함수 내부 순수 로직 버그처럼 인접 경계가 없으면 즉시 "그대로 OK" — 오버헤드가 작다.
• 판정을 정당한 근거로 무시할 수 있으나, 무시 시 사유 1줄을 남긴다(무비판 수용·무비판 무시 둘 다 금지).

---

로그 규칙

지원 언어별 로그 형식

언어	마커 주석	로그 함수	예시
JavaScript/TypeScript	// [DEBUG-INSERTED]	console.log	console.log('[DEBUG] userId:', userId);
Python	# [DEBUG-INSERTED]	print (또는 기존 logger)	print(f'[DEBUG] user_id: {user_id}')
Java	// [DEBUG-INSERTED]	System.out.println (또는 기존 logger)	System.out.println("[DEBUG] userId: " + userId);
Kotlin	// [DEBUG-INSERTED]	println (또는 기존 Log/logger)	println("[DEBUG] userId: $userId")

불변 규칙

1. 모든 삽입 로그는 [DEBUG] 문자열을 반드시 포함
2. 로그 라인 바로 위에 // [DEBUG-INSERTED] 또는 # [DEBUG-INSERTED] 마커 주석 삽입
3. 기존 logger (winston, pino, SLF4J 등)가 있으면 해당 logger의 debug 레벨 사용 — 마커 규칙은 동일 적용
4. 로그에 비밀번호·토큰·개인정보가 찍힐 가능성이 있으면 해당 필드를 ***로 마스킹

---

정리 단계

마커 주석 기반 제거만 수행한다:

• [DEBUG-INSERTED] 마커 주석이 달린 라인과 바로 아래 로그 라인 쌍을 제거
• 마커 없이 [DEBUG]만 있는 라인은 사용자의 기존 로그 → 절대 건드리지 않음

제거 후 검증 (필수):

grep -r "\[DEBUG-INSERTED\]" . --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.java" --include="*.kt"

• 결과가 0건이어야 종료 가능
• 1건 이상이면 해당 파일로 돌아가 재정리

정리 완료 출력:

정리 완료: 제거한 로그 N개 / 수정된 파일: 파일목록

---

안전 규칙

• 수정 범위는 원인 + 범위 판정 게이트에서 ⚠️ 변경필요로 나온 인접 경계(같은 원인의 다른 발현)에 한정 — 그 외 관련 없는 리팩토링·기능 추가는 금지
• 테스트 파일(*.spec.*, *.test.*)·CI 설정·.env·secrets 파일에는 로그 삽입 금지
• 정리 단계 없이 커밋하는 것은 불가 — 종료 전 반드시 grep 검증 수행

---

Known Pitfalls

본 skill 실행 중 반복 발생한 실패 패턴. 신규 패턴 발견 시 entry 추가.

(현재 누적 entry 없음)

작성 형식

• [패턴명] — YYYY-MM-DD
  • 상황: 어떤 단계(로그 삽입/원인 특정/정리)·조건에서 발생
  • 원인: 무엇 때문에 실패 (마커 누락 / 정리 실패 / 잘못된 원인 특정 등)
  • 회피: 다음 실행 시 적용할 가이드