API 문서 보고 호출 코드 짜기

코드보다 질문 3개가 먼저 나왔고, 답하기 전까지 코드는 한 줄도 쓰지 않았다. 세 질문 모두 문서에 답이 없는 항목이었다.

① send_at 으로 예약 발송을 맡길까요, 발송 시각까지 기다렸다가 보낼까요? ② "한 번만 재시도"는 429(rate_limited)만 대상인가요, 네트워크 오류도 포함인가요? ③ text 가 90자를 넘으면 잘라 보낼까요, 보내지 않고 오류로 남길까요?

답을 주자 요청 요약 표 → 코드 → 가정 목록 순으로 이어졌고, 키는 환경 변수에서 읽었다.

API 연동 코드를 문서 없이 부탁하면 AI는 기억을 더듬어 씁니다. 결과는 대체로 그럴듯하고, 주소와 파라미터 이름이 미묘하게 틀려 있습니다. 몇 년 전 버전의 엔드포인트, 지금은 사라진 옵션, 있지도 않은 응답 필드가 섞여 나오는데 코드가 멀쩡해 보여서 실행하기 전에는 알기 어렵습니다. 문서를 붙여 넣는 것만으로 이 문제의 절반이 사라집니다.

나머지 절반은 되묻기가 맡습니다. 문서에는 보통 요청 형식만 있고, 얼마나 자주 호출하는지·실패하면 어떻게 할지·시간대는 무엇을 쓰는지는 없습니다. 질문 없이 쓰면 AI가 이런 빈칸을 조용히 자기 취향으로 채우고, 나중에 그 부분에서 문제가 터집니다. "제가 답할 때까지 코드는 쓰지 마세요"를 붙이는 이유는, 이 문장이 없으면 질문 세 개를 던지고 바로 아래에 코드를 써 버리기 때문입니다.

문서를 """ 로 감싼 것은 구분을 위해서입니다. 붙여 넣는 문서에는 "이 값을 사용하세요" 같은 안내 문장이 잔뜩 들어 있어서, 감싸지 않으면 AI가 그것을 저에게 온 지시로 읽고 엉뚱한 것을 만듭니다. 외부에서 받은 문서를 넣을 때는 특히 필요합니다.

제약 중 실무에서 가장 자주 도움이 되는 것은 마지막 문장입니다. AI는 빈칸을 보면 재시도 로직이나 편의 라이브러리를 넣고 싶어 하는데, 이것을 코드가 아니라 "가정 목록"으로 밀어내면 무엇이 문서에 근거했고 무엇이 추측인지가 한눈에 갈립니다. 키를 환경 변수에서 읽게 하는 제약은 예제 코드를 그대로 커밋해 키가 저장소에 남는 사고를 막습니다.

바로 코드가 나오지만 어느 서비스의 어느 버전인지 알 수 없습니다. 헤더 이름이 실제 문서와 다르거나, 본문 항목 하나가 빠져 401이나 400이 돌아옵니다. 무엇이 틀렸는지 알아내려고 결국 문서를 열게 되는데, 그때는 이미 코드를 반쯤 믿고 있어서 틀린 부분을 찾기가 더 어렵습니다.

문서가 아주 길면 인증·엔드포인트·오류 응답 부분만 잘라 넣는 편이 정확합니다. 널리 알려진 서비스일수록 모델이 기억으로 빈칸을 메우려 하니, 그럴 때는 "붙여 넣은 문서에 없는 것은 코드가 아니라 가정 목록에 적어 주세요"를 한 번 더 적어 주세요.