버그를 Codex로 디버깅하는 법: 증상부터 원인까지 추적하게 만드는 지시 흐름

1. 에러 메시지를 사건 기록으로 바꾸기

Codex에게 에러가 나요라고만 말하면 가능한 원인을 넓게 나열하기 쉽습니다. 디버깅의 첫 단계는 에러 문장을 복사하는 일이 아니라, 버그를 재현 가능한 사건으로 바꾸는 것입니다.

재현 조건을 먼저 적기

다음 네 가지를 한 덩어리로 전달하세요.

• 재현 순서: 어떤 화면에서 무엇을 몇 단계로 실행했는가
• 입력값: 정상 입력과 실패한 입력의 차이는 무엇인가
• 실제 결과: 에러 문구, HTTP 상태 코드, 로그, 화면 변화를 그대로 기록
• 기대 결과: 사용자가 보았어야 할 정상 동작

예를 들어 “로그인이 안 됨”보다 “이미 가입한 이메일로 로그인 버튼을 누르면 로딩이 끝나지 않고, 서버 로그에는 Invalid session이 남는다. 새 이메일 가입은 정상이다”가 훨씬 좋은 출발점입니다. 민감한 토큰과 개인정보는 지운 뒤 공유하세요.

조코헌트에는 현재 255개 프로덕트가 출시되어 있습니다. 혼자 만든 제품일수록 기능과 실행 환경이 제각각이므로, 에러 한 줄보다 재현 조건을 남기는 습관이 시간이 지날수록 큰 차이를 만듭니다.


2. Codex에게 가설을 세우고 검증하게 하기

원인을 바로 고치라고 하면 첫 번째로 그럴듯한 지점을 수정할 수 있습니다. 대신 “가능한 원인 → 확인할 파일과 로그 → 판정 기준”의 순서를 지시하세요.

가설의 범위를 좁히는 질문

다음 질문을 프롬프트에 포함하면 추측이 줄어듭니다.

1. 이 증상을 만들 수 있는 원인을 2~3개로 분류해라.
2. 각 가설을 확인할 파일, 함수, 로그 위치를 제시해라.
3. 가장 적은 변경으로 확인할 수 있는 검증부터 실행해라.
4. 검증 결과가 가설을 지지하는지 반박하는지 설명해라.
5. 근거가 부족하면 수정하지 말고 추가로 필요한 정보를 질문해라.

특히 “관련 파일을 모두 고쳐라”보다 “먼저 읽고, 원인 후보와 근거를 보고한 뒤 수정 여부를 물어라”가 안전합니다. 코드 변경 전후의 차이를 확인하려면 Codex로 코드 리뷰 받기: 혼자 개발할 때 리뷰어를 대신하는 활용 패턴의 diff 중심 점검 방식도 함께 적용해볼 수 있습니다.

로그는 결과가 아니라 관찰 도구로 쓰기

로그를 무작정 추가하면 오히려 흐름이 복잡해집니다. 어떤 값이 어느 경계에서 사라졌는지 확인할 수 있도록 요청하세요. 예를 들면 “요청 진입, 인증 판정, DB 조회 직전과 응답 직전에 식별자와 상태만 기록하고 비밀값은 출력하지 마라”처럼 범위를 정합니다.

3. 바로 복사하는 디버깅 프롬프트

아래 템플릿의 대괄호 부분만 채워 사용하세요.

다음 버그를 원인부터 검증해줘.

[증상]
- 실제 결과: 
- 에러 메시지/로그: 
- 발생 빈도와 시점: 

[재현 방법]
1. 
2. 
3. 
- 실패 입력:
- 성공하는 입력 또는 비교 조건:

[기대 동작]
- 사용자가 보아야 할 결과:
- 현재 동작과 다른 점:

[범위]
- 관련 페이지/API/함수:
- 우선 읽을 파일:
- 최근 변경 사항:

작업 순서:
1) 코드를 먼저 읽고 원인 후보를 2~3개로 정리한다.
2) 각 후보를 뒷받침하거나 반박하는 근거를 파일과 코드 줄 기준으로 설명한다.
3) 가장 작은 검증 방법을 제안하고 실행한다.
4) 원인이 확인된 경우에만 최소 수정안을 만든다.
5) 수정 후 재현 절차와 회귀 테스트를 실행하고 결과를 요약한다.
추측으로 빈칸을 채우지 말고, 필요한 정보가 있으면 질문한다.

이 프롬프트의 핵심은 문장이 멋진가가 아니라 작업 순서가 고정되어 있다는 점입니다. 프로젝트 규칙이나 테스트 명령을 별도 문서로 관리한다면 AGENTS.md 작성법: Codex가 프로젝트 규칙을 잊지 않게 만드는 실전 구조도 참고하세요.


4. 수정 완료를 “테스트 통과” 이상으로 정의하기

에러가 사라졌다고 디버깅이 끝난 것은 아닙니다. 원래 실패한 경로와 주변 경로가 함께 안전해졌는지 확인해야 합니다.

수정 뒤 확인할 체크리스트

• 처음 보고된 재현 절차가 더 이상 실패하지 않는다.
• 성공하던 입력이 계속 정상 동작한다.
• 빈 값, 잘못된 형식, 권한 부족 같은 경계 조건을 확인했다.
• 같은 문제가 다른 화면이나 API에도 반복되지 않는지 검색했다.
• 수정 이유와 재현·검증 명령을 커밋 또는 이슈에 남겼다.

테스트가 없다면 Codex에게 큰 테스트 묶음을 만들라고 하기보다, 이번 버그를 고정하는 최소 재현 테스트 하나부터 요청하세요. 레거시 영역을 건드린다면 레거시 코드 리팩토링을 Codex에게 안전하게 맡기는 절차: 테스트 먼저, 작게 쪼개기처럼 변경 단위를 작게 유지하는 편이 좋습니다.

5. 출시 후에는 버그 보고 양식도 제품의 일부다

조코헌트 출시 프로덕트 중 첫 24시간 안에 업보트나 댓글 같은 반응을 하나라도 받은 경우는 60%입니다. 반응이 빠르게 들어오는 제품이라면 “안 돼요”라는 제보를 기다리기보다, 재현에 필요한 정보를 받는 질문을 미리 준비해두는 것이 유리합니다. 다만 댓글을 받은 프로덕트는 35%이므로, 모든 사용자가 자세한 보고서를 남긴다고 기대하기는 어렵습니다.

문의가 들어오면 다음 세 문장으로 다시 물어보세요.

• 어떤 작업을 하다가 문제가 발생했나요?
• 문제가 난 직전까지의 순서를 적어줄 수 있나요?
• 기대한 결과와 실제 결과가 각각 무엇인가요?

이 답변을 위 프롬프트의 입력으로 옮기면, 감정적인 오류 신고가 조사 가능한 디버깅 자료로 바뀝니다. Codex를 빠른 수정 도구로만 쓰지 말고, 관찰하고 가설을 검증하는 조사 파트너로 사용해보세요.