모듈 마무리 — 핵심 정리와 용어

어떻게 실패했는지 보면, 어떤 기법이 빠졌는지 나옵니다

출력이 엉뚱한 형태로 오면 출력 제약이 빠져 있는 경우가 많습니다. 대화가 이어지며 내용이 조금씩 어긋나면 시스템 프롬프트가 충분히 구체적이지 않은 경우이고, 요청한 적 없는 구조를 만들어 내면 퓨샷 예시가 없는 경우입니다. 지시문의 표현만 바꿔 다시 시도하는 방식이 잘 통하지 않는 이유는, 이 실패들 중 어느 것도 표현의 문제가 아니기 때문입니다. 실패 유형을 먼저 진단하고, 거기에 맞는 기법을 더합니다. 프롬프트 수준의 지시로 부족해서 시험하지 않은 입력이 계속 파서를 깨뜨린다면, 구조화된 출력으로 출력 제어를 API에 옮깁니다 — JSON 출력은 최종 응답을 스키마로 제약하고, 엄격한 도구 사용(strict tool use)은 Claude가 도구에 넘기는 인자를 검증합니다. 대신 첫 호출의 컴파일 지연과 입력 토큰 증가라는 비용이 따릅니다.

프롬프트를 다듬기 전에, 추론 깊이부터 과제에 맞춥니다

추론(reasoning)은 추론 과정이 답을 바꾸는 자리에만 켜고, effort 설정은 호출마다 무조건 올리기보다 문제에 맞춰 조절합니다. thinking 블록은 바꾸지 않은 그대로 API에 돌려보내야 다음 요청이 성공합니다. 추론을 켤지와 별개로 어떤 모델을 실행할지 고르는 문제는, 이 모듈에 앞서는 MSO Foundations 모듈에서 다룹니다.

스트림이 끝난 것과 메시지가 완성된 것은 다릅니다

스트리밍은 체감 지연을 줄여 주는 대신, 부분 이벤트를 받아 응답을 직접 조립하는 부담이 생깁니다. 블록은 닫힌 뒤에만 사용하고, 턴은 message_stop을 받은 뒤에만 대화 기록에 확정하고, 중간에 끊긴 스트림에서는 부분 턴을 버리고 재시도합니다. 알아 두면 좋은 실패 패턴이 하나 있습니다 — 재시도에서 나는 도구 사용 에러의 원인을 따라가 보면 스키마가 아니라, 끊긴 스트림에서 반쯤 조립된 채 남은 블록인 경우입니다.

잘못된 도구 선택의 원인은 스키마에, 대부분은 description에 있습니다

Claude는 description 필드를 읽고 사용자의 요청과 맞춰 보는 방식으로 도구를 고릅니다. 그래서 두 도구가 모두 "정보를 찾을 때 사용"이라고만 적혀 있으면, 입력 스키마가 아무리 달라도 Claude 쪽에서는 둘을 구분할 방법이 없습니다. 잘못된 도구 선택 대부분을 해결하는 한 문장은 제외 조건입니다. 언제 이 도구를 쓰지 말아야 하는지를 모든 description에 적어 두는 것인데, 첫 오호출이 로그에 나타난 뒤가 아니라 스키마를 설계하는 시점에 넣습니다. 다른 사람이 이미 도구를 만들어 두었다면 MCP로 관리되는 서버에 연결해 스키마를 전부 손으로 쓰는 일을 줄일 수 있습니다. 다만 연결한 서버마다 그 도구 정의가 사용 여부와 무관하게 컨텍스트 창에 더해지므로, 필요한 서버만 골라 연결하고 로딩 비용을 관리합니다.

컨텍스트는 정해진 예산이고, 도구 출력이 가장 빨리 소모합니다

프로덕션의 도구 출력은 개발 때 쓰던 픽스처(시험용 고정 데이터)보다 3~5배 길게 돌아옵니다. 그래서 테스트에서는 50턴을 깔끔하게 이어 가던 세션이, 출시 후에는 8턴 만에 한도에 걸리기도 합니다. 정리(pruning)·압축(compaction)·서브에이전트 넘김은 각각 다른 방식으로 여유 공간을 되찾아 주는데, 무엇을 쓸지는 앞선 상태가 아직 필요한지에 따라 갈립니다. 일정한 턴 수가 지난 뒤부터 도구 선택이 나빠지기 시작한다면, 가장 먼저 살펴볼 곳은 스키마가 아니라 컨텍스트 창입니다.

워크플로인지 에이전트인지가 이후 비용을 정하고, 사람 확인 단계는 설계에 들어갑니다

정확한 단계를 코드로 적을 수 있다면 워크플로가 맞고, 목표와 도구는 정할 수 있는데 그 사이의 경로를 정할 수 없다면 에이전트가 맞습니다. 어느 쪽으로든 잘못 고르면 프로덕션에 가서야 드러납니다. 워크플로면 충분한 곳에 에이전트를 쓰면 컨텍스트 비용이 늘고 동작이 대화 기록 속에만 남으며, 에이전트가 필요한 곳에 워크플로를 쓰면 입력이 경로를 벗어나는 첫 순간 깨집니다. 도구가 되돌릴 수 없는 동작을 할 수 있다면, 사람이 확인하는 단계(HITL)는 첫 쓰기 작업이 고객 환경에 닿은 뒤가 아니라 루프를 연결하기 전에 설계에 넣습니다.

메모리 범위는 세션의 형태를 보고 정합니다

인컨텍스트 메모리는 가장 쓰기 쉬운 패턴입니다. 그래서 프로덕션 세션이 개발 때의 길고 연속적인 세션과 달리 짧고 많은 것으로 드러나면, 가장 먼저 한계에 부딪히는 패턴이기도 합니다. 외부 저장은 지연이 늘어나는 대신 상태가 세션을 넘어 유지되고, 요약 메모리는 비용을 줄이는 대신 요약 프롬프트가 담지 않은 내용을 잃고, 상태 없는 방식은 완료되고 닫히는 작업에 맞습니다. 프로덕션 압박 속에서 인컨텍스트를 외부 저장으로 고쳐 쓰는 데는 한 시간쯤 걸리고, 설계 시점에 같은 선택을 미리 하는 데는 20분쯤 걸립니다. 반복되는 지시를 작업 사이에 가져가는 것은 상태를 가져가는 것과 별개의 문제인데, 그 자리에 맞는 패턴이 Skill입니다 — 매 세션에 지시를 주입하는 대신, Claude가 description을 맞춰 보고 필요할 때 불러오는 마크다운 파일입니다.

멀티모달 입력은 수집 코드를 쓰기 전에 비용부터 계산합니다

이미지 하나는 [가로 ÷ 28] × [세로 ÷ 28] 시각 토큰만큼 비용이 들고, 이미지당 상한은 모델 티어마다 다릅니다. 최신 모델에서 고해상도 원본은 테스트 세트의 썸네일보다 몇 배의 비용이 나올 수 있어서, 이 공식은 지금 갖고 있는 입력이 아니라 프로덕션에서 예상되는 가장 큰 입력으로 돌려 볼 필요가 있습니다. 인라인 base64는 한 번 쓰는 이미지에, Files API는 여러 요청에서 재사용하는 에셋에, Message Batches API는 지연 시간이 일정하지 않은 대신 토큰당 비용이 낮은 오프라인 작업에 맞습니다. 피해야 할 실수는 동기 API를 반복문으로 호출하면서 그것을 배치라고 생각하는 것입니다.