좋은 버그 리포트 작성법 (AI 또는 개발자를 위해)

좋은 버그 리포트는 다른 사람(개발자든 AI든)이 내가 본 것과 같은 문제를 보게 해 주며, 내게 추가로 질문할 필요가 없게 합니다. 구체적인 제목, 재현하는 정확한 단계, 기대한 결과, 실제로 일어난 일, 단어 그대로 옮긴 오류 메시지, 그리고 발생 위치(어느 페이지, 브라우저, 기기, 사용자)가 필요합니다. 버그 하나당 리포트 하나를 쓰고, 도움이 되면 스크린샷을 붙이세요.

대부분의 버그는 고치는 것보다 이해하는 데 시간이 더 걸립니다. 명확한 리포트는 이해하는 부분을 줄여 줍니다. AI 도구에서는 이것이 더 중요합니다. AI는 "결제가 이상해"라는 말이 무슨 뜻인지 되물을 수 없으므로 추측하고, 잘못된 추측은 다른 것을 망가뜨릴 수 있습니다.

템플릿

이것을 복사해서 채우세요.

제목: [무엇이 잘못되었고, 어디서] — 예: "예약 폼이 오후 6시 이후 시간을 거부함"

재현 단계:
1. ...
2. ...
3. ...

기대한 결과: [일어나야 하는 것]
실제 결과: [대신 일어난 것]

오류 메시지: [정확한 문구, 있다면]
발생 위치: [페이지/URL, 브라우저, 기기, 로그인한 사용자]
발생 빈도: [매번 / 가끔 / 한 번]
스크린샷 또는 녹화: [첨부]

이 가이드의 나머지 부분에서 각 항목을 설명합니다.

1단계: 먼저 재현하기

쓰기 전에 버그를 다시 일으켜 보세요. 어떤 단계가 중요한지, 매번 발생하는지 알 수 있습니다.

• 깨끗한 상태에서 시작하세요. 새로고침하거나, 로그아웃했다가 다시 로그인하세요.
• 클릭한 것과 입력한 내용을 하나씩 적으세요.
• 버그를 일으키는 가장 짧은 경로를 찾으세요.
• 다른 브라우저나 다른 계정으로도 해 보세요. 한 사용자에게만 일어난다면 중요한 단서입니다.

이에 대해 더 알아보려면 AI로 만든 앱을 디버깅하는 법을 보세요.

2단계: 구체적인 제목 쓰기

제목은 무엇이 어디서 잘못되었는지 말해야 합니다. 목록을 훑는 사람이 어떤 버그인지 알 수 있어야 합니다.

3단계: 정확한 단계 나열하기

번호를 매기세요. 있는 그대로 쓰세요. 어느 페이지, 어느 버튼, 무엇을 입력했는지 적으세요.

1. 고객 계정으로 로그인합니다(테스트 계정: customer@example.com).
2. "스타터 키트"를 장바구니에 담습니다.
3. 할인 코드 WELCOME10을 입력하고 적용을 클릭합니다.
4. 결제를 클릭합니다.

"코드를 넣고 결제해 보세요"라고만 쓰면 중요한 세부 사항이 빠집니다. 어떤 사용자인지, 어떤 상품인지, 어떤 코드인지, 코드가 먼저 적용되었는지 같은 것들입니다.

4단계: 기대한 결과 대 실제 결과

이것이 리포트의 핵심입니다. 둘 다 쓰세요. 둘의 차이가 바로 버그이기 때문입니다.

• 기대한 결과: 결제 페이지가 열리고, 총액에 10% 할인이 표시됩니다.
• 실제 결과: 버튼에 1초 동안 로딩 표시가 뜬 뒤 아무 일도 일어나지 않습니다. 할인 코드 없이 결제하면 정상 작동합니다.

"기대한 결과"가 없으면 읽는 사람은 그 동작이 잘못되었다는 것을 모를 수 있습니다. "실제 결과"가 없으면 무엇을 찾아야 하는지 모릅니다.

5단계: 오류를 정확히 복사하기

오류 메시지는 원인에 이르는 가장 빠른 길입니다. 텍스트로 복사하고, 단어 그대로 옮기세요. 바꿔 쓰지 마세요.

찾는 곳은 다음과 같습니다.

• 화면에서: 앱이 보여 주는 모든 메시지.
• 브라우저 콘솔: 개발자 도구(F12, 또는 우클릭 → 검사)를 열고 콘솔 탭에서 빨간 줄을 찾으세요.
• 네트워크 탭: 개발자 도구에서 실패한 요청을 찾고 URL과 상태 코드를 적으세요(예: POST /api/checkout → 500).
• 서버 로그, 접근 권한이 있다면.

TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 같은 한 줄이 문제를 곧바로 가리키는 경우가 많습니다.

6단계: 맥락 추가하기

• 어디서: 페이지 URL, 환경(미리보기, 스테이징, 실서비스).
• 누가: 어떤 사용자나 역할인지 — 관리자, 멤버, 로그아웃 상태.
• 기기와 브라우저: "iPhone의 Safari"와 "Windows의 Chrome"은 차이가 날 수 있습니다.
• 데이터: 레코드에 특이한 점 — 아주 긴 텍스트, 특수 문자, 많은 항목 수.
• 언제 시작되었는지: "어제 할인 코드를 바꾼 뒤부터"는 아주 중요한 정보입니다.
• 얼마나 자주인지: 매번인지, 열 번 중 한 번인지.

7단계: 보여 주기

문제 부분에 동그라미를 친 스크린샷이나 짧은 화면 녹화는 모호함을 없애 줍니다. 특히 레이아웃 버그에 그렇습니다. AI 도구가 이미지를 받는다면 하나를 첨부하세요. 키나 다른 사람의 데이터 등 비공개 정보는 잘라내세요.

AI 빌더에게 버그 리포트 쓰기

같은 구조가 그대로 프롬프트가 됩니다. 두 가지를 더하면 도움이 됩니다.

• 바뀌면 안 되는 것을 말하세요. 수정이 새로운 문제를 일으키지 않도록요.
• 수정을 작성하는 데서 끝내지 말고, 수정이 맞는지 검증하도록 요청하세요.

고객으로 로그인해서 "스타터 키트"를 장바구니에 담고 코드 WELCOME10을 적용한 뒤 결제를 클릭하면 아무 일도 일어나지 않아. 기대한 결과: 결제 페이지가 열리고 총액에서 10%가 할인되어야 해. 실제 결과: 잠깐 로딩 표시가 뜨고 그다음 아무것도 없어. 네트워크 탭에서 POST /api/checkout이 500을 반환했어. 코드 없이 결제하면 정상이야. 원인을 찾아서 고치되, 코드가 없는 주문의 가격 계산 방식은 바꾸지 마. 그다음 퍼센트 코드, 정액 코드, 코드 없음 세 경우로 결제를 확인해 줘.

원인이 확실하지 않다면 먼저 진단을 요청하세요.

아직 코드를 바꾸지 마. 이 리포트를 기준으로, 가능성이 높은 원인은 무엇이고 각각을 확인하려면 무엇을 해야 하는지 알려 줘.

흔한 실수

• "고장 났어." 단계도, 기대한 결과도 없어서 무엇을 해야 할지 알 수 없습니다.
• 한 리포트에 여러 버그. 일부는 고쳐지고 나머지는 잊힙니다.
• 바꿔 쓴 오류 메시지. "정의되지 않은 무언가"라고 쓰면 쓸모 있는 부분이 사라집니다.
• 사용자나 역할을 빠뜨림. 많은 버그는 관리자나 신규 사용자에게만 일어납니다.
• 문제 대신 원하는 수정 방법만 설명함("널 체크를 추가해 줘")
• 스크린샷이나 붙여 넣은 로그에 비밀 값을 포함함.

체크리스트

• 버그를 재현했고, 가장 짧은 단계를 찾았습니다.
• 제목이 무엇이 어디서 잘못되었는지 말합니다.
• 단계는 번호가 매겨져 있고 있는 그대로입니다.
• 기대한 결과와 실제 결과를 둘 다 썼습니다.
• 오류 메시지를 정확히 복사했고, 실패한 요청과 상태 코드를 포함했습니다.
• 페이지, 환경, 사용자, 기기, 브라우저를 포함했습니다.
• 얼마나 자주 발생하는지, 언제 시작됐는지 적었습니다.
• 비공개 데이터를 지운 스크린샷이나 녹화를 첨부했습니다.
• 리포트 하나에 버그 하나만 담았습니다.

Mythex 에이전트에 버그 보고하기

Mythex 프로젝트에서는 리포트 자체가 프롬프트입니다. 몇 가지 기능이 도움이 됩니다.

• 스크린샷 첨부. 미리보기나 오류 화면을 메시지당 최대 5개 파일까지 첨부할 수 있습니다.
• **/fix**는 에이전트가 버그 수정에 집중하게 합니다. 계획 모드에서는 편집하기 전에 조사하게 할 수 있습니다.
• **/test**는 에이전트가 미리보기에서 흐름을 직접 재현하고 본 내용을 보고하게 합니다.
• 이 시점으로 되돌리기는 상황을 더 나쁘게 만든 수정을 취소합니다.

문서의 프롬프트로 디버깅하기 페이지도 같은 단계, 기대한 결과, 실제 결과 구조를 사용합니다. 그 주변의 수정과 확인 과정은 AI로 만든 앱을 반복해서 개선하는 법을 참고하세요.

자주 묻는 질문