AI와 함께 디버깅하기
"고쳐 줘"를 더 세게 말하지 말고,
AI에게 주는 정보와 순서를 바꿉니다.
코딩 경험 없어도 됩니다 · 약 40분 · 실습 15분 포함
같은 에러가 반복되면 "고쳐 줘"를 더 세게 말할 게 아니라, AI에게 주는 정보와 순서를 바꿉니다.
아직 고치지 마. 먼저 이 에러의 원인 후보 3개를 가능성 순으로 적고, 각각을 확인할 방법을 알려 줘. 확인 결과를 보고 원인을 고른 다음, 한 번에 하나씩만 고치자.
가장 흔한 원인을 짐작해서 고칩니다.
짐작이 빗나가도 결과를 직접 확인하지 않았으니 "수정했습니다"라고 보고합니다.
다음 요청에서는 또 다른 짐작을 그 위에 얹습니다.
증상만 받으면 AI는 확인하지 않고 고칩니다.
처방 → 재현 방법·에러 원문·기대 vs 실제를 준다
실패한 시도와 틀린 가설이 대화에 쌓이고, AI는 그것을 사실처럼 다시 참고합니다.
처방 → 요약을 들고 새 세션으로
빗나간 수정이 지워지지 않고 남아, 원래 버그 위에 새 버그가 덮입니다. "고칠수록 꼬인다"의 정체입니다.
처방 → 되돌리고, 한 번에 하나씩
가끔이라면 "날 때와 안 날 때 무엇이 달랐나"가 가장 큰 단서입니다. 파일, 시간, PC, 클릭 순서를 비교하세요.
이 문장은 ⑤ 확인 단계에서 그대로 다시 씁니다. 그래서 처음에 적어 두는 겁니다.
그래프가 이상하게 나와요. 고쳐 주세요.
📋 에러는 요약하지 말고 전체를 붙여 넣습니다. 마지막 줄만 보면 원인이 빠질 때가 많습니다.
📸 화면 문제는 스크린샷을 함께 — 말로 설명하기 어려운 어긋남이 그대로 전달됩니다.
monthly.xlsx 를 넣고 [그래프 그리기]를 누르면 막대 그래프가 나와. 기대: 1월~6월 막대 6개 실제: 막대 5개, 3월이 없음. 에러 메시지는 없음 3월 행만 비고 칸에 쉼표가 들어 있어 — 관계있을지도 몰라. 스크린샷 첨부할게. 아직 고치지 말고 원인부터 같이 보자.
아직 고치지 마. 원인 후보 3개를 가능성 순으로 적고, 각각을 어떻게 확인할 수 있는지 알려 줘.
확인도 AI에게 맡길 수 있습니다 — "1번부터 확인해서 결과만 보여 줘".
결과를 보고 원인이 확정된 후보만 ④로 넘깁니다.
● 원인 후보 (가능성 순) 1. 비고 칸의 쉼표 때문에 3월 행의 칸이 밀림 확인: 3월 행만 남긴 파일로 실행해 칸 수 출력 2. 3월 날짜 형식이 달라 읽을 때 빠짐 확인: 읽은 직후 날짜 값을 그대로 출력 3. 그래프 필터 조건이 3월을 제외 확인: 필터 전·후 행 수를 비교
세 군데를 한꺼번에 고치면 무엇이 효과였는지, 새 문제가 어디서 왔는지 알 수 없습니다.
1번 원인만 고쳐 줘. 다른 곳은 건드리지 말고, 무엇을 바꿨는지 3줄로 알려 줘.
"수정했습니다"는 보고일 뿐입니다. ①의 재현 문장대로 다시 해 보고 눈으로 확인합니다.
✅ 증상이 사라졌다 → 커밋해서 세이브 포인트로
❌ 그대로다 → 그 수정은 되돌리고 ③의 다음 후보로
증거를 받는 법은 → ../verification/
로그 = 프로그램이 일하는 중간중간 남기는 메모. 단계마다 값을 찍어 두면, 처음으로 값이 이상해지는 지점이 원인 근처입니다.
고치지 말고, 파일을 읽은 직후 · 계산 직전 · 화면에 그리기 직전에 값을 출력하는 로그를 넣어 줘. 실행 결과를 보고 어디서 틀어지는지 짚어 줘.
로그가 나오는 곳 — 웹페이지는 F12 → Console, 파이썬은 터미널. 원인을 찾은 뒤에는 "디버깅용 로그는 지워 줘".
# 로그 출력 예시 [읽기] 행 수: 6 [읽기] 3월 행 칸 수: 8 ← 나머지는 7 [읽기] 3월 행 금액: "점검" ← 숫자가 아님 [계산] 월별 합계: 1월 412 · 2월 398 · 3월 NaN [그리기] 막대 수: 5 → 읽는 단계에서 이미 칸이 밀렸다. 계산·그리기는 범인이 아니다.
반씩 줄이면 1,000행도 10번 안에 한 행까지 좁혀집니다.
이 CSV를 반으로 나눠 각각 실행해 보고, 에러 나는 쪽을 계속 반으로 줄여서 문제의 행을 찾아 줘. 그 행이 정상 행과 무엇이 다른지 비교해 줘.
🔒 작게 줄인 샘플은 값을 가짜로 바꿔도 에러가 나는지 확인하세요. 그러면 실데이터 없이 AI와 원인을 볼 수 있습니다.
마지막으로 잘 되던 상태(커밋)로 돌아간 뒤, 실패한 방식은 빼고 다시 시작합니다.
마지막 커밋 상태로 되돌려 줘. 방금까지 쓴 방식은 빼고, 다른 방법으로 접근해 보자.
Claude Code는 Esc 두 번(/rewind)으로 이전 지점까지 되감을 수도 있습니다 · ../github/
먼저 지금까지를 파일로 남기고, /clear 또는 새 터미널에서 그 파일만 읽힙니다.
지금까지를 debug-notes.md 로 정리해 줘: 증상 · 재현 방법 · 시도한 것과 결과 · 남은 가설. 코드는 건드리지 마.
debug-notes.md 를 읽고, 이미 실패한 방법은 빼고 원인 후보부터 다시 세워 줘.
막힌 지점에서만 /effort 로 추론 깊이를 올리거나 /model 로 더 큰 모델을 고릅니다.
분석이 끝나면 원래 설정으로 돌아와 구현합니다 — 비싼 설정은 짧게 씁니다.
다른 도구·다른 계열의 모델에게 같은 요약 파일을 주고 두 번째 의견을 받는 것도 같은 방법입니다.
코드는 고치지 마. debug-notes.md 와 관련 파일을 읽고 1) 지금까지의 수정이 왜 실패했는지 2) 근본 원인이 무엇인지 3) 그걸 확인할 방법 을 분석해 줘.
어떤 모델을 언제 고르는지, 비용은 어느 정도인지는 → ../setup/ 의 모델 고르기
C:\Users\kim\work\report\lots.csv/Users/kim/work/report/lots.csvdata/lots.csv상대 경로는 어디서 실행했느냐에 따라 가리키는 곳이 바뀝니다. "파일이 없다"는 에러의 단골 원인입니다.
C:\Users\김철수\내 문서\2026 보고\C:\work\yield-report\어떤 도구는 공백에서 경로를 끊고, 어떤 도구는 한글 경로를 못 읽습니다. 공백이 있으면 경로를 "따옴표"로 감쌉니다.
남이 만들어 둔 부품. No module named … 는 "그 부품이 안 깔렸다", 또는 "깐 곳과 실행하는 파이썬이 다르다".
localhost는 "내 컴퓨터 자신", 포트는 그 안의 문 번호입니다.
이 주소는 터미널에서 서버가 돌고 있는 동안만 열립니다. 터미널을 닫으면 서버도 꺼지고, 다른 사람 PC에서는 열리지 않습니다.
프로그램이 에러와 로그를 적는 창. 웹페이지는 F12 → Console 탭, 파이썬은 실행한 터미널 그 자체입니다.
글자를 숫자로 저장하는 규칙. 한글 Windows 엑셀의 CSV는 흔히 CP949, 요즘 도구의 기본은 UTF-8.
규칙이 다르게 읽으면 �� · ÇÑ±Û 처럼 깨집니다.
원인엑셀 CSV는 CP949인데 코드는 UTF-8로 읽음
처방"인코딩을 확인하고 맞게 읽어 줘. 엑셀로 다시 열 파일은 utf-8-sig 로 저장해 줘"
원인설치 안 함, 또는 설치한 파이썬과 실행한 파이썬이 다름
처방"지금 실행 중인 파이썬이 무엇인지 확인하고, 그 파이썬에 설치해 줘"
원인전에 띄운 서버가 다른 터미널에서 아직 돌고 있음
처방그 터미널에서 Ctrl+C, 또는 "다른 포트로 띄워 줘"
원인상대 경로의 기준 폴더가 다름 · 오타 · 한글·공백 폴더
처방"현재 실행 폴더와 파일의 실제 위치를 둘 다 출력해서 비교해 줘"
원인회사 망의 보안 장비가 통신을 중계해서, 도구가 사내 인증서를 모름
처방사내 IT가 안내하는 인증서·프록시 설정을 적용. 모르면 에러 원문을 들고 헬프데스크로
원인그 파일이 엑셀에서 열려 있음 · 보호된 폴더 · 관리자 전용 위치
처방파일을 닫고 다시. 안 되면 내 작업 폴더로 복사해서 작업
원인사내 DRM으로 암호화된 파일은 프로그램이 직접 못 읽음
처방엑셀·PPT를 실제로 띄워 읽는 방식(xlwings · win32com)으로 → ../agent-skills/
에러 원문을 붙일 때도 보안 약속은 같습니다 — 실데이터·키가 섞이지 않았는지 보고 붙이기 · 회사 정책이 이 자료보다 우선 → ../security/
lot_report.html 에서 lots.csv 를 고르면 표가 안 나와. 콘솔 에러는 이거야: (붙여넣기). 아직 고치지 말고, 두 파일을 읽고 원인 후보 3개와 확인 방법부터 알려 줘.
보너스 — "버그마다 원인·증상·고친 방법을 debug-notes.md 로 정리해 줘"
[파일]로 [동작]을 하면 [결과]가 나와. 기대: … / 실제: … / 에러 원문: (붙여넣기)
아직 고치지 마. 원인 후보 3개를 가능성 순으로, 각각 확인 방법과 함께 알려 줘.
1번 원인만 고쳐 줘. 다른 곳은 건드리지 말고, 바꾼 내용을 3줄로 알려 줘.
고치지 말고, 단계마다 값을 출력하는 로그를 넣어 줘. 실행 결과로 어디서 틀어지는지 짚어 줘.
되는 데이터와 안 되는 데이터를 가장 작게 줄여서, 둘이 무엇이 다른지 찾아 줘.
지금까지를 debug-notes.md 로 정리해 줘: 증상 · 재현 방법 · 시도와 결과 · 남은 가설.
코드는 고치지 마. 지금까지의 수정이 왜 실패했는지와 근본 원인, 그걸 확인할 방법만 분석해 줘.
| No such file | 경로가 틀림 — 기준 폴더 확인 |
| No module named | 부품 없음 — 실행 중인 파이썬 확인 |
| already in use | 서버가 이미 켜져 있음 |
| codec · decode | 인코딩 — CP949 vs UTF-8 |
| CERTIFICATE | 회사 망 인증서 — 끄지 말고 IT |
| Permission · EACCES | 파일이 열려 있거나 막힌 위치 |
"고쳐 줘" 전에 재현 문장과 에러 원문, 기대 vs 실제를 넘기세요.
후보 3개와 확인 방법을 받고, 한 번에 하나만 고치고, 같은 절차로 다시 확인합니다.
로그로 보고, 입력을 줄이고, 되돌리고, 새 세션을 열고, 더 센 눈에게 분석을 맡깁니다.
🔒 보안 약속 3
1. 회사 기밀·실데이터는 사내 승인 도구에서만 — 애매하면 넣지 않는다.
2. API 키·비밀번호는 코드·대화·커밋에 남기지 않는다 — 새어 나갔다면 삭제가 아니라 재발급.
3. 회사 정책이 이 자료보다 우선한다. 자세한 내용은 → ../security/