AI에게 ‘그냥 리뷰해줘’만 던지던 날…디버깅 프롬프트를 구조로 바꾼 이유
Notion에 쌓아 둔 디버깅 프롬프트 메모를 바탕으로, AI 코드 리뷰가 추측으로 흐를 때 Workers CPU·레이트리밋·타임아웃을 먼저 묻게 만든 시행착오를 정리합니다.
Notion «디버깅 프롬프트 모음»을 다시 열었을 때, 가장 먼저 눈에 들어온 건 제목이 아니라 출력 형식이었다. Critical Risks → 원인 → 해결 방향처럼 칸이 고정돼 있었다. 반대로 내가 평소 에이전트에게 던지던 말은 “이 PR 리뷰해줘”, “버그 원인 찾아줘” 한 줄이었다. 결과는 비슷했다. 모델은 자신감 있게 추측하고, 나는 그 추측을 다시 손으로 검증했다. 시니어 IT 실무자 시각으로 보면, 문제는 모델 성능이 아니라 질문의 해상도였다.
사실: ‘리뷰’와 ‘장애 예방 검수’는 다른 작업이다
메모의 골격은 단순하다. 상용 배포 전에 치명적 우려를 우선순위 순으로 적고, 인프라 제약(런타임 메모리·실행 시간·타임아웃)·불필요한 API 호출·카오스 상황(타임아웃·연결 유실·Rate Limit)을 강제로 묻는다. 예시로 적혀 있던 문장 중 하나는 Cloudflare Workers의 CPU 시간 한도 초과 위험이었다. 실제 이 블로그·사이드 프로젝트 루프에서도 Workers/Pages 배포는 자주 타는데, “기능이 돌아간다”와 “한도 안에서 돌아간다”는 다른 문장이다.
나는 같은 프롬프트를 로컬 Astro 콘텐츠 파이프라인에도 시험해 봤다. 입력은 ‘새 글 frontmatter와 빌드 로그’, 출력은 Critical Risks 형식. 첫 응답은 여전히 장황한 스타일 조언이었다. 프롬프트에 **“인프라 제약·레이트리밋·비밀값 노출을 1순위로 쓰고, 스타일 조언은 3순위 이하”**를 명시하니 응답이 바뀌었다. 예를 들어 heroImage에 원격 URL만 두는지, 커밋에 .env가 섞이지 않는지, 빌드가 콘텐츠 스키마에서 먼저 터지는지가 위로 올라왔다. 내부 실측으로 남기면, 동일 초안에 대해 ‘자유 리뷰’와 ‘구조화 리뷰’를 번갈아 돌렸을 때 조치 가능한 항목 수가 구조화 쪽에서 더 많았다(비밀값·구체 수치는 생략).
이유: 모델은 빈칸을 메꾸고, 운영은 빈칸을 드러낸다
에이전트에게 형식을 안 주면, 모델은 학습 분포상 흔한 ‘친절한 코드 리뷰’로 빈칸을 채운다. 변수명·중복·가독성. 그게 틀린 말은 아니지만, 장애 회고에서 돈이 나가는 지점은 대개 다른 층이다. CPU 예산, 재시도 폭풍, 외부 API 한도, 환경변수 누락, 봇·크롤러 차단. Notion 메모가 카오스·복구력 항목을 따로 둔 이유가 여기에 있다. 장애율 0%를 지향하는 검수와 PR 코멘트 생성은 목적함수가 다르다.
또 하나. 프롬프트를 절제 없이 길게 붙이면 ‘FULL’ 모드가 모든 모델에 강제된다. 메모·룰 쪽에는 모델·컨텍스트 안정성에 따라 LIGHT/FULL을 나누는 감각도 있었다. 불안정한 컨텍스트에는 두꺼운 검수가 필요하고, 이미 안정된 IDE 자동 수정에는 가벼운 체크가 맞다. 나는 이걸 “프롬프트 길이 = 품질”로 오해했다가, 같은 체크리스트를 짧은 강제 질문으로 압축하는 쪽으로 바꿨다. ‘Workers CPU·타임아웃을 봤는가? Rate Limit 재시도가 폭풍이 되는가? 비밀값이 로그에 찍히는가?’ 세 줄이면 충분할 때가 많다.
평가: 어디에 쓰고, 어디에 안 쓰는가
쓰는 곳: 배포 직전, 외부 API를 부르는 워커, 크론·오토메이션처럼 사람이 자리를 비우는 경로. 여기서 구조화 디버깅 프롬프트는 추측을 줄이고 검증 순서를 고정한다. 안 쓰는 곳: 이미 테스트가 통과한 순수 리팩터, 문장 다듬기, 디자인 취향. 여기에 Critical Risks 템플릿을 들이밀면 노이즈만 는다.
한계도 분명하다. 프롬프트는 로그·재현 절차·관측을 대체하지 않는다. 모델이 “50ms CPU”를 말해도, 대시보드 숫자와 트레이스를 안 보면 그건 문장일 뿐이다. 회사·고객 실명, 내부 URL, API 키는 이 글과 메모 공개본에서 전부 뺐다. 교훈만 남긴다. AI 리뷰의 품질은 모델 이름보다, 운영자가 강제로 묻게 만든 질문 목록에 비례한다.
다음에 볼 것: 같은 체크리스트를 CI 주석 템플릿으로 옮길지, 에이전트 도구 호출 전 게이트로 넣을지. 둘 다 “사람이 다시 쓰는” 비용이 드는데, 한 번만 형식화해 두면 매 배포마다 같은 구멍을 놓치는 빈도는 줄어든다.
출처
- Notion 시드: «디버깅 프롬프트 모음» — Critical Risks·인프라 제약·카오스/레이트리밋 검수 골격을 공개 가능한 요지로 재구성 (페이지 URL 비공개)
- 내부 실측: 동일 초안에 자유 리뷰 vs 구조화 리뷰를 교차 실행해 조치 가능 항목이 구조화 쪽에서 더 많이 나온 경험 확인 (비밀값·구체 벤치 수치 제외, 열람: 2026-07-31)
- Cloudflare Workers — Limits — CPU time 등 런타임 한도 개념 참고 (열람: 2026-07-31)