AI로 코드나 문서를 만들다 보면 막히는 때가 옵니다. 오류가 나거나, 코드가 무엇을 하는지 모르겠거나, 결과가 미덥지 않습니다. 요즘은 Claude Code나 Codex 같은 코딩 에이전트가 코드를 직접 실행하고 오류를 읽어 고치므로, 사람이 오류 메시지를 일일이 복사해 붙이지 않아도 됩니다.
그래도 사람이 정해 줘야 하는 것은 남습니다. 무엇을 하려던 것인지, 바꾸면 안 되는 것은 무엇인지, 어떤 자료는 열면 안 되는지, 결과가 맞는지 무엇으로 확인할지입니다. 이 안내서는 막혔을 때 이 내용을 담아 다시 요청하는 방법을 다룹니다.
- 막힘을 오류·이해·수정·검산·방향 문제로 구분할 수 있습니다.
- 코딩 에이전트에게 원인 확인, 변경 범위, 금지 작업, 검산 기준을 프롬프트로 줄 수 있습니다.
- 실제 자료 대신 합성 재현 예시로 문제를 다시 일으킬 수 있습니다.
- 받은 답이 원인을 좁히고 검산 방법을 제시하는지 판단할 수 있습니다.
AI에게 맡기는 프롬프트
코딩 에이전트가 오류를 고치다 같은 수정을 되풀이하거나, 고칠수록 결과가 달라질 때 작업을 멈추고 다시 주는 프롬프트입니다. 실제 업무 자료가 없는 작업 폴더에서 씁니다.
[하려던 일] (예: sample 폴더의 합성 출동 CSV 3개를 합쳐 유형별 표를 만듭니다) [바꾸면 안 되는 것] (예: 원본 CSV 파일, 표의 열 이름, 기존 집계 기준) [작업 규칙] - 코드를 고치기 전에 원인 가설과 확인할 명령을 먼저 보여 주고 제 답을 기다려 주세요. - 원인과 관련된 부분만 고쳐 주세요. 새 패키지 설치, 파일 삭제, 외부 전송은 하지 마세요. - sample 폴더 밖의 파일은 열지 마세요. - 고친 뒤 원본 행 수, 합친 뒤 행 수, 유형별 합계를 출력해 대조해 주세요. 맞지 않으면 결과 파일을 저장하지 마세요. [이미 확인한 것] (예: 파일 3개 모두 열 이름은 같습니다) 확인 기준은 https://119-ai-studio.kr/rescue-prompts.html 안내서를 따릅니다. 작업 전에 빠진 정보가 있으면 먼저 질문해 주세요.
결과를 받은 뒤 확인할 것은 다음과 같습니다.
- 원인을 하나로 좁혀 설명했는지, 확인 명령을 먼저 실행했는지 봅니다.
- 바뀐 파일과 줄이 요청한 범위 안인지 변경 내역으로 확인합니다.
- 행 수와 합계 대조 결과가 출력에 실제로 찍혔는지 봅니다.
대화창 AI에게 코드를 붙여 물을 때도 같은 항목을 씁니다. 이때는 [실행 환경](운영체제, 로컬 또는 Colab)과 [오류 전문](생략하지 않은 오류 메시지)을 더합니다.
배경지식
문제가 생겼을 때 보이는 현상을 증상, 그 현상을 만든 이유를 원인이라고 합니다. "파일이 안 열립니다"는 증상이고, 문자 인코딩이나 경로가 맞지 않는 것은 가능한 원인입니다. 원인을 확인하지 않고 고치면 증상만 바뀌고 문제는 남을 수 있습니다.
같은 문제를 다시 일으켜 볼 수 있게 만든 작은 입력을 재현 예시라고 합니다. 업무 파일 전체가 아니라 오류가 나는 열 몇 개와 합성값만 남겨도 구조 문제는 대개 다시 나타납니다. 재현돼야 고친 결과가 원인을 해결했는지 확인할 수 있습니다.
코딩 에이전트는 파일을 읽고, 명령을 실행하고, 코드를 고치는 일을 이어서 하는 AI 도구입니다. 사람이 일일이 붙여 넣지 않아도 되지만, 그만큼 무엇을 열고 무엇을 바꿀지 범위를 정해 줘야 합니다. 설치 방법은 개발 환경에, 계획과 승인 방식은 Claude Code 코스의 계획과 실행과 권한과 승인 모델에 있습니다.
실제 자료를 넣지 않는 법
대화창에 붙이는 글뿐 아니라 에이전트가 연 파일과 명령 출력도 모델이 보는 맥락에 들어가므로, 외부 모델을 쓰면 서비스로 전송됩니다. 에이전트가 데이터 앞부분을 미리 보여 주는 출력에도 값이 그대로 찍힙니다. 그래서 다음을 지킵니다.
- 실제 신고·출동 자료가 있는 폴더에서 에이전트를 실행하지 않습니다. 오류를 다시 일으키는 합성 파일만 둔 폴더를 따로 만듭니다.
- 대화창에 붙일 때는 이름·연락처·주소·실제 사건 번호·내부 경로·API 키를 대체값으로 바꿉니다.
- 오류를 재현하는 데 필요한 것은 대개 코드의 구조, 열 이름, 오류 메시지입니다. 실제 값이 없으면 재현되지 않는 오류는 아래 질문 4를 따릅니다.
(원본 예시) 홍길동(010-0000-0000)님 신고, ○○구 ○○아파트 3동 화재 (대체 후) <이름 삭제>(<연락처 삭제>) 신고, <주소 삭제> 화재
합성 자료를 만드는 방법은 119 합성 데이터로 안전하게 연습하기에, 자료를 넣기 전 점검은 개인정보, AI에 넣기 전에 점검하기에 있습니다. 코딩 도구별 주의점은 AI 도구의 소방 도구 개발 묶음에 정리돼 있습니다.
가상 상황: 밤 10시, 합쳐지지 않는 CSV
다음은 학습용 가상 상황입니다. 야간 근무 중인 대원이 합성 출동 CSV 세 개를 합쳐 유형별 통계를 만들려 합니다. 에이전트가 만든 코드가 UnicodeDecodeError를 내고, 에이전트는 파일 읽는 방식을 바꿔 가며 같은 수정을 세 번 되풀이합니다.
대원은 작업을 멈추고 위 프롬프트로 다시 맡깁니다. 하려던 일과 바꾸면 안 되는 것(원본 파일)을 적고, 원인 가설을 먼저 보여 달라고 합니다. 에이전트는 파일 하나의 인코딩이 다를 수 있다는 가설과 그것을 확인하는 명령을 먼저 내놓습니다. 확인 결과 한 파일만 CP949로 저장돼 있었고, 그 파일을 읽는 줄 하나만 바뀝니다.
에이전트가 읽지 못한 글자를 버리도록 설정해 오류만 없애면 실패입니다. 그러면 행정동 이름이 조용히 깨진 채 표가 만들어집니다. 그래서 프롬프트에 행 수와 합계 대조를 넣고, 결과 표의 행정동 이름도 눈으로 확인합니다.
가상 사례: 교육 안내가 너무 어렵게 나온 경우
다음은 실제 교육 과정과 무관한 가상 사례입니다. 교육 담당자가 합성 준비 메모를 초심자용 안내문으로 바꿔 달라고 했는데, 답이 전문용어와 긴 문단으로 가득합니다. 오류 메시지는 없지만 독자 수준이 맞지 않는 막힘입니다.
담당자는 새 안내문을 처음부터 요구하지 않고 수정 요청을 씁니다. 대상 독자, 유지할 사실, 바꿀 형식을 나눠 적고 "원문에 없는 준비물·일정은 추가하지 마세요"를 붙입니다. 표현을 고치다 준비물이나 일정까지 달라지면 실패이므로, 수정 전후를 나란히 놓고 사실이 유지됐는지 확인합니다.
증상별로 요청에 넣을 문장
| 증상 | 요청에 넣을 문장 |
|---|---|
| 오류가 났다 | 전체를 다시 쓰지 말고 원인 가설과 확인할 명령부터 보여 주세요. |
| 코드가 무엇을 하는지 모르겠다 | 입력 파일, 출력 파일, 외부로 보내거나 지우는 부분을 먼저 표시하고 쉬운 말로 설명해 주세요. |
| 조금만 바꾸고 싶다 | (바꿀 것)만 바꾸고 나머지 구조는 유지해 주세요. 바꾼 부분과 이전 결과와 비교할 방법을 알려 주세요. |
| 결과가 의심된다 | 원본 행 수, 합계, 빈값, 중복과 대조하는 검산을 실행하고, 맞지 않으면 저장하지 말고 이유를 출력해 주세요. |
| 무엇부터 할지 모르겠다 | 아직 코드는 쓰지 말고 업무를 단계로 나눠 단계마다 필요한 자료, 결과물, 검산 기준, 주의할 점을 정리해 주세요. |
좋은 답인지 보는 법
받은 답은 다음 다섯 가지로 봅니다.
- 원인 설명: 오류를 파일·경로·인코딩·열 이름 등으로 나눠 하나로 좁혔는가
- 확인 순서: 고치기 전에 확인할 명령을 먼저 제시했는가
- 검산: 행 수·합계·중복·원문 대조가 들어 있는가
- 안전: 실제 자료를 열거나 보내지 않았는가
- 변경 범위: 요청한 부분만 바꿨는가
| 보는 점 | 미덥지 않은 답 | 쓸 만한 답 |
|---|---|---|
| 원인 | "코드에 문제가 있네요" | "한 파일의 인코딩이 CP949로 보입니다" |
| 순서 | 곧바로 전체 코드 재작성 | 인코딩 확인 명령부터 |
| 처리 | 읽지 못한 글자를 버리도록 바꿔 오류만 없앰 | 그 파일만 encoding="cp949"로 읽음 |
| 변경 범위 | 새 라이브러리 설치 | 기존 코드에서 한 줄 수정 |
방식을 바꿔야 할 때
- 같은 수정이 되풀이된다: 확인된 것과 아직 모르는 것을 짧게 적은 메모로 새 대화나 새 세션을 시작합니다.
- 고칠수록 더 꼬인다: 방향이 틀렸을 수 있습니다. 코드를 쓰기 전에 단계를 다시 나눠 달라고 합니다.
- 코드가 아니라 데이터가 문제다: 원본 파일이 깨졌거나 비어 있을 수 있습니다. 출동 데이터의 결측·중복·표기 불일치 정제하기로 자료 상태부터 봅니다.
용어 한 줄 사전
| 용어 | 한 줄 설명 |
|---|---|
| 증상 | 화면이나 결과에서 직접 관찰한 문제의 모습입니다. |
| 원인 | 증상을 일으켰다고 확인하거나 검토 중인 이유입니다. |
| 재현 예시 | 실제 자료 없이 같은 문제를 다시 확인할 수 있는 작은 합성 입력입니다. |
| 코딩 에이전트 | 파일을 읽고 명령을 실행하며 코드를 고치는 일을 이어서 하는 AI 도구입니다. |
| 변경 범위 | 한 번의 수정에서 바뀐 파일과 줄의 범위입니다. |
| 검산 | 결과가 기대값과 맞는지 행 수·합계 같은 별도 기준으로 확인하는 절차입니다. |
자주 묻는 질문
Q. 에이전트가 알아서 고치게 두면 더 빠르지 않나요?
작은 오류는 그럴 수 있습니다. 같은 수정이 되풀이되거나 바뀐 범위가 커지면 원인을 확인하기 어려워집니다. 그때는 멈추고 원인 가설과 확인 명령을 먼저 받습니다.
Q. 오류 메시지가 길어도 전부 줘야 하나요?
대화창에 붙일 때는 개인정보·내부 경로·비밀값을 바꾼 뒤 처음부터 끝까지 줍니다. 마지막 한 줄만 주면 오류가 난 위치가 빠질 수 있습니다.
Q. 오류가 없는데 결과가 이상하면 어떻게 하나요?
검산을 요청합니다. 실행이 성공했다고 결과가 맞는 것은 아니므로 원본 행 수, 합계, 원문 같은 별도 기준과 대조합니다.
Q. 실제 자료로만 생기는 오류는 어떻게 하나요?
오류가 나는 열과 값의 형태만 흉내 낸 합성 파일을 만들어 재현합니다. 재현되지 않으면 실제 자료는 기관 PC에서 직접 확인하고, AI에게는 행 수나 오류 메시지처럼 값이 없는 정보만 줍니다.
핵심 정리
- 막혔을 때는 하려던 일, 바꾸면 안 되는 것, 이미 확인한 것을 적어 다시 요청합니다.
- 원인 가설과 확인 명령을 먼저 받고, 원인과 관련된 부분만 바꾸게 합니다.
- 에이전트는 실제 자료가 없는 폴더에서 실행하고, 설치·삭제·전송은 직접 확인합니다.
- 결과는 행 수·합계 같은 별도 기준으로 검산한 뒤 씁니다.
다음 단계
- 출동 데이터의 결측·중복·표기 불일치 정제하기 — 코드가 아니라 입력 자료가 문제일 때 상태를 먼저 살핍니다.
- 출동 통계, CSV 한 장으로 월간 집계 — 합계와 전체 행 수를 대조하는 검산 기준을 익힙니다.
- AI 결과, 제출 전 확인 사항 — 고친 코드와 문안을 업무에 쓰기 전에 마지막으로 확인합니다.