모든 세미나
SEMINAR · 2026.11 · 01 기본기 · DEBUGGING

고칠수록
꼬일 때

AI와 함께 디버깅하기

"고쳐 줘"를 더 세게 말하지 말고,
AI에게 주는 정보와 순서를 바꿉니다.

코딩 경험 없어도 됩니다 · 약 40분 · 실습 15분 포함

에러 나. 고쳐 줘 ● 원인을 찾아 수정했습니다 ✓ 아직 똑같은 에러야 ● 다른 부분도 수정했습니다 ✓ 이번엔 다른 데까지 깨졌어… ● 죄송합니다. 다시 수정했습니다 ✓
3분 요약 · TL;DR

결론부터 — 이 세 줄이면 됩니다

같은 에러가 반복되면 "고쳐 줘"를 더 세게 말할 게 아니라, AI에게 주는 정보와 순서를 바꿉니다.

  1. 1
    재현 방법과 에러 원문부터 넘기세요언제·무엇을 하면·무엇이 나오는지 한 문장, 빨간 글씨 전체, 기대한 결과와 실제 결과.
  2. 2
    고치기 전에 원인 후보 3개와 확인 방법을 받으세요확인해서 원인을 고른 뒤, 한 번에 하나만 고치고 같은 절차로 다시 확인합니다.
  3. 3
    세 번 헛돌면 판을 바꿉니다로그 심기 · 입력 줄이기 · 되돌리고 다른 접근 · 새 세션 리셋 · 깊이 올려 원인 분석만.
지금 바로 써 보는 프롬프트
아직 고치지 마. 먼저 이 에러의 원인 후보 3개를 가능성 순으로 적고,
각각을 확인할 방법을 알려 줘.
확인 결과를 보고 원인을 고른 다음, 한 번에 하나씩만 고치자.
이럴 때 이 덱을 다시 펼치세요
  • 같은 에러가 두 번 이상 반복될 때
  • 고칠수록 다른 곳이 깨질 때
  • AI가 말하는 에러 용어를 못 알아듣겠을 때
CH 1 · 왜 헛도나

같은 에러가 세 번 나왔다면, 모자란 건 AI의 실력이 아니라 정보입니다

AI가 받은 것

  • "에러 나. 고쳐 줘" — 한 줄
  • 에러 메시지 원문
  • 언제, 무엇을 했을 때 나는지
  • 어떤 파일·데이터로 했는지
  • 원래 기대한 결과가 무엇인지

그래서 AI가 하는 일

가장 흔한 원인을 짐작해서 고칩니다.

짐작이 빗나가도 결과를 직접 확인하지 않았으니 "수정했습니다"라고 보고합니다.

다음 요청에서는 또 다른 짐작을 그 위에 얹습니다.

의사에게 "아파요"만 말하면 처방도 짐작이 됩니다. 어디가, 언제부터, 어떻게 아픈지를 말해야 합니다.
CH 1 · 왜 헛도나

헛도는 이유는 셋 — 정보 부족, 대화 오염, 추측 수정의 누적

🩺 원인 정보가 없다

증상만 받으면 AI는 확인하지 않고 고칩니다.

처방 → 재현 방법·에러 원문·기대 vs 실제를 준다

🌫 대화가 오염됐다

실패한 시도와 틀린 가설이 대화에 쌓이고, AI는 그것을 사실처럼 다시 참고합니다.

처방 → 요약을 들고 새 세션으로

🧱 추측 수정이 쌓였다

빗나간 수정이 지워지지 않고 남아, 원래 버그 위에 새 버그가 덮입니다. "고칠수록 꼬인다"의 정체입니다.

처방 → 되돌리고, 한 번에 하나씩

세 원인 모두 "더 세게 부탁하기"로는 풀리지 않습니다. 주는 정보, 대화의 판, 수정의 순서를 바꿔야 합니다.
이미 배운 것

기본 복구법은 다른 덱에 있습니다 — 이 덱은 그다음 이야기입니다

복구 3문장prompt 에러는 통째로 복붙 · 꼬이면 잘 되던 버전으로 · 반복되면 완전히 다른 방법으로 ../prompt/ →
복구 3단계 · 문장 사전workshop 에러 복붙 → 보여주기·묘사 → 국소 수정·되돌리기. F12 콘솔 여는 법과 "고장 난 앱" 실습 ../workshop/ →
되돌리기github 커밋이 세이브 포인트 — 망가지면 마지막 커밋 상태로 되돌린다 ../github/ →
이 기본기로 대부분은 풀립니다. 이 덱은 그래도 같은 에러가 반복되고, 고칠수록 꼬일 때를 다룹니다.
CH 2 · 디버깅 루프

"고쳐 줘"는 넷째 단계입니다 — 앞의 셋을 먼저

① 재현다시 일으키기언제 · 무엇을 하면 · 무엇이 나오나
② 전달정확히 말하기에러 원문 · 스크린샷 · 기대 vs 실제
③ 가설원인 후보 받기후보 3개와 각각의 확인 방법
④ 하나씩하나만 고치기확인된 원인 하나, 다른 곳은 그대로
⑤ 확인같은 절차로 재확인①을 그대로 다시 — 되면 커밋
안 되면 그 수정은 되돌리고 ③으로
①–③을 건너뛰고 ④부터 시키면, 그것이 바로 추측 수정입니다.
① 재현② 전달③ 가설④ 하나씩⑤ 확인

① 재현 — 언제, 무엇을 하면, 무엇이 나오는지 한 문장으로

언제
어떤 파일·데이터로
"11월 측정 CSV(240행)를 넣었을 때"
무엇을 하면
어떤 순서로 무엇을
"페이지를 열고 파일을 고른 직후"
무엇이 나오나
에러·화면이 어떻게
"표는 비어 있고, 콘솔에 빨간 줄 2개"

매번 나나요, 가끔 나나요?

가끔이라면 "날 때와 안 날 때 무엇이 달랐나"가 가장 큰 단서입니다. 파일, 시간, PC, 클릭 순서를 비교하세요.

재현이 안 되면 고쳤는지도 모릅니다

이 문장은 ⑤ 확인 단계에서 그대로 다시 씁니다. 그래서 처음에 적어 두는 겁니다.

① 재현② 전달③ 가설④ 하나씩⑤ 확인

② 전달 — 해석하지 말고 원문, 그리고 "기대 vs 실제"

😵 겉도는 전달
그래프가 이상하게 나와요. 고쳐 주세요.

📋 에러는 요약하지 말고 전체를 붙여 넣습니다. 마지막 줄만 보면 원인이 빠질 때가 많습니다.

📸 화면 문제는 스크린샷을 함께 — 말로 설명하기 어려운 어긋남이 그대로 전달됩니다.

😎 원인을 찾을 수 있는 전달
monthly.xlsx 를 넣고 [그래프 그리기]를 누르면 막대 그래프가 나와.
기대: 1월~6월 막대 6개
실제: 막대 5개, 3월이 없음. 에러 메시지는 없음
3월 행만 비고 칸에 쉼표가 들어 있어 — 관계있을지도 몰라.
스크린샷 첨부할게. 아직 고치지 말고 원인부터 같이 보자.
① 재현② 전달③ 가설④ 하나씩⑤ 확인

③ 가설 — 고치기 전에 "원인 후보 3개와 확인 방법"을 받습니다

💬 이렇게 요청
아직 고치지 마. 원인 후보 3개를 가능성 순으로 적고,
각각을 어떻게 확인할 수 있는지 알려 줘.

확인도 AI에게 맡길 수 있습니다 — "1번부터 확인해서 결과만 보여 줘".

결과를 보고 원인이 확정된 후보만 ④로 넘깁니다.

● 원인 후보 (가능성 순)

1. 비고 칸의 쉼표 때문에 3월 행의 칸이 밀림
   확인: 3월 행만 남긴 파일로 실행해 칸 수 출력

2. 3월 날짜 형식이 달라 읽을 때 빠짐
   확인: 읽은 직후 날짜 값을 그대로 출력

3. 그래프 필터 조건이 3월을 제외
   확인: 필터 전·후 행 수를 비교
후보마다 확인 방법이 붙어 있으면, 짐작이 아니라 증거로 원인을 고를 수 있습니다.
① 재현② 전달③ 가설④ 하나씩⑤ 확인

④ 하나만 고치고, ⑤ 처음 재현 절차 그대로 확인합니다

④ 한 번에 하나

세 군데를 한꺼번에 고치면 무엇이 효과였는지, 새 문제가 어디서 왔는지 알 수 없습니다.

💬
1번 원인만 고쳐 줘. 다른 곳은 건드리지 말고, 무엇을 바꿨는지 3줄로 알려 줘.

⑤ 같은 절차로 확인

"수정했습니다"는 보고일 뿐입니다. ①의 재현 문장대로 다시 해 보고 눈으로 확인합니다.

✅ 증상이 사라졌다 → 커밋해서 세이브 포인트로

❌ 그대로다 → 그 수정은 되돌리고 ③의 다음 후보로

증거를 받는 법은 → ../verification/

CH 3 · 루프가 안 돌 때

세 번 헛돌면 같은 요청을 반복하지 말고, 판을 바꿉니다

🪵로그 심기보이지 않던 중간값을 화면에 꺼낸다원인이 안 보일 때
✂️입력 줄이기되는 데이터와 안 되는 데이터를 비교한다특정 데이터에서만 날 때
↩️되돌리고 다른 접근쌓인 추측 수정을 걷어낸다고칠수록 꼬일 때
🧼새 세션 리셋요약 파일만 들고 깨끗한 대화로같은 실수를 반복할 때
🧠더 깊이 생각고치지 말고 원인 분석만 맡긴다위를 다 해도 막힐 때
기준은 단순합니다 — 같은 증상으로 세 번 고쳤는데 그대로라면, 네 번째 "고쳐 줘"는 보내지 않습니다.
CH 3 · 🪵 로그 심기

로그를 심으면, 어디서부터 틀어지는지 눈으로 보입니다

로그 = 프로그램이 일하는 중간중간 남기는 메모. 단계마다 값을 찍어 두면, 처음으로 값이 이상해지는 지점이 원인 근처입니다.

💬 이렇게 요청
고치지 말고, 파일을 읽은 직후 · 계산 직전 · 화면에 그리기 직전에 값을 출력하는 로그를 넣어 줘. 실행 결과를 보고 어디서 틀어지는지 짚어 줘.

로그가 나오는 곳 — 웹페이지는 F12 → Console, 파이썬은 터미널. 원인을 찾은 뒤에는 "디버깅용 로그는 지워 줘".

# 로그 출력 예시
[읽기] 행 수: 6
[읽기] 3월 행 칸 수: 8   ← 나머지는 7
[읽기] 3월 행 금액: "점검"   ← 숫자가 아님
[계산] 월별 합계: 1월 412 · 2월 398 · 3월 NaN
[그리기] 막대 수: 5

→ 읽는 단계에서 이미 칸이 밀렸다.
  계산·그리기는 범인이 아니다.
CH 3 · ✂️ 입력 줄이기

잘 되던 데이터와 안 되는 데이터의 차이가 곧 원인입니다

반씩 잘라 범인 행을 찾는다

1,000행
앞 500
정상
뒤 500
에러 → 다시 반으로
…
1행
비고 칸에 줄바꿈

반씩 줄이면 1,000행도 10번 안에 한 행까지 좁혀집니다.

💬 이렇게 요청
이 CSV를 반으로 나눠 각각 실행해 보고, 에러 나는 쪽을 계속 반으로 줄여서 문제의 행을 찾아 줘. 그 행이 정상 행과 무엇이 다른지 비교해 줘.

🔒 작게 줄인 샘플은 값을 가짜로 바꿔도 에러가 나는지 확인하세요. 그러면 실데이터 없이 AI와 원인을 볼 수 있습니다.

CH 3 · ↩️ 되돌리기 · 🧼 새 세션

꼬였으면 쌓인 수정을 걷어내고, 대화도 새로 엽니다

↩️ 되돌리고 다른 접근

마지막으로 잘 되던 상태(커밋)로 돌아간 뒤, 실패한 방식은 빼고 다시 시작합니다.

💬
마지막 커밋 상태로 되돌려 줘. 방금까지 쓴 방식은 빼고, 다른 방법으로 접근해 보자.

Claude Code는 Esc 두 번(/rewind)으로 이전 지점까지 되감을 수도 있습니다 · ../github/

🧼 새 세션 리셋 — 요약 + 파일

먼저 지금까지를 파일로 남기고, /clear 또는 새 터미널에서 그 파일만 읽힙니다.

💬 리셋 전
지금까지를 debug-notes.md 로 정리해 줘: 증상 · 재현 방법 · 시도한 것과 결과 · 남은 가설. 코드는 건드리지 마.
💬 새 세션에서
debug-notes.md 를 읽고, 이미 실패한 방법은 빼고 원인 후보부터 다시 세워 줘.
CH 3 · 🧠 더 깊이 생각시키기

그래도 막히면, 더 깊이 생각하게 해서 "원인 분석만" 맡깁니다

막힌 지점에서만 /effort 로 추론 깊이를 올리거나 /model 로 더 큰 모델을 고릅니다.

분석이 끝나면 원래 설정으로 돌아와 구현합니다 — 비싼 설정은 짧게 씁니다.

다른 도구·다른 계열의 모델에게 같은 요약 파일을 주고 두 번째 의견을 받는 것도 같은 방법입니다.

💬 이렇게 요청
코드는 고치지 마.
debug-notes.md 와 관련 파일을 읽고
1) 지금까지의 수정이 왜 실패했는지
2) 근본 원인이 무엇인지
3) 그걸 확인할 방법
을 분석해 줘.

어떤 모델을 언제 고르는지, 비용은 어느 정도인지는 → ../setup/ 의 모델 고르기

CH 4 · AI의 말 알아듣기

"경로"는 파일의 주소 — 기준점이 다르면 같은 주소도 엉뚱한 곳을 가리킵니다

절대 경로 · 처음부터 끝까지 전체 주소C:\Users\kim\work\report\lots.csv/Users/kim/work/report/lots.csv
상대 경로 · 지금 있는 폴더 기준data/lots.csv

상대 경로는 어디서 실행했느냐에 따라 가리키는 곳이 바뀝니다. "파일이 없다"는 에러의 단골 원인입니다.

피할 폴더 이름 · 한글 · 공백C:\Users\김철수\내 문서\2026 보고\
작업 폴더는 영문 · 공백 없이C:\work\yield-report\

어떤 도구는 공백에서 경로를 끊고, 어떤 도구는 한글 경로를 못 읽습니다. 공백이 있으면 경로를 "따옴표"로 감쌉니다.

Windows는 \, Mac은 / 로 폴더를 나눕니다. 다른 PC에서 받은 코드가 "파일이 없다"고 하면 이것부터 의심합니다.
CH 4 · AI의 말 알아듣기

이 네 단어만 알면 에러 메시지의 절반이 읽힙니다

📦 패키지 · 모듈 module

남이 만들어 둔 부품. No module named … 는 "그 부품이 안 깔렸다", 또는 "깐 곳과 실행하는 파이썬이 다르다".

🔌 localhost · 포트 :8000

localhost는 "내 컴퓨터 자신", 포트는 그 안의 문 번호입니다.

이 주소는 터미널에서 서버가 돌고 있는 동안만 열립니다. 터미널을 닫으면 서버도 꺼지고, 다른 사람 PC에서는 열리지 않습니다.

🖥 콘솔 console

프로그램이 에러와 로그를 적는 창. 웹페이지는 F12 → Console 탭, 파이썬은 실행한 터미널 그 자체입니다.

🔤 인코딩 encoding

글자를 숫자로 저장하는 규칙. 한글 Windows 엑셀의 CSV는 흔히 CP949, 요즘 도구의 기본은 UTF-8.

규칙이 다르게 읽으면 �� · ÇÑ±Û 처럼 깨집니다.

CH 5 · 사내 단골 에러 처방 ①

데이터·환경 에러 넷 — 이름이 보이면 이렇게 부탁합니다

🔤 CSV·엑셀 한글 깨짐 UnicodeDecodeError: 'utf-8' codec can't decode … · 화면에 ���

원인엑셀 CSV는 CP949인데 코드는 UTF-8로 읽음

처방"인코딩을 확인하고 맞게 읽어 줘. 엑셀로 다시 열 파일은 utf-8-sig 로 저장해 줘"

📦 모듈 없음 ModuleNotFoundError: No module named 'pandas'

원인설치 안 함, 또는 설치한 파이썬과 실행한 파이썬이 다름

처방"지금 실행 중인 파이썬이 무엇인지 확인하고, 그 파이썬에 설치해 줘"

🔌 포트 사용 중 Address already in use · EADDRINUSE

원인전에 띄운 서버가 다른 터미널에서 아직 돌고 있음

처방그 터미널에서 Ctrl+C, 또는 "다른 포트로 띄워 줘"

📁 파일을 찾을 수 없음 FileNotFoundError · No such file or directory · ERR_FILE_NOT_FOUND

원인상대 경로의 기준 폴더가 다름 · 오타 · 한글·공백 폴더

처방"현재 실행 폴더와 파일의 실제 위치를 둘 다 출력해서 비교해 줘"

CH 5 · 사내 단골 에러 처방 ②

회사 망·권한·DRM 에러 — 우회하지 말고 정해진 길로

🛡 프록시 · 인증서 CERTIFICATE_VERIFY_FAILED · UNABLE_TO_GET_ISSUER_CERT_LOCALLY · SELF_SIGNED_CERT_IN_CHAIN

원인회사 망의 보안 장비가 통신을 중계해서, 도구가 사내 인증서를 모름

처방사내 IT가 안내하는 인증서·프록시 설정을 적용. 모르면 에러 원문을 들고 헬프데스크로

🔒 권한 거부 PermissionError: [Errno 13] · EACCES · 액세스가 거부되었습니다

원인그 파일이 엑셀에서 열려 있음 · 보호된 폴더 · 관리자 전용 위치

처방파일을 닫고 다시. 안 되면 내 작업 폴더로 복사해서 작업

🔐 DRM 문서 File is not a zip file · 파일이 손상되었습니다 · 알 수 없는 글자

원인사내 DRM으로 암호화된 파일은 프로그램이 직접 못 읽음

처방엑셀·PPT를 실제로 띄워 읽는 방식(xlwings · win32com)으로 → ../agent-skills/

⚠ AI가 "인증서 검증을 끄자"(verify=False, NODE_TLS_REJECT_UNAUTHORIZED=0)거나 "관리자 권한으로 밀어붙이자"고 하면 멈추세요. 에러는 사라져도 보안 구멍이 남습니다.

에러 원문을 붙일 때도 보안 약속은 같습니다 — 실데이터·키가 섞이지 않았는지 보고 붙이기 · 회사 정책이 이 자료보다 우선 → ../security/

🖐 실습 · 15분

고장 난 랏 수율 리포트를 루프대로 살려 봅니다

📦 lab.zip 받기 lot_report.html csv.js lots.csv 전부 합성 데이터 · 버그 3개가 숨어 있습니다
  1. 압축을 푼 폴더에서 Claude Code를 켭니다. lot_report.html 을 브라우저로 열고 lots.csv 를 고릅니다.
  2. ① 재현 ② 전달 — F12 콘솔과 화면을 보고, 재현 문장 + 에러 원문 + 기대 vs 실제로 적어 AI에게 줍니다.
  3. ③ 가설 — "아직 고치지 마. 원인 후보 3개와 확인 방법"을 받고, 확인 결과로 원인을 고릅니다.
  4. ④ 하나씩 ⑤ 확인 — 하나 고칠 때마다 새로고침 → lots.csv 다시 고르기로 확인합니다. 증상이 바뀌면 다시 ①로.
무엇을 배우나
  • 버그가 여러 개일 때 한 번에 하나씩 벗겨 내는 순서
  • 경로 · 인코딩 · 데이터 형식 — 사내에서 가장 흔한 세 종류
💬 첫 문장
lot_report.html 에서 lots.csv 를 고르면 표가 안 나와. 콘솔 에러는 이거야: (붙여넣기). 아직 고치지 말고, 두 파일을 읽고 원인 후보 3개와 확인 방법부터 알려 줘.
🖐 실습 · 완료 기준과 막힐 때

눈으로 이 네 가지가 보이면 끝입니다

완료 기준 — 화면에서 확인
  • 표에 랏 12행, 공정·담당·비고의 한글이 정상
  • 전체 수율 92.8%
  • 저수율 랏 3개 — LOT-2611-05 · 07 · 11 이 빨간 줄
  • F12 콘솔에 빨간 줄 0개

보너스 — "버그마다 원인·증상·고친 방법을 debug-notes.md 로 정리해 줘"

막히면
  • 골라도 아무 반응이 없다 → 콘솔의 첫 빨간 줄 원문을 그대로 붙인다
  • 글자가 깨진다 → "엑셀에서 내보낸 CSV야" 한 줄을 보탠다
  • 몇 행만 숫자가 이상하다 → 이상한 행과 멀쩡한 행을 한 줄씩 붙여 "뭐가 달라?"
  • 세 번 헛돈다 → debug-notes.md 로 요약하고 새 세션
완료 숫자를 AI에게 미리 알려 주지 마세요. "92.8%가 나오게 해 줘"는 답을 맞추는 코드를 부를 수 있습니다.
복붙용 · 디버깅 프롬프트

막힐 때 그대로 붙여 넣는 일곱 문장

① 재현 · ② 전달
[파일]로 [동작]을 하면 [결과]가 나와. 기대: … / 실제: … / 에러 원문: (붙여넣기)
③ 가설 먼저
아직 고치지 마. 원인 후보 3개를 가능성 순으로, 각각 확인 방법과 함께 알려 줘.
④ 하나만
1번 원인만 고쳐 줘. 다른 곳은 건드리지 말고, 바꾼 내용을 3줄로 알려 줘.
🪵 로그
고치지 말고, 단계마다 값을 출력하는 로그를 넣어 줘. 실행 결과로 어디서 틀어지는지 짚어 줘.
✂️ 입력 줄이기
되는 데이터와 안 되는 데이터를 가장 작게 줄여서, 둘이 무엇이 다른지 찾아 줘.
🧼 리셋 전 요약
지금까지를 debug-notes.md 로 정리해 줘: 증상 · 재현 방법 · 시도와 결과 · 남은 가설.
🧠 분석만
코드는 고치지 마. 지금까지의 수정이 왜 실패했는지와 근본 원인, 그걸 확인할 방법만 분석해 줘.
📸 이 장표만 찍어 가세요

같은 에러가 두 번 나면 — 이 순서로

  • 재현 문장 — 언제 · 무엇을 하면 · 무엇이 나오나
  • 에러 원문 전체 + 스크린샷 + 기대 vs 실제
  • "아직 고치지 마. 원인 후보 3개와 확인 방법"
  • 한 번에 하나 → 같은 절차로 재확인 → 되면 커밋, 안 되면 되돌리기
  • 세 번 헛돌면 판 바꾸기 — 로그 · 입력 줄이기 · 되돌리기 · 새 세션 · 깊이 올리기

에러 속 단어 → 뜻

No such file경로가 틀림 — 기준 폴더 확인
No module named부품 없음 — 실행 중인 파이썬 확인
already in use서버가 이미 켜져 있음
codec · decode인코딩 — CP949 vs UTF-8
CERTIFICATE회사 망 인증서 — 끄지 말고 IT
Permission · EACCES파일이 열려 있거나 막힌 위치
정리 · 기억할 것

세 문장만 가져가세요

1. AI는 본 만큼만 고칩니다

"고쳐 줘" 전에 재현 문장과 에러 원문, 기대 vs 실제를 넘기세요.

2. 고치기 전에 원인부터

후보 3개와 확인 방법을 받고, 한 번에 하나만 고치고, 같은 절차로 다시 확인합니다.

3. 세 번 헛돌면 판을 바꿉니다

로그로 보고, 입력을 줄이고, 되돌리고, 새 세션을 열고, 더 센 눈에게 분석을 맡깁니다.

다음 단계

고친 다음은 — 증거를 받고, 대화를 관리하고, 세이브 포인트를 남깁니다

🔒 보안 약속 3

1. 회사 기밀·실데이터는 사내 승인 도구에서만 — 애매하면 넣지 않는다.

2. API 키·비밀번호는 코드·대화·커밋에 남기지 않는다 — 새어 나갔다면 삭제가 아니라 재발급.

3. 회사 정책이 이 자료보다 우선한다.  자세한 내용은 → ../security/