#11 Claude API 기초 — 코드 없이 파라미터 이해하기lecture_script
코스: claude-autowork · 에이전트: producer
HOOK (45초)
Claude로 자동화를 시작하려는데, API 문서를 열었다가 바로 닫아본 적 있으시죠?
Temperature, max_tokens, system prompt… 영어 단어들이 줄줄이 나오는 순간 "이건 개발자 영역이구나" 싶어서 포기하게 됩니다.
근데 오늘 이 세 단어만 제대로 이해하면, API를 쓸 때 Claude가 왜 이상한 답변을 내뱉는지, 어떻게 고쳐야 하는지 바로 보이기 시작합니다.
코드 한 줄 안 써도 됩니다. 개념만 잡으면 됩니다.
PROMISE (30초)
이번 차시가 끝나면, temperature·max_tokens·system prompt 세 파라미터를 각각 설명할 수 있고, 세 가지 설정 조합이 출력 결과에 어떤 차이를 만드는지 비교 분석표로 직접 정리할 수 있게 됩니다.
CORE (8–10분)
중요 개념 1 — Temperature: '창의성 다이얼'
설명
Temperature는 Claude가 다음 단어를 고를 때 얼마나 '예측 가능한 선택'을 하느냐를 조절합니다.
값은 0에서 1 사이입니다. 0에 가까울수록 확실한 단어만 고릅니다. 1에 가까울수록 덜 확실한 단어도 과감하게 선택합니다.
메모리 페그, 이렇게 기억하세요. '라디오 볼륨 다이얼' 입니다. 볼륨을 낮추면 잡음 없이 또렷한 소리만 나옵니다. 볼륨을 높이면 소리가 풍성해지지만 가끔 지직거립니다.
예시
계약서 요약 작업을 맡긴다고 해봅시다. Temperature를 0.1로 설정하면, Claude는 매번 거의 동일한 표현으로 요약합니다. 재현성이 높아서 업무 자동화에 딱 맞습니다.
반대로 광고 카피를 10개 뽑아달라고 할 때 Temperature를 0.9로 설정하면, 매번 다른 표현과 구조로 아이디어를 쏟아냅니다.
반례
그렇다면 창의적인 작업이니까 항상 높게 쓰면 좋을까요? 그렇지 않습니다. Temperature를 너무 높이면 사실 기반 답변에서 없는 정보를 지어내는 경향이 강해집니다. 제 경험상, 사실 확인이 필요한 작업에는 0.3 이하를 유지하는 게 안전합니다.
정리
- 반복·정확성 중심 작업 → Temperature 0~0.3
- 아이디어·다양성 중심 작업 → Temperature 0.7~1.0
중요 개념 2 — System Prompt: '역할 계약서'
설명
System Prompt는 Claude에게 대화가 시작되기 전에 건네는 '업무 지시서'입니다.
"너는 어떤 역할이고, 어떤 말투를 쓰고, 어떤 건 절대 하면 안 돼"를 미리 정의합니다.
사용자가 보내는 메시지는 매번 바뀌지만, System Prompt는 전체 대화에 걸쳐 유지됩니다.
메모리 페그는 '신입사원 입사 교육 문서' 입니다. 신입사원은 매일 다른 질문을 받지만, 입사 첫날 받은 교육 매뉴얼에 따라 일관되게 행동합니다. System Prompt가 바로 그 매뉴얼입니다.
예시
고객 응대 챗봇을 만든다고 해봅시다. System Prompt에 "당신은 친절한 고객 서비스 담당자입니다. 환불 정책은 안내하되 직접 결정은 내리지 마세요"라고 적어두면, 사용자가 어떤 말을 해도 Claude는 그 범위 안에서만 움직입니다.
반례
System Prompt를 너무 길고 복잡하게 쓰면 오히려 역효과가 납니다. 서로 충돌하는 지시가 들어가면, Claude가 어느 쪽을 따라야 할지 혼란스러워하며 일관성이 깨집니다. 대부분의 경우, System Prompt는 5~7문장 이내로 명확하게 쓰는 게 통하는입니다.
정리
- System Prompt = 대화 전체를 관통하는 역할·규칙 정의
- 짧고 충돌 없이 작성할 것
- 사용자 메시지와 분리해서 관리할 것
중요 개념 3 — Max Tokens: '출력 예산'
설명
Max Tokens는 Claude가 한 번의 응답에서 생성할 수 있는 최대 텍스트 분량을 제한합니다.
토큰은 단어보다 작은 단위입니다. 한국어 기준으로 대략 한 글자가 1~2토큰이라고 보시면 됩니다. 영어는 단어 하나가 보통 1토큰입니다.
메모리 페그는 '택시 미터기' 입니다. Max Tokens는 출발 전에 "이 정도 금액까지만 달려줘"라고 말하는 것과 같습니다. 미터기가 그 금액에 도달하면 응답이 딱 멈춥니다.
예시
짧은 요약이 필요한 자동화라면 max_tokens를 200~300으로 제한합니다. Claude가 쓸데없이 길게 설명을 늘어놓는 걸 방지할 수 있습니다.
반대로 긴 보고서 초안을 생성할 때는 2000 이상으로 넉넉하게 설정합니다.
반례
Max Tokens를 너무 낮게 설정하면, 응답이 문장 중간에 잘립니다. "결론은…" 이라고 시작했다가 그냥 끊기는 상황이 생깁니다. 실제로 자동화 파이프라인에서 이게 오류처럼 보여 디버깅에 시간을 쏟는 경우가 꽤 있습니다. 필요한 출력 길이보다 20~30% 여유 있게 설정하세요.
정리
- 짧은 출력 필요 → 200~500 토큰
- 긴 문서 생성 → 1500~4000 토큰
- 항상 예상 출력보다 여유 있게 설정
EXERCISE (3–4분)
지금 영상을 일시정지하고 직접 표를 만들어보세요.
아래 단계를 따라 진행하면 됩니다.
Step 1 — 표 틀 만들기
노션, 엑셀, 구글 시트 중 편한 것을 여세요. 열은 5개를 만듭니다.
- 조합 번호 / Temperature / Max Tokens / System Prompt 요약 / 예상 출력 특성
Step 2 — 3가지 조합 채우기
아래 세 조합을 그대로 입력하세요.
조합 A: Temperature 0.1 / Max Tokens 300 / System Prompt "정확한 사실만 간결하게 답변하세요"
조합 B: Temperature 0.8 / Max Tokens 800 / System Prompt "창의적인 마케터로서 활기차게 답변하세요"
조합 C: Temperature 0.5 / Max Tokens 500 / System Prompt "친절한 고객 서비스 담당자로 답변하세요"
Step 3 — 예상 출력 특성 직접 써보기
각 조합에서 "신제품 출시 안내 문구를 써줘"라는 동일한 질문을 넣었을 때, 어떤 결과가 나올지 스스로 예측해서 마지막 열에 적어보세요.
단어 몇 개라도 좋습니다. '짧고 건조할 것 같다', '다양한 표현이 나올 것 같다'처럼요.
Step 4 — 비교 문장 한 줄 추가
표 아래에 "나의 업무에 가장 맞는 조합은 이고, 이유는 이다"를 채워 넣으세요.
이 표가 다음 차시 실습의 기준 문서가 됩니다. 꼭 저장해두세요.
CTA (30초)
다음 차시에서는 오늘 만든 이 비교표를 실제 API 호출에 그대로 적용해봅니다.
노코드 툴에서 파라미터를 직접 입력하고, 조합별로 출력이 어떻게 달라지는지 눈으로 확인하는 시간입니다.
오늘 만든 비교표를 댓글에 공유해주세요. 다른 분들의 예측과 비교하면 훨씬 빠르게 감이 잡힙니다.
예상 분량: 15분