Anthropic Academy에서 제공하는 "Building with the Claude API"는 Claude API의 기본기부터 에이전트 패턴까지를 12개 챕터 79개 레슨으로 다루는 무료 코스이다. Claude Code와 짝을 이루는 코스로, Claude의 호출 쪽을 깊게 파고든다.
이 글은 7년차 안드로이드 개발자가 코스를 수료한 뒤, 실무에 바로 적용 가능한 부분을 정리한 것이다. 사주멍/루나데이의 AI 상담 엔진을 다듬는 과정과 직접 연결된 내용 위주로 추렸다.
코스 개요
| 항목 | 내용 |
|---|---|
| 코스명 | Building with the Claude API |
| 제공 | Anthropic Academy (Skilljar) |
| 분량 | 79개 레슨, 12개 챕터, 챕터별 Quiz 7문항 |
| 소요 시간 | 약 8~10시간 |
| 비용 | 무료 (인증서 포함) |
| 난이도 | Intermediate |
| 인증서 | Building with the Claude API |
1. 챕터 구성 — 어디부터 봐야 하나
전체 12 챕터 중 가장 핵심도가 높은 것은 다음 5개이다.
| 챕터 | 핵심 내용 | 핵심도 |
|---|---|---|
| 03 Accessing the API | API 키, 요청 구조, 시스템 프롬프트, 스트리밍, 구조화 출력 | ⭐⭐⭐⭐⭐ |
| 05 Prompt Engineering | 명확성, XML 태그, Few-shot 예시 | ⭐⭐⭐⭐⭐ |
| 06 Tool Use | 함수 호출, 멀티턴, 다중 도구 | ⭐⭐⭐⭐⭐ |
| 09 MCP | Model Context Protocol 표준 | ⭐⭐⭐⭐⭐ |
| 11 Agents and Workflows | 에이전트 패턴, 라우팅, 평가 루프 | ⭐⭐⭐⭐⭐ |
나머지 7 챕터(Prompt Eval, RAG, Features 등)도 중요하지만, 위 5개만 깊게 봐도 코스의 80%는 챙길 수 있다.
2. System Prompt와 Temperature — 가장 자주 쓰는 두 가지
Chapter 03에서 다루는 내용 중 실무에서 매일 만지게 되는 두 파라미터이다.
System Prompt
System prompt는 모델에게 역할과 톤을 고정하는 영역이다. User 메시지에 같은 지시를 매번 넣는 것보다 system에 한 번 박는 것이 토큰 효율과 일관성 면에서 우위에 있다.
response = client.messages.create(
model="claude-sonnet-4-6",
system="당신은 한국 사주명리학 전문가입니다. 사용자의 사주 정보를 바탕으로 조언합니다.",
messages=[
{"role": "user", "content": "올해 운세가 어떤가요?"}
],
max_tokens=1024
)
사주멍의 상담 엔진은 system prompt 길이가 약 1,500 토큰이다. 여기에는 역할, 톤, 위기 감지 규칙, 응답 형식이 모두 들어간다.
Temperature
| 값 | 용도 |
|---|---|
| 0.0 ~ 0.3 | 분류, 추출, 구조화 출력 |
| 0.4 ~ 0.7 | 일반 대화, 요약 |
| 0.8 ~ 1.0 | 창작, 다양한 답변 필요 시 |
사주멍 상담은 0.7 근처에서 가장 안정적이었다. 너무 낮으면 답변이 기계적이고, 너무 높으면 사주 해석이 일관성을 잃었다. 도메인마다 sweet spot이 다르므로 실제로 비교 테스트가 필요하다.
3. XML 태그로 프롬프트 구조화 — 가장 큰 ROI
Chapter 05의 Structure with XML tags 레슨이 가장 즉시 효과를 본 부분이다.
위반 사례
처음에는 사주 정보를 자연어로만 넣었다.
prompt = f"""
사용자 생년월일: {birth_date}
태어난 시각: {birth_time}
질문: {question}
이전 상담 내용: {history}
위 정보를 바탕으로 답변해주세요.
"""
모델이 어느 부분이 "질문"이고 어느 부분이 "이전 내용"인지 가끔 헷갈렸다. 응답에 "이전 상담 내용: {history}" 같은 placeholder가 그대로 흘러나오는 사고도 있었다.
개선안
XML 태그로 영역을 나누니 안정성이 크게 올랐다.
prompt = f"""
<user_profile>
<birth_date>{birth_date}</birth_date>
<birth_time>{birth_time}</birth_time>
</user_profile>
<conversation_history>
{history}
</conversation_history>
<current_question>
{question}
</current_question>
위 정보를 바탕으로 답변해주세요.
"""
모델이 Anthropic 학습 데이터에서 XML 태그를 구조 신호로 인식하도록 훈련돼 있어, 자연어 구분자보다 훨씬 안정적으로 동작한다. 사주멍의 모든 프롬프트는 이 패턴으로 통일했다.
4. Tool Use — Claude를 "행동하는 모델"로
Chapter 06이 코스 전체에서 가장 분량이 많고(13 레슨), 가장 패러다임 전환이 큰 부분이다.
기본 흐름
1. 도구 스키마 정의 (이름, 설명, input_schema)
2. messages.create()에 tools 파라미터로 전달
3. 응답에 tool_use 블록이 포함됨
4. 클라이언트가 해당 도구를 실행
5. tool_result 블록으로 결과 회신
6. Claude가 최종 답변 생성
사주멍 적용 사례
루나데이 건강관리 앱에서 다음 도구를 정의했다.
tools = [
{
"name": "get_user_health_records",
"description": "사용자의 최근 N일간 건강 기록을 조회합니다.",
"input_schema": {
"type": "object",
"properties": {
"user_id": {"type": "string"},
"days": {"type": "integer", "default": 30}
},
"required": ["user_id"]
}
},
{
"name": "get_period_prediction",
"description": "다음 생리 예측일을 계산합니다.",
"input_schema": {...}
}
]
사용자가 "이번 달 몸 상태 어때?" 라고 물으면 Claude가 get_user_health_records를 호출하고, "다음 생리 언제야?" 라고 물으면 get_period_prediction을 호출한다. 모델이 필요한 데이터를 스스로 요청하는 구조라서, 클라이언트는 모든 컨텍스트를 미리 끌어모을 필요가 없다.
멀티턴 도구 호출
복잡한 질문에서는 한 번의 응답에 여러 도구 호출이 연쇄적으로 일어난다. Chapter 06-08의 Implementing multiple turns 레슨은 이 루프를 직접 구현하는 예제를 다룬다.
while True:
response = client.messages.create(...)
if response.stop_reason == "end_turn":
break
# tool_use 블록을 추출해 실행
tool_results = execute_tools(response.content)
messages.append({"role": "user", "content": tool_results})
이 루프 구조가 결국 에이전트의 핵심 동작 원리이다. Chapter 11에서 이 패턴이 한 단계 더 추상화된다.
5. MCP — 코드는 직접 짤 줄 알아야 한다
Chapter 09는 Model Context Protocol을 다룬다. Claude Code에서 claude mcp add로 쉽게 추가하는 것과 별개로, MCP 서버를 직접 짜는 능력은 별도의 영역이다.
MCP가 해결하는 문제
Tool Use는 클라이언트마다 도구 정의를 새로 짜야 한다. MCP는 도구 정의를 표준화된 서버로 분리해, 여러 클라이언트가 같은 서버를 공유하도록 한다.
[Claude Code] ──┐
[Claude API] ──┼──→ [MCP Server] ──→ [DB / API / FS]
[Custom App] ──┘
실제 작성 경험
필자는 코스 수료 전에 이미 두 개의 MCP 서버를 npm에 배포한 경험이 있다.
- claude-session-continuity-mcp — Claude Code 세션 연속성 (awesome-mcp-servers 큐레이션 등재)
- mac-pilot-mcp — macOS UI 자동화
코스에서 새로 알게 된 부분은 MCP의 인증·권한 설계이다. 단순히 stdio 통신만 쓰던 방식에서, OAuth/HTTP 기반 원격 MCP로 확장하는 패턴이 인상 깊었다.
6. Agents and Workflows — Tool Use의 상위 추상화
Chapter 11이 코스의 최종장이다. Anthropic이 정의한 에이전트 패턴 4가지가 정리되어 있다.
| 패턴 | 설명 | 적용 사례 |
|---|---|---|
| Prompt Chaining | 출력을 다음 입력으로 연결 | 이력서 분석 → 매칭 점수 산출 |
| Routing | 입력 유형에 따라 다른 프롬프트로 분기 | 사주 상담 vs 일반 상담 |
| Parallelization | 여러 호출을 병렬로 + 집계 | 다중 정보원 통합 |
| Orchestrator-Workers | 메인이 작업 분배 + 워커가 처리 | MCP 멀티 서버 호출 |
사주멍의 MCP 상담 엔진은 Routing + Parallelization + Orchestrator-Workers가 결합된 구조이다. 사용자 질문이 들어오면 먼저 라우터가 카테고리를 판단하고, 카테고리별 워커들이 병렬로 정보를 수집한 뒤, 오케스트레이터가 최종 답변을 합성한다.
코스를 듣기 전에는 이 구조를 직관적으로 짰지만, 공식 패턴 이름이 있다는 사실과 그 한계 및 비용까지 공식 문서로 정리된 점이 가장 큰 수확이었다. 면접에서 *"왜 이렇게 짰나"*를 답할 때 근거가 생긴다.
7. 평가 — Prompt Eval은 선택이 아니다
Chapter 04의 Prompt Evaluation은 가장 과소평가된 챕터이다. 프로덕션 LLM 앱에서 평가 파이프라인은 필수인데, 이걸 모르고 시작하면 *"왜 응답 품질이 들쑥날쑥하지?"*를 영영 해결 못한다.
평가의 두 종류
| 방식 | 설명 | 언제 쓰나 |
|---|---|---|
| Code-based grading | 정답 비교, 정규식, 길이 체크 | 명확한 정답이 있을 때 |
| Model-based grading | 다른 LLM이 응답을 채점 | 주관적 품질 평가 |
사주멍에 적용할 때는 두 가지를 섞었다. 위기 감지(자살 시그널 등)는 code-based(키워드 매칭 + 점수), 답변 자연스러움은 model-based(Claude 자체가 채점). 자체 평가 프레임워크 이름을 SPARKE로 정해서 운영 중이다.
8. Quiz에서 만난 까다로운 문제
코스의 Quiz가 의외로 까다롭다. 챕터별 평균 7문항인데, 단순 암기보다 개념의 경계를 묻는 문제가 많다.
인상 깊었던 문제 (Ch 06 Tool Use)
Claude의 tool_use 응답을 받은 뒤, 다음 messages.create 호출에 무엇을 포함해야 하는가? A) tool_use 블록만 B) tool_result 블록만 C) tool_use를 포함한 assistant 메시지와 tool_result를 포함한 user 메시지 모두 D) 새 user 메시지만
답은 C이다. Claude가 자신의 이전 tool_use 결정을 기억해야 일관된 후속 답변이 나오기 때문이다. 이걸 모르면 도구 호출이 자꾸 처음부터 다시 시작되는 버그를 만나게 된다.
9. 사주멍/루나데이에 적용한 결과
코스를 들으면서 사주멍의 프롬프트와 도구 정의를 단계별로 다시 정리했다. 결과는 다음과 같다.
| 영역 | 개선 |
|---|---|
| Prompt 구조 | 자연어 → XML 태그 통일 |
| 도구 정의 | 수동 라우팅 → Tool Use 자동 라우팅 |
| 평가 | 임의 테스트 → SPARKE 정량 평가 |
| 토큰 비용 | 시스템 프롬프트 분리 + 캐싱 도입으로 약 30% 감소 |
| 에이전트 구조 | "그냥 호출" → Orchestrator-Workers 패턴 |
코스가 새로운 기능을 가르쳐줬다기보다는, 이미 쓰고 있던 패턴에 이름과 근거를 붙여줬다. 이 차이가 면접/회고에서 큰 무기가 된다.
정리
- Building with the Claude API는 12 챕터 79 레슨으로 Claude의 호출 쪽을 깊게 다룬다
- 핵심도가 높은 챕터는 03(API 기본), 05(프롬프트), 06(도구), 09(MCP), 11(에이전트)이다
- XML 태그 프롬프트 구조화가 가장 즉시 효과를 보는 기법이다
- Tool Use 루프 구조가 에이전트 패턴의 출발점이다
- 평가 파이프라인(Prompt Eval)을 빠뜨리면 프로덕션 LLM은 흔들린다
- 이미 쓰던 패턴에 공식 이름과 근거를 붙여주는 것이 코스의 가장 큰 가치였다
참고: