가이드: 버그 수정
디버그 워크플로우 사용 시기
특정 버그를 진단하고 수정해야 할 때 /debug를 사용하세요(또는 자연어로 "버그 수정", "에러 수정", "디버그"라고 말해도 됩니다). 이 워크플로우는 증상만 고치는 흔한 함정을 피하고, 근본 원인을 잡아내는 체계적이고 재현 가능한 디버깅 방법을 제공합니다.
디버그 워크플로우는 모든 벤더(Gemini, Claude, Codex, Qwen)를 지원합니다. 단계 1-5는 인라인으로 실행됩니다. 단계 6(유사 패턴 스캔)은 스캔 범위가 넓을 때(10개 이상 파일 또는 멀티 도메인 에러) debug-investigator 서브에이전트에 위임될 수 있습니다.
버그 리포트 템플릿
버그를 보고할 때 가능한 한 다음 정보를 제공하세요. 각 필드는 디버그 워크플로우가 검색 범위를 더 빠르게 좁히는 데 도움됩니다.
필수 필드
| 필드 | 설명 | 예시 |
|---|---|---|
| 에러 메시지 | 정확한 에러 텍스트 또는 스택 트레이스 | TypeError: Cannot read properties of undefined (reading 'id') |
| 재현 단계 | 버그를 트리거하는 순서대로의 동작 | 1. 관리자로 로그인. 2. /users로 이동. 3. 아무 사용자에서 "삭제" 클릭. |
| 예상 동작 | 정상적으로 일어나야 하는 것 | 사용자가 삭제되고 목록에서 제거됨. |
| 실제 동작 | 실제로 일어나는 것 | 화면이 흰색으로 크래시됨. |
선택 필드 (강력 권장)
| 필드 | 설명 | 예시 |
|---|---|---|
| 환경 | 브라우저, OS, Node 버전, 기기 | Chrome 124, macOS 15.3, Node 22.1 |
| 빈도 | 항상, 가끔, 최초 1회만 | 항상 재현 가능 |
| 최근 변경 | 버그 발생 전 변경된 것 | PR #142 머지 (사용자 삭제 기능) |
| 관련 코드 | 의심되는 파일 또는 함수 | src/api/users.ts, deleteUser() |
| 로그 | 서버 로그, 콘솔 출력 | [ERROR] UserService.delete: user.organizationId is undefined |
| 스크린샷/녹화 | 시각적 증거 | 에러 화면 스크린샷 |
미리 더 많은 정보를 제공할수록 디버그 워크플로우가 추가 질문을 주고받을 필요가 줄어듭니다.
심각도 분류 (P0-P3)
심각도는 버그 처리 방법과 수정 속도를 결정합니다.
P0 — 긴급 (즉시 대응)
정의: 프로덕션이 다운되었거나, 데이터가 손실/손상되고 있거나, 보안 침해가 진행 중.
대응 기대: 모든 작업을 중단합니다. 해결될 때까지 이것만 처리합니다.
예시:
- 인증 시스템이 우회됨 — 모든 사용자가 관리자 엔드포인트에 접근 가능.
- 데이터베이스 마이그레이션이 users 테이블을 손상 — 계정 접근 불가.
- 결제 처리가 이중 청구 중.
- API 엔드포인트가 다른 사용자의 개인 정보를 반환.
디버그 접근: 전체 템플릿을 건너뜁니다. 에러 메시지와 스택 트레이스만 제공하면 됩니다. 워크플로우가 즉시 2단계(재현)부터 시작합니다.
P1 — 높음 (현재 세션 내)
정의: 상당수 사용자에게 핵심 기능이 깨짐. 우회 방법이 있을 수 있지만 장기적으로 허용 불가.
대응 기대: 현재 작업 세션 내에 수정. 해결 전까지 새 기능 시작 금지.
예시:
- 특수 문자가 포함된 검색 쿼리에서 검색 결과가 반환되지 않음.
- 5MB보다 큰 파일 업로드 실패 (제한은 50MB여야 함).
- Android 14 기기에서 모바일 앱이 실행 시 크래시.
- 비밀번호 재설정 이메일이 발송되지 않음 (이메일 서비스 통합 중단).
디버그 접근: 전체 5단계 루프. 수정 후 QA 리뷰 권장.
P2 — 중간 (이번 스프린트)
정의: 기능은 작동하지만 동작이 저하된 상태. 기능 자체가 아닌 사용성에 영향을 줌.
대응 기대: 현재 스프린트에 일정 잡기. 다음 릴리스 전에 수정.
예시:
- 테이블 정렬이 대소문자를 구분 ("apple"이 "Zebra" 뒤에 정렬됨).
- 다크 모드에서 설정 패널에 읽을 수 없는 텍스트.
- /users 엔드포인트의 API 응답 시간이 8초 (1초 미만이어야 함).
- 목록이 비어있을 때 페이지네이션이 "Page 1 of 0"을 표시.
디버그 접근: 전체 5단계 루프. QA 회귀 테스트 스위트에 포함.
P3 — 낮음 (백로그)
정의: 외관 문제, 엣지 케이스, 사소한 불편.
대응 기대: 백로그에 추가합니다. 여유가 있을 때 수정하거나, 관련 변경 사항과 묶어서 처리합니다.
예시:
- 툴팁 텍스트에 오타: "Delet" → "Delete".
- 더 이상 사용되지 않는 React 라이프사이클 메서드에 대한 콘솔 경고.
- 뷰포트 너비 768-800px 사이에서 푸터 정렬이 2픽셀 어긋남.
- 콘텐츠가 보인 후에도 로딩 스피너가 200ms 동안 계속됨.
디버그 접근: 전체 디버그 루프가 필요하지 않을 수 있음. 직접 수정과 회귀 테스트로 충분.
5단계 디버그 루프 상세
/debug 워크플로우는 이 단계를 엄격한 순서로 실행합니다. 전 과정에서 MCP 코드 분석 도구를 사용하며, 파일을 직접 읽거나 grep을 쓰지 않습니다.
Step 1: 에러 정보 수집
워크플로우가 요청하는(또는 사용자로부터 받는) 정보:
- 에러 메시지와 스택 트레이스
- 재현 단계
- 예상 vs 실제 동작
- 환경 세부사항
프롬프트에 에러 메시지가 이미 제공되면, 워크플로우는 즉시 Step 2로 진행합니다.
Step 2: 버그 재현
사용 도구: search_for_pattern(에러 메시지나 스택 트레이스 키워드), find_symbol(정확한 함수와 파일 위치).
목표는 코드베이스에서 에러를 위치시키는 것입니다 — 예외가 발생하는 정확한 라인, 잘못된 출력을 생성하는 정확한 함수, 예상치 못한 동작을 유발하는 정확한 조건을 찾습니다.
이 단계는 사용자가 보고한 증상("페이지가 크래시됨")을 코드베이스 수준 위치(src/api/users.ts:47, deleteUser()에서 TypeError 발생)로 변환합니다.
Step 3: 근본 원인 진단
사용 도구: find_referencing_symbols(에러 지점에서 역방향으로 실행 경로 추적).
워크플로우는 에러 위치에서 역방향으로 추적하여 실제 원인을 찾습니다. 확인하는 일반적인 근본 원인 패턴:
| 패턴 | 확인 사항 |
|---|---|
| Null/undefined 접근 | 누락된 null 검사, 필요한 optional chaining, 초기화되지 않은 변수 |
| 레이스 컨디션 | 비순서 완료되는 비동기 연산, 누락된 await, 공유 가변 상태 |
| 누락된 에러 처리 | try/catch 부재, 처리되지 않은 promise rejection, 누락된 error boundary |
| 잘못된 데이터 타입 | 숫자가 예상되는 곳에 문자열, 누락된 타입 변환, 잘못된 스키마 |
| 오래된 상태 | React 상태 업데이트 안 됨, 무효화되지 않은 캐시 값, 오래된 값을 캡처하는 클로저 |
| 누락된 유효성 검사 | 미처리된 사용자 입력, 검증되지 않은 API 요청 바디, 확인되지 않은 경계 조건 |
핵심 원칙: 증상이 아닌 근본 원인을 진단합니다. user.id가 undefined이면, 질문은 "undefined를 어떻게 검사하지?"가 아니라 "이 실행 경로에서 user가 왜 undefined인가?"입니다.
Step 4: 최소 수정 제안
워크플로우가 제시하는 내용:
- 식별된 근본 원인 (코드 추적의 증거 포함).
- 제안된 수정 (필요한 것만 변경).
- 이것이 증상이 아닌 근본 원인을 수정하는 이유 설명.
워크플로우는 사용자가 확인할 때까지 여기서 블록됩니다. 이는 승인 없이 디버그 에이전트가 변경하는 것을 방지합니다.
최소 수정 원칙: 가능한 한 적은 줄을 변경합니다. 리팩토링하지 않고, 코드 스타일을 개선하지 않고, 관련 없는 기능을 추가하지 않습니다. 수정은 2분 이내에 리뷰할 수 있어야 합니다.
Step 5: 수정 적용 및 회귀 테스트 작성
이 단계에서 두 가지 작업이 수행됩니다:
- 수정 구현 — 승인된 최소 변경을 적용합니다.
- 회귀 테스트 작성 — 다음 조건의 테스트:
- 원래 버그를 재현 (수정 없이 테스트가 실패해야 함)
- 수정이 작동하는지 확인 (수정 있으면 테스트가 통과해야 함)
- 같은 버그가 향후 변경으로 재발하는 것을 방지
회귀 테스트는 디버그 워크플로우의 가장 중요한 산출물입니다. 이것 없이는 향후 어떤 변경으로든 같은 버그가 재도입될 수 있습니다.
Step 6: 유사 패턴 스캔
수정이 적용된 후, 워크플로우는 버그를 유발한 동일 패턴을 전체 코드베이스에서 스캔합니다.
사용 도구: search_for_pattern(근본 원인으로 식별된 패턴).
예를 들어, organization이 null인지 확인하지 않고 user.organization.id에 접근하여 버그가 발생한 경우, null 검사 없이 organization.id에 접근하는 모든 다른 인스턴스를 스캔합니다.
서브에이전트 위임 기준 — 다음 경우 debug-investigator 서브에이전트를 스폰합니다:
- 에러가 여러 도메인에 걸쳐 있는 경우.
- 유사 패턴 스캔 범위가 10개 이상 파일.
- 완전한 진단을 위해 깊은 의존성 추적이 필요한 경우.
모든 유사한 취약 위치가 보고됩니다. 확인된 인스턴스는 같은 세션의 일부로 수정됩니다.
Step 7: 버그 문서화
워크플로우가 메모리 파일에 기록하는 내용:
- 증상과 근본 원인
- 적용된 수정과 변경된 파일
- 회귀 테스트 위치
- 코드베이스 전체에서 발견된 유사 패턴
/debug용 프롬프트 템플릿
디버그 워크플로우를 트리거할 때 구조화된 프롬프트를 제공할 수 있습니다:
/debug
Error: TypeError: Cannot read properties of undefined (reading 'id')
Stack trace:
at deleteUser (src/api/users.ts:47:23)
at handleDelete (src/routes/users.ts:112:5)
Steps to reproduce:
1. Log in as admin
2. Navigate to /users
3. Click "Delete" on a user whose organization was deleted
Expected: User is deleted
Actual: 500 Internal Server Error
Environment: Node 22.1, PostgreSQL 16
이 구조가 효과적인 이유:
- 에러 + 스택 트레이스를 통해 2단계에서 코드를 즉시 찾을 수 있습니다 (
search_for_pattern으로 "deleteUser"를 검색하여 함수를 찾고,find_symbol로 정확한 위치를 특정합니다). - 재현 단계에 구체적인 트리거 조건("조직이 삭제된 사용자")이 포함되어 근본 원인(null 외래 키)에 대한 힌트를 줍니다.
- 환경 정보는 버전별 오진을 제거합니다.
더 간단한 버그의 경우 짧은 프롬프트도 효과적입니다:
/debug The login page shows "Invalid credentials" even with correct password
워크플로우가 필요에 따라 추가 세부사항을 요청합니다.
에스컬레이션 시그널
이 시그널은 표준 디버그 루프를 넘어서는 에스컬레이션이 필요함을 나타냅니다:
시그널 1: 같은 수정을 두 번 시도
워크플로우가 수정을 제안하고 적용한 후 같은 에러가 재발하면, 문제가 초기 진단보다 깊습니다. 이를 지원하는 워크플로우(ultrawork, orchestrate, work)에서 Exploration Loop를 트리거합니다:
- 근본 원인에 대한 2-3가지 대안 가설 생성.
- 각 가설을 별도 워크스페이스에서 테스트.
- 결과를 점수화하고 최적의 접근법 채택.
시그널 2: 멀티 도메인 근본 원인
프론트엔드의 에러가 백엔드 변경에 의해 발생하고, 그것이 데이터베이스 스키마 마이그레이션에 의해 발생한 경우. 근본 원인이 도메인 경계를 넘을 때 관련 도메인 에이전트를 포함하도록 /work 또는 /orchestrate로 에스컬레이션합니다.
시그널 3: 재현 환경 부재
버그가 프로덕션에서만 발생하고 로컬에서 재현할 수 없는 경우. 프로덕션 로그를 수집하고, 프로덕션 모니터링에 대한 접근을 요청하며, 수정 시도 전에 계측/로깅 추가를 고려합니다.
시그널 4: 테스트 인프라 장애
테스트 인프라가 깨져 있거나, 누락되었거나, 부적절하여 회귀 테스트를 작성할 수 없는 경우.
조치: 먼저 테스트 인프라를 수정한 다음(또는 oma install로 설정) 디버그 워크플로우로 돌아옵니다.
수정 후 검증 체크리스트
수정과 회귀 테스트를 적용한 후 검증합니다:
- 수정 없이 회귀 테스트가 실패 — 수정을 일시적으로 되돌려 테스트가 버그를 잡는지 확인.
- 수정 적용 시 회귀 테스트가 통과 — 수정을 적용하고 테스트가 통과하는지 확인.
- 기존 테스트가 여전히 통과 — 전체 테스트 스위트를 실행하여 회귀 없음 확인.
- 빌드 성공 — 타입 에러나 임포트 문제를 잡기 위해 프로젝트를 컴파일/빌드.
- 유사 패턴 스캔 완료 — Step 6이 완료되었고 발견된 모든 인스턴스가 수정되거나 문서화됨.
- 수정이 최소적 — 필요한 줄만 변경됨. 관련 없는 리팩토링 포함되지 않음.
- 근본 원인 문서화 — 메모리 파일에 기록: 증상, 근본 원인, 적용된 수정, 변경된 파일, 회귀 테스트 위치, 유사 패턴.
완료 기준
디버그 워크플로우는 다음이 충족되면 완료됩니다:
- 근본 원인이 식별되고 문서화되었음 (증상만이 아님).
- 사용자 승인과 함께 최소 수정이 적용됨.
- 수정 없이 실패하고 수정 적용 시 통과하는 회귀 테스트가 존재.
- 유사 패턴에 대해 코드베이스가 스캔되었고, 확인된 모든 인스턴스가 처리됨.
- 메모리에 버그 리포트가 기록됨.
- 수정 후 모든 기존 테스트가 계속 통과.