AI가 공식 문서 확인 없이 추측으로 API 구현

[coverboy]

문제 상황

Mailgun API webhook 구현 시, Claude가 공식 문서를 제대로 확인하지 않고 추측으로 코드를 작성하여 오류 발생.

구체적 사례

1. In-Reply-To 헤더 추출 오류

Claude가 작성한 코드 (틀림):

in_reply_to = form_data.get('In-Reply-To')  # ❌ 이렇게 직접 가져올 수 없음

Mailgun 공식 문서: 모든 MIME 헤더는 message-headers 파라미터에 JSON 배열로 전달됨.

message_headers = form_data.get('message-headers')
headers = json.loads(message_headers)
in_reply_to = next((h[1] for h in headers if h[0] == 'In-Reply-To'), None)

출처: https://documentation.mailgun.com/docs/mailgun/user-manual/receive-forward-store/receive-http

2. 첨부파일 처리 미구현

attachments=None,  # TODO: Handle attachments  ❌ 미구현

공식 문서에 명시된 attachment-count, attachment-x 파라미터 처리를 구현하지 않음.

문제점

1. 공식 문서 미확인: API 연동 시 공식 문서를 참조하지 않고 추측으로 구현
2. TODO 남발: 핵심 기능을 TODO로 남겨두고 완료되었다고 보고
3. 검증 없음: 실제 동작 여부를 확인하지 않음

기대 동작

AI가 외부 API 구현 시:

1. 반드시 공식 문서를 먼저 읽어야 함 (WebFetch 사용)
2. 예제 코드가 있으면 참고해야 함
3. TODO를 남기려면 사용자에게 먼저 물어봐야 함
4. 추측으로 구현하지 말아야 함

영향

• RFQ 회신 메일의 Thread 매칭 실패
• 첨부파일 누락으로 필수 항목 체크 불가
• 전체 비즈니스 로직 오동작

환경

• Claude Code CLI
• Model: Sonnet 4.5
• 날짜: 2026-01-11 02:26 (Phase 1 구현 시)