AI로 버그 찾는 5단계 디버깅 워크플로
준비물과 예상 소요 시간
- 이 글 주제 관련 도구 계정 또는 설치본
- 연습용 샘플 프로젝트 또는 빈 페이지 1개
- 예상 시간: 40~90분 (처음 기준)
버그에 하루를 쓰는 흔한 이유는 수정보다 재현과 범위 축소가 안 되어서입니다. AI는 그 단계를 대신 코딩해 주기보다, 가설을 빠르게 나열하고 체크리스트를 만드는 보조로 쓸 때 안전합니다.
5단계 워크플로
1단계 — 재현 조건을 문장으로 고정
환경: OS, 브라우저/런타임 버전언제: 로그인 직후 / 특정 API 호출 시입력: ...기대: ...실제: ...빈도: 항상 / 가끔재현 안 되면 AI에게 코드를 보여 줘도 추측만 늘어납니다.
2단계 — 최소 실패 단위로 줄이기
관련 없는 컴포넌트·피처 플래그를 끄고, 에러 나는 함수·요청 1개까지 축소.
3단계 — AI에 넘기는 패키지 구성
역할: 디버깅 파트너. 추측과 확인된 사실을 구분해라.재현 절차:[1단계 문장]에러 전문:[스택 트레이스]관련 코드:[최소 파일]이미 시도한 것:[목록]요청:1) 가능 원인 3개 (가능성 순)2) 각 원인을 5분 안에 확인하는 방법3) 수정 코드는 확인 후에만4단계 — 한 번에 한 가설만 검증
로그 한 줄, 브레이크포인트 하나, 실험 하나. 동시에 3곳을 고치면 원인 불명.
5단계 — 회귀 방지
- 가능하면 테스트 1개 추가
- ERR 노트(포스트 6)에 기록
- “왜 탐지가 늦었는지” 한 줄
짧은 사례 (형식 예시)
- 증상: API 201 응답 후 UI가 빈 목록
- 축소: 네트워크 탭에서 응답 배열이 비어 있음
- 원인: 클라이언트 필드명
userIdvs 서버user_id - AI 역할: 스키마 불일치 후보를 빨리 지적
- 방지: 타입 공유·계약 테스트
하지 말 것
- 프로덕션 시크릿이 포함된 로그 전체 업로드
- “코드 전체 다시 짜줘”로 원인 미상 덮기
- 테스트 없이 대규모 리팩터
FAQ
Q. AI가 틀린 원인을 확신해요. 프롬프트에 “확인 전에는 단정 금지”를 넣고, 실험으로 기각하세요.
Q. 레이스 컨디션·플래키 테스트? 재현 빈도·스레드/비동기 단서를 명시. 필요하면 로그 타임스탬프를 붙이세요.
단계별 시간 배분 예 (90분 예산)
| 단계 | 시간 | 산출물 |
|---|---|---|
| 재현 문장 | 15 | 재현 절차 |
| 축소 | 20 | 최소 파일 목록 |
| AI 가설 | 10 | 원인 3 |
| 검증 | 30 | 기각/채택 |
| 수정+테스트 | 15 | 패치 |
로그와 함께 넘기는 포맷
[ENV] node 20 / postgres 16[REQ] POST /api/login[RES] 500 body: ...[LOG] timestamp ...[CODE] auth.ts L40-80재발 방지 티켓 템플릿
- 증상 / 루트코즈 / 수정 / 테스트 / 모니터링
가설 표
| 가설 | 확인 방법 | 결과 |
|---|---|---|
| 환경변수 누락 | 시작 로그에 키 존재 | |
| 버전 불일치 | lockfile vs 런타임 | |
| 레이스 | 재현 스크립트 반복 |
추가 FAQ
Q. 프로덕션만 재현돼요. 가능하면 스테이징에서. 불가 시 개인정보 제거한 로그 샘플과 버전 해시만 공유.
주말 실습: 과거 버그 사후 분석
최근에 고생한 버그 하나를 5단계 형식으로 재작성한다. 그때 AI에 던졌던 질문과, 지금이라면 붙였을 최소 재현 코드를 비교한다.
현장 시나리오: “가끔 500” API
증상은 간헐적 500, 로그에는 타임아웃과 null 참조가 섞여 있습니다. 이 경우 AI에게 전체 레포를 맡기면 추측이 폭증합니다.
권장 진행:
- 재현 비율을 적는다 (예: 10회 중 3회).
- 동일 요청을 curl로 고정 페이로드 실행한다.
- 성공/실패 응답 바디를 나란히 저장한다.
- AI 프롬프트에는 실패 로그 1건 + 관련 함수 1개만 넣는다.
- 가설이 “DB 풀 고갈”이면 풀 메트릭을 보고, 코드 리팩터는 그다음이다.
수정 후에도 같은 curl을 20회 돌려 비율이 줄었는지 확인합니다. “느낌상 해결”은 회귀의 시작입니다.
추가 팁: 이슈 티켓에 재현 curl을 그대로 붙여 두면 다음 사람이 AI 없이도 같은 길을 갑니다.
한계와 현실적인 기대
디버깅 속도는 똑똑한 추측이 아니라 재현 가능한 실험 횟수에서 납니다. AI는 실험 설계를 도와주지만, 결과 해석과 롤백 결정은 개발자 몫입니다. 로그에 개인정보가 있으면 마스킹 전에 외부 모델로 보내지 마세요. 해결 후에는 같은 증상이 모니터링에 잡히는지, 테스트가 재발을 막는지 한 줄씩만 추가해도 팀 전체 시간이 줄어듭니다.
실습 체크리스트 (AI 디버깅 5단계)
- 재현 절차를 3줄 이상 적었는가
- 에러 메시지·스택을 그대로 수집했는가
- 가설을 1개만 먼저 검증했는가
- 수정 후 회귀 테스트 또는 재현 경로를 돌렸는가
- ERR 노트에 원인·해결을 남겼는가
가설 검증 미니 실험 설계
디버깅이 길어지는 이유는 수정이 많아서가 아니라 가설이 병렬이기 때문입니다. 한 번에 하나의 변수만 바꿉니다.
실험 기록 템플릿:
- 가설:
- 바꿀 것 하나:
- 기대:
- 실제:
- 다음 가설:
AI를 쓰면 안 되는 순간
- 재현 절차가 아직 없을 때
- 프로덕션 시크릿이 로그에 포함돼 있을 때
- 이미 원인 후보가 너무 많아 질문 자체가 불명확할 때
이때는 먼저 로컬에서 입력을 최소화한 재현 스크립트를 만드세요. AI는 그 스크립트와 로그를 받은 뒤에 쓰는 편이 정확합니다.
회귀 범위를 정하는 법
버그 수정 PR에는 “이 시나리오는 반드시 통과” 목록을 3개만 적어도 리뷰 품질이 올라갑니다. 자동 테스트가 없으면 수동 체크리스트라도 남기세요. 같은 증상이 두 번 재발하면 탐지(테스트/알람) 를 백로그에 올리는 것이 다음 생산성 투자입니다.
이 글을 끝내면 할 수 있는 것
- 재현→수집→가설→수정→회귀의 5단계를 순서대로 한다.
- AI에게 추측 금지·근거 인용을 요구한다.
- 해결을 ERR 노트로 남긴다.
5단계 한눈에
- 재현: 환경, 입력, 빈도
- 수집: 로그, 스택, 최근 변경
- 가설 1개: 동시에 여러 개 고치지 않기
- 최소 수정: 원인에 가장 가까운 한 곳
- 회귀: 같은 시나리오 + 인접 케이스
AI에 줄 때 템플릿
재현 절차:1.기대 결과:실제 결과:최근 변경:로그:질문: 가능한 원인 3개와 각각 검증 방법. 추측 코드 전체 재작성 금지.트러블슈팅
| 증상 | 원인 | 해결 |
|---|---|---|
| AI가 코드 전체를 재작성 | 프롬프트 과광 | “최소 diff” 명시 |
| 로컬만 실패 | 환경 차이 | 버전·env 비교 |
| 간헐 실패 | 레이스/시간 | 재현 스크립트·시드 |
| 수정 후 다른 곳 파괴 | 회귀 생략 | 체크리스트 5단계 |
| 같은 버그 재발 | 기록 없음 | ERR 노트 의무 |
FAQ 보강
Q. printf 디버깅이 나쁘나요? 빠른 가설 검증엔 유효합니다. 남긴 로그는 제거하거나 레벨을 낮추세요.
Q. 프로덕션 핫픽스에도 5단계? 축약해도 재현·회귀는 남기세요.
현장에서 바로 쓰는 AI 디버깅 운영 노트
이 절은 AI 디버깅 본문을 읽은 뒤 다음 영업일 안에 실행할 때 참고하는 운영 메모입니다. 도구 이름보다 중요한 것은 반복 가능한 순서와 실패 기록입니다. 처음 한 주는 완벽한 세팅보다 ‘최소 성공 1회’를 목표로 하세요. 성공 기준을 숫자나 체크박스로 적어 두면 나중에 회고할 때 감이 아니라 데이터로 판단할 수 있습니다.
첫 48시간 실행 계획 (AI 디버깅)
- 준비물 절을 보고 계정·설치·권한을 먼저 끝낸다. 본론 중간에서 설치하면 흐름이 끊긴다.
- 본문의 핵심 절차 중 가장 작은 단위 하나만 끝까지 재현한다.
- 트러블슈팅 표에서 해당 증상 행을 찾아 해결을 적용하고, 없으면 새 행을 메모한다.
- FAQ에서 비용·보안·팀 도입 질문을 읽고 내 환경에 해당하는지 표시한다.
- 실습 체크리스트를 인쇄하거나 이슈 한 장에 옮겨 완료 표시를 남긴다.
- 동료가 있다면 5분 데모를 보여 주고, 설명 중 막힌 지점을 문서에 보완한다.
품질을 유지하는 주간 루틴
AI 디버깅 관련 설정과 문서는 한 번 만들고 방치하면 금방 낡습니다. 매주 15분만 투자해 다음을 점검하세요. 지난주에 새로 생긴 예외 상황, 팀원이 물은 질문, 실패한 명령, 유료 결제 여부, 보안 정책 변경 여부입니다. 변경이 있으면 본문 요약이 아니라 체크리스트와 트러블슈팅 표를 먼저 고칩니다. 긴 서론을 고치는 것보다 표 한 줄이 다음 독자를 더 많이 구합니다.
혼자 일할 때와 팀에서 쓸 때의 차이
개인 사이드 프로젝트에서는 속도와 실험이 우선일 수 있습니다. 하지만 팀 저장소·고객 데이터·공통 인프라가 걸리면 AI 디버깅 사용 방식이 달라져야 합니다. 권한, 감사 로그, 승인 단계, 공유 채널 공지 같은 사회적 절차가 기술적 절차만큼 중요합니다. 모호하면 보수적으로 선택하세요. 막힌 시간을 줄이려다 사고를 키우는 경우가 더 비쌉니다. 팀 합의 문장이 없다면 이 글의 체크리스트를 복사해 ‘우리 팀 버전’ 헤더만 바꿔 공유하는 것으로 충분합니다.
측정 지표 제안
| 지표 | 측정 방법 | 해석 |
|---|---|---|
| 첫 성공까지 시간 | 타이머 | 온보딩 문서 개선 신호 |
| 주간 재사용 횟수 | 간단한 해시 체크 | 습관 정착 여부 |
| 실패 재발 | 같은 증상 메모 | 트러블슈팅 보강 필요 |
| 도움 요청 횟수 | 슬랙/구두 | 문서 공백 위치 |
| 중단 결정 | 2주 후 유지/폐기 | 도구 과잉 방지 |
폐기 기준 (중요)
AI 디버깅가 팀에 안 맞을 수도 있습니다. 실패를 인정하는 기준을 미리 정하세요. 예를 들어 2주 동안 핵심 절차를 3회 이상 재현하지 못했거나, 보안 검토에서 막혔거나, 기존 도구 대비 명확한 이득이 없으면 중단이 올바른 결정입니다. 중단할 때도 설정 내보내기·권한 회수·문서 보관 위치를 남겨 두면 다음에 재도전할 때 비용이 줄어듭니다. 생산성 글의 목적은 도구 수집이 아니라 더 적은 마찰로 같은 품질의 결과를 내는 것입니다.
독자가 자주 놓치는 디테일
- 버전을 안 적으면 한 달 뒤 같은 글이 거짓이 됩니다. 환경 절에 버전을 남기세요.
- 스크린샷만 있고 텍스트 명령이 없으면 접근성과 검색성이 떨어집니다.
- 성공 로그만 남기고 실패 로그를 지우면 학습이 사라집니다.
- 다른 글과 주제가 비슷할 때는 이 글의 완료 정의만 다시 읽고 범위를 지키세요.
- 공유 전에 시크릿·사내 URL·고객명이 있는지 검색하세요.
정리
AI 디버깅의 속도는 모델이 아니라 재현 문장과 최소 코드에서 납니다.
참고: 언어별 디버거 공식 문서(VS Code debugging 등)
글 공유
이 글이 도움이 되셨다면 다른 사람들과 공유해 주세요!
