AI 어시스턴트가 정확하게 진단할 수 있도록 버그를 어떻게 설명하나요?

Question

Accepted Answer

AI에게 보내는 좋은 버그 리포트는 사람에게 보내는 좋은 버그 리포트와 같습니다. **머릿속에서 문제를 재현할 수 있을 만큼의 맥락**을 주고, 노이즈를 잘라내는 것입니다. AI는 당신이 붙여넣은 것만으로 추론할 수 있습니다 — 모호한 설명은 모호한 추측을 낳습니다.

## 포함할 것

- **정확한 에러 메시지와 전체 stack trace** — 바꿔 말하지 말고 그대로 복사하세요. trace의 파일과 줄 번호가 가장 유용한 단서입니다.
- **관련 코드** — 전체 repo가 아니라 에러를 던지는 함수와 그것을 직접 호출하는 곳.
- **기대 동작 vs 실제 동작** — "X를 기대했는데 Y가 나온다"가 모든 버그 리포트의 핵심입니다.
- **재현 단계** — 그것을 유발하는 정확한 입력 또는 순서.
- **환경/버전** — 언어, framework, 라이브러리 버전(버그는 특정 버전에서만 발생할 수 있음).
- **DB schema 또는 샘플 데이터** — 버그가 query나 데이터 형태와 관련될 때.

## 제외할 것

관련 없는 파일, 전체 config, secret/API key, 그리고 진단을 편향시키는 "X일 것 같다"는 식의 추측. 직감이 아니라 사실을 주세요.

## 약한 리포트 vs 강한 리포트

```text
❌ 약함: "로그인이 망가졌어요, 에러가 납니다. 왜죠?"
   → 에러 텍스트 없음, 코드 없음, 재현 없음 → AI는 추측만 가능

✅ 강함:
   에러(그대로):
     TypeError: Cannot read properties of undefined (reading 'id')
       at getUser (auth.js:42)
   코드(auth.js:40-43):
```

```js
function getUser(token) {
  const session = sessions.find(s => s.token === token); // 찾지 못하면 undefined 반환
  return session.user.id; // 42번 줄: session이 undefined일 때 crash
}
```

```text
   기대: 알 수 없는 token에 대해 null 반환.
   실제: 위 TypeError 발생.
   재현: getUser('expired-token') 호출.
   환경: Node 20, framework 없음.
```

강한 버전이면 AI는 빠진 `undefined` 검사를 바로 짚어내고 guard를 제안할 수 있습니다. 필요한 모든 사실이 화면에 있기 때문입니다.

## 왜 중요한가

AI 어시스턴트는 **당신의 실행 중인 시스템에 접근할 수 없습니다** — 제공된 것만으로 추론합니다. 약한 리포트는 에러, 코드, 환경을 한꺼번에 추측하게 만들고, 잘못된 추측은 한 번의 왕복을 낭비합니다. 강한 리포트(정확한 trace + 관련 코드 + 기대/실제 + 재현 + 버전)는 진단을 집중된 작업으로 바꾸고 보통 첫 시도에 올바른 수정을 얻어냅니다. 간결한 버그 리포트를 쓰는 법을 익히면 스스로도 더 나은 디버거가 됩니다. 묻기 전에 사실을 분리하도록 강제하기 때문입니다.