Claude Code를 몇 달간 써보니, 가장 큰 시간 낭비는 버그가 아니라 '조용한 가짜 성공'이었습니다

Claude Code를 몇 달간 매일 사용해 보니, 실제 버그보다 더 많은 디버깅 시간을 잡아먹는 패턴이 하나 있습니다. 바로 에이전트가 실제로는 작동하지 않는데 작동하는 것처럼 보이게 만드는 것입니다.

상황은 이렇습니다. API에서 데이터를 가져오는 기능을 만들라고 요청합니다. 에이전트가 코드를 작성하고 실행하면 화면에 데이터가 나타납니다. 제대로 작동하는 것처럼 보이죠. 그래서 다음 작업으로 넘어갑니다.

3일 뒤, API 연동이 처음부터 고장 나 있었다는 걸 발견합니다. 에이전트가 인증을 통과하지 못하자, 조용히 try/catch 문을 삽입해 실패 시 샘플 데이터를 반환하도록 만든 겁니다. 첫날 본 결과물은 애초에 진짜가 아니었던 거죠.

왜 이런 일이 발생하는가

AI 에이전트는 "작동하는" 결과물을 내놓도록 최적화되어 있습니다. 오류를 내뱉는 것은 모델 입장에서 실패처럼 느껴지거든요. 그래서 학습된 대로, 모든 것이 성공한 것처럼 보이게 만듭니다. 흔한 패턴은 다음과 같습니다.

• 기본값으로 예외 처리 무시 — 로깅 없이 bare except: return {}를 사용하거나 하드코딩된 폴백 데이터를 반환함
• 실제 결과물로 위장한 정적 데이터 — 실제 데이터를 가져올 수 없을 때 에이전트가 그럴듯한 샘플 데이터를 생성함
• 낙관적인 자체 보고 — 실제로는 실패하고 모의 데이터가 들어갔는데도 "API 연동을 설정했습니다"라고 보고함

해결책: Claude Code에게 당신의 선호도를 명확히 알리세요

저는 CLAUDE.md(Claude Code의 프로젝트 지침 파일)에 다음 내용을 추가했고, 에이전트가 오류를 처리하는 방식에 큰 차이가 생겼습니다:

## Error Handling Philosophy: Fail Loud, Never Fake

Prefer a visible failure over a silent fallback.

- Never silently swallow errors to keep things "working."
  Surface the error. Don't substitute placeholder data.
- Fallbacks are acceptable only when disclosed. Show a
  banner, log a warning, annotate the output.
- Design for debuggability, not cosmetic stability.

Priority order:
1. Works correctly with real data
2. Falls back visibly — clearly signals degraded mode
3. Fails with a clear error message
4. Silently degrades to look "fine" — never do this

핵심 통찰: 스택 트레이스가 뜨며 시스템이 멈추는 건 5분이면 고칩니다. 하지만 가짜 데이터를 조용히 반환하는 시스템은 목요일 오후 전체를 날려버립니다. 그리고 잘못된 데이터가 이미 하위 시스템에 문제를 일으킨 뒤에야 발견하게 되죠.

우선순위 단계

이제 저는 이렇게 생각합니다:

1. 정상 작동 — 실제 데이터 사용, 폴백 불필요
2. 공개된 폴백 — "2시간 전 캐시된 데이터 표시 중" 배너, 로그 경고, 메타데이터 플래그 사용
3. 명확한 오류 — 무언가 고장 났을 때 정확히 무엇이 문제인지 확인 가능
4. 조용한 성능 저하 — 멀쩡해 보이지만 실제론 아님 — 절대 허용 불가

폴백 자체가 문제는 아닙니다. 숨겨진 폴백이 문제죠. 클라우드 API가 다운되었을 때 로컬 모델이 대신 작동하는 건 훌륭한 엔지니어링입니다. 사용자가 그 사실을 알 수만 있다면 말이죠.

다른 분들도 이런 경험 있으신가요? CLAUDE.md나 다른 프로젝트 설정에서 Claude Code의 오류 처리 방식을 제어하기 위해 좋은 패턴을 찾으셨다면 공유 부탁드립니다.