anthropic-cookbook)는 Anthropic이 직접 운영하는 "복붙 가능한" 코드 레시피 모음집이다. 프롬프트 한 줄 팁이 아니라, Jupyter 노트북 89개 + 실행 가능한 파이썬 프로젝트가 RAG·툴 사용·멀티모달·평가(eval)·에이전트 오케스트레이션·Claude Agent SDK·Managed Agents까지 하나하나 "돌아가는 예제"로 채워져 있다.
단순 문서 저장소가 아니라 uv·ruff·pytest·pre-commit·CI로 관리되는 진짜 소프트웨어 프로젝트이며, 노트북이 top-to-bottom으로 실제 실행되는지 CI가 검증한다는 점이 특징이다.
이 문서는 "어떤 레시피가 있나"를 넘어, 이 저장소 자체가 어떻게 설계·관리되는가(registry 기반 카탈로그, 노트북 검증 파이프라인, 에이전트 설계 패턴)에서 무엇을 배울 수 있는지에 초점을 둔다.
(저장소: anthropics/claude-cookbooks · Anthropic 공식 · Python/Jupyter · MIT · 노트북 89개 · TrendShift 오늘 Daily 9위)
Claude Cookbooks는 Anthropic이 관리하는 개발자용 예제 저장소다. Claude API 문서가 "이 기능은 이렇게 씁니다"라고 설명한다면, Cookbooks는 "그 기능들을 엮어서 실제 앱을 만들면 이렇게 됩니다"를 통째로 실행 가능한 코드로 보여준다.
API 레퍼런스가 "밀가루·설탕·오븐의 사용법"을 나열한 식재료 설명서라면, Cookbooks는 "팬케이크 만들기", "케이크 굽기" 같은 완성된 레시피다. 재료를 어떤 순서로, 얼마나, 어떻게 섞는지를 처음부터 끝까지 보여준다.
게다가 이 요리책은 모든 레시피를 CI 로봇이 매번 직접 요리해보고 "정말 완성되는지" 확인한다. 낡아서 안 돌아가는 예제를 방치하지 않는다는 뜻이다.
범위는 넓다. 텍스트 분류·요약·RAG 같은 기본 능력(capabilities)부터, 외부 툴을 붙이는 tool use, 이미지·PDF·차트를 읽는 멀티모달, 프롬프트 품질을 자동 채점하는 평가(evals), 그리고 여러 에이전트를 조율하는 Claude Agent SDK / Managed Agents까지 — "입문 → 실전 → 프로덕션"의 사다리를 하나의 저장소에 담았다.
| 항목 | 내용 |
|---|---|
| 저장소 | anthropics/claude-cookbooks (구 anthropic-cookbook) |
| 운영 주체 | Anthropic 공식 + 커뮤니티 기여(authors.yaml로 관리) |
| 핵심 콘텐츠 | Jupyter 노트북 89개 + 실행 가능한 파이썬 에이전트 프로젝트 |
| 언어/런타임 | Python 3.11~3.12, Jupyter, anthropic SDK ≥0.109, claude-agent-sdk ≥0.1.50 |
| 패키지 관리 | uv (pyproject.toml + uv.lock), ruff, pytest, pre-commit |
| 카탈로그 | registry.yaml — 85개 레시피 항목을 카테고리·저자·경로로 색인 |
| 라이선스 | MIT |
Claude로 뭔가 만들려고 검색하면 블로그·유튜브가 쏟아지지만, 버전이 낡거나 틀린 경우가 많다. Cookbooks는 모델을 만든 Anthropic이 직접 관리한다. CLAUDE.md에는 "항상 최신 모델 별칭(claude-sonnet-5, claude-opus-4-8 등)을 쓰고 날짜 박힌 모델 ID는 금지"라는 규칙까지 못박혀 있고, /model-check 슬래시 커맨드가 이를 CI에서 자동 검사한다.
가장 큰 차별점은 실행 검증이다. scripts/validate_notebooks.py와 nbval 기반 테스트가 노트북을 실제로 실행해 오류 없이 끝까지 도는지 확인한다. README를 베낀 죽은 예제가 아니라, clone 후 uv sync 한 번이면 바로 돌아가는 살아있는 코드라는 뜻이다.
초기엔 분류·RAG·요약 같은 단발 기능 위주였지만, 지금은 무게중심이 에이전트로 옮겨갔다. registry의 카테고리 분포만 봐도 드러난다:
| 카테고리 | 레시피 수 | 성격 |
|---|---|---|
| Tools | 23 | 툴 사용·통합(client-side tool, JSON 추출 등) |
| Agent Patterns | 20 | 프롬프트 체이닝·라우팅·오케스트레이터·평가자-최적화기 |
| RAG & Retrieval | 18 | contextual retrieval, 벡터DB, 지식그래프 |
| Claude Managed Agents | 10 | Anthropic 호스팅 상태유지 에이전트 실전 |
| Claude Agent SDK | 8 | 연구 에이전트 → 멀티에이전트 오케스트레이션 |
| Multimodal | 8 | 비전·차트·폼 추출 |
| Evals | 7 | 평가·벤치마크 패턴 |
| Skills | 4 | 커스텀 Skill 제작(금융 애플리케이션 등) |
| Thinking | 2 | extended thinking |
즉 단순 API 호출 예제집에서 "에이전트를 설계·평가·운영하는 법"을 가르치는 종합 교재로 진화했다. 이게 지금 트렌딩하는 이유다 — 다들 에이전트를 만들고 싶어 하는데, 공식 레퍼런스 구현이 여기 다 있다.
LangChain 문서·예제는 프레임워크 종속적이고 추상화 계층이 두껍다. Cookbooks는 반대로 SDK를 얇게 직접 호출해서, "프레임워크 마법" 없이 무슨 일이 일어나는지 그대로 드러낸다. 배우기엔 이쪽이 투명하다.
Python >=3.11,<3.13 위에서 돈다. 핵심 의존성은 anthropic>=0.109(Claude API 공식 SDK)와 claude-agent-sdk>=0.1.50(에이전트 루프 구축용)이다. 여기에 노트북 실행 환경(jupyter, ipykernel, notebook)과 데이터 도구(numpy, pandas, matplotlib, networkx)가 얹힌다. 임베딩은 voyageai를 기본으로 쓴다.
uv sync 하나로 uv.lock에 고정된 정확한 버전을 그대로 재현 설치한다. 이 저장소는 pip install 대신 uv를 표준으로 쓴다.| 도구 | 역할 |
|---|---|
| ruff | 포매터 + 린터. line-length 100, 큰따옴표. 노트북(.ipynb)도 검사하되 mid-file import(E402)·재정의(F811) 등은 완화 |
| pytest + nbval | 노트북을 실제로 실행해 셀이 에러 없이 도는지 검증. slow 마커로 무거운 노트북 분리 |
| pre-commit | 커밋 전 포맷·노트북 구조·시크릿(detect-secrets) 자동 검사 |
| tox + tox-uv | 여러 파이썬 버전에서 매트릭스 테스트 |
| Makefile | make format / lint / check / fix / test 로 명령을 단순화 |
이 저장소의 "숨은 뼈대"는 세 개의 YAML이다:
| 파일 | 내용 |
|---|---|
| registry.yaml | 레시피 85개의 카탈로그. 각 항목이 title / description / path / authors / categories를 가진다. 웹사이트·검색이 이걸 읽는다 (약 27KB) |
| authors.yaml | 기여자 정보(이름·링크). 새 기여자는 여기 추가 → validate_authors_sorted.py가 정렬 검사 |
| lychee.toml | 깨진 링크 검사기(lychee) 설정 — 죽은 링크를 CI에서 잡는다 |
일반 노트북 외에, 별도 pyproject.toml을 가진 독립 프로젝트가 두 개 있다: claude_agent_sdk/(연구→멀티에이전트 튜토리얼 8종)와 managed_agents/(Anthropic 호스팅 런타임 실전). 이들은 @anthropic-ai/claude-code CLI, node, MCP 서버(Linear·Sentry·Slack 커넥터) 같은 외부 요소까지 물린다.
겉보기엔 "예제 노트북 폴더"지만, 뚜껑을 열면 린터·테스트·CI·링크검사·시크릿검사·카탈로그 자동화가 다 갖춰진 정식 오픈소스 프로젝트다. 예제의 품질을 "코드 프로젝트 수준"으로 관리하겠다는 의지가 도구 선택에 그대로 드러난다.
노트북 파일이 여기저기 흩어져 있어도, "어떤 레시피가 존재하는가"의 단일 진실원은 registry.yaml이다. 새 레시피를 추가하는 절차가 CLAUDE.md에 명문화돼 있다: ① 적절한 폴더에 노트북 생성 → ② registry에 title/description/path/authors/categories 등록 → ③ 새 기여자면 authors.yaml 추가 → ④ 품질검사 후 PR. /add-registry 슬래시 커맨드가 이 등록을 돕는다.
도서관에 책(노트북)을 아무 서가에 꽂아도, 카드 목록(registry)만 정확하면 검색·분류·웹사이트 렌더링이 전부 자동으로 굴러간다. 콘텐츠와 색인을 분리한 전형적인 데이터 기반 설계다 — 참고로 이 딥다이브 저장소의 repo_index.json도 똑같은 철학을 쓴다.
대부분의 예제 저장소는 노트북이 낡아 죽는다. Cookbooks는 이를 CI로 방어한다. scripts/validate_notebooks.py가 노트북 구조(셀 타입·메타데이터·출력 유지 여부)를 검사하고, nbval이 노트북을 top-to-bottom 실제 실행해 예외가 나는지 본다. CLAUDE.md의 규칙 "노트북 출력은 일부러 남긴다(데모용) · 한 노트북에 한 개념 · 끝까지 에러 없이 실행"이 이 파이프라인과 짝을 이룬다.
.claude/ 폴더가 흥미롭다. commands/에 model-check.md, notebook-review.md, link-review.md, review-pr.md 같은 슬래시 커맨드가, agents/에 code-reviewer.md 서브에이전트가, skills/에 cookbook-audit 스킬이 들어 있다. 즉 "AI로 개발하는 저장소를, AI 도구(Claude Code)로 리뷰·검증한다" — 도그푸딩(자기 제품을 자기가 씀)의 교과서적 사례다.
patterns/agents/는 Anthropic의 유명한 글 "Building Effective Agents"의 최소 참조 구현이다. 프레임워크 없이 순수 SDK 호출로 다섯 가지 패턴을 보여준다:
| 패턴 | 핵심 아이디어 |
|---|---|
| Prompt Chaining | 작업을 단계로 쪼개 한 LLM 출력이 다음 입력이 되게 |
| Routing | 입력을 분류해 알맞은 전문 프롬프트로 분기 |
| Parallelization | 여러 LLM 호출을 병렬로 돌려 취합 |
| Orchestrator-Workers | 지휘자 LLM이 하위 작업을 쪼개 워커에게 위임 |
| Evaluator-Optimizer | 한 LLM이 만들고, 다른 LLM이 채점해 반복 개선 |
이 다섯은 지금 나오는 거의 모든 에이전트 프레임워크의 바탕 개념이다. 여기서 "맨살"로 익히면 어떤 프레임워크를 봐도 구조가 보인다.
capabilities/(기본기) → tool_use/·multimodal/(확장) → patterns/agents/(설계 원리) → claude_agent_sdk/(직접 조립) → managed_agents/(운영). 폴더 순서가 곧 커리큘럼이다.
capabilities/retrieval_augmented_generation/guide.ipynb와 contextual-embeddings/가 핵심. 단순 임베딩 검색을 넘어 Contextual Retrieval(청크마다 문서 맥락을 붙여 임베딩·BM25 정확도를 끌어올리는 기법)까지 다룬다. 평가(evaluation) 폴더가 함께 있다는 점이 중요 — 검색 품질을 눈대중이 아니라 수치로 측정하는 습관을 배운다.
calculator_tool.ipynb(툴 호출 기본), customer_service_agent.ipynb(client-side 툴로 실제 에이전트), extracting structured JSON(툴 스키마로 JSON 강제). "함수 호출/구조화 출력"이 어떻게 같은 메커니즘인지 몸으로 익힌다.
tool_use/context_engineering/는 메모리·컴팩션·툴 결과 비우기(clearing)로 긴 대화의 문맥을 관리하는 법을 다룬다. 에이전트가 오래 돌수록 문맥창이 터지는 문제를 어떻게 다루는지 — 실전 에이전트의 생존 기술이다.
00_The_one_liner_research_agent(가장 단순한 연구 에이전트)에서 시작해 01_chief_of_staff(멀티스텝), 03_site_reliability(SRE 자동화), 06_vulnerability_detection(보안 스캐닝), 07_Hosting(배포)까지. 번호 순서대로 따라가면 연구 에이전트 → 멀티에이전트 오케스트레이션 → 호스팅의 전 과정을 밟는다. 04는 OpenAI Agents SDK에서 마이그레이션하는 법이라, 타 프레임워크 사용자에게 유용하다.
가장 실무적인 부분. sre_incident_responder.ipynb는 알림 → 세션 시작 → 조사 → PR 생성 → 병합 전 사람 승인 대기라는 human-in-the-loop 게이트를 그대로 구현한다. CMA_iterate_fix_failing_tests.ipynb가 입문용으로 모든 API 형태를 소개한다. Linear·Sentry·Slack MCP 커넥터를 붙이는 실제 코드가 폴더에 들어 있다.
data_analyst_agent.ipynb의 샘플 CSV를 내 실제 데이터로 바꿔 돌려보라. 예제가 "돌아가는 상태"로 검증돼 있으니, 바뀌는 건 데이터뿐이라 실패 지점을 빠르게 좁힐 수 있다.
이 저장소는 로컬에서 모델을 돌리는 게 아니라 Claude API를 호출한다. 따라서 GPU·대용량 RAM이 필요 없고, 노트북을 실행할 수 있는 평범한 개발 PC면 충분하다. 진짜 관문은 유효한 ANTHROPIC_API_KEY(호출마다 과금)다.
| 요구사항 | 내용 |
|---|---|
| Python | 3.11 이상 3.13 미만 |
| 패키지 매니저 | uv (권장). curl -LsSf https://astral.sh/uv/install.sh | sh |
| API 키 | ANTHROPIC_API_KEY (platform.claude.ai에서 발급) — .env에 저장 |
| 추가(일부 노트북) | node + @anthropic-ai/claude-code(Agent SDK), GITHUB_TOKEN(observability), VOYAGE_API_KEY(임베딩), Pinecone 키 등 |
# 1. 클론 & 의존성 설치(uv.lock 그대로 재현)
git clone https://github.com/anthropics/claude-cookbooks.git
cd claude-cookbooks
uv sync --all-extras
# 2. pre-commit 훅 설치(선택)
uv run pre-commit install
# 3. API 키 설정
cp .env.example .env
# .env를 열어 ANTHROPIC_API_KEY=... 입력레시피는 실제 API를 호출하므로 실행할수록 토큰 비용이 든다. 특히 에이전트 노트북은 여러 번 반복 호출하니 사용량을 확인하며 돌려라.
CLAUDE.md 규칙대로 .env는 절대 커밋 금지 — dotenv.load_dotenv()로 로드하고 os.getenv()로만 접근한다. pre-commit의 detect-secrets가 실수를 잡아준다.
capabilities/summarization/ 노트북을 열어, 예제 텍스트를 내가 가진 긴 문서(회의록·논문)로 바꿔 실행. 프롬프트를 조금씩 고치며 출력이 어떻게 달라지는지 관찰한다.
tool_use/calculator_tool.ipynb의 툴 정의를 참고해, 날씨 API나 환율 API를 툴로 등록하고 Claude가 스스로 호출하게 만든다. 툴 스키마(JSON Schema) 작성이 핵심.
patterns/agents/basic_workflows.ipynb를 따라 프롬프트 체이닝·라우팅·병렬화를 구현한 뒤, evaluator_optimizer.ipynb를 응용해 "글 쓰고 → 스스로 채점 → 재작성" 루프를 만든다.
contextual-embeddings/로 문맥 청킹 RAG를 만들고, 함께 있는 evaluation 노트북으로 일반 RAG vs 컨텍스추얼 RAG의 검색 정확도를 수치로 비교한다. "감이 아니라 지표로" 개선하는 훈련.
managed_agents/sre_incident_responder.ipynb를 클론해, 가짜 알림을 트리거로 에이전트가 조사→PR 생성까지 하되 병합 직전 사람 승인 게이트를 넣는다. 자동화와 안전장치의 균형을 설계하는 실전.
| 주차 | 주제 | Cookbooks 경로 + 목표 |
|---|---|---|
| 1주차 | 기본기 | capabilities/ 전체 + misc/(JSON모드·캐싱·배치). 프롬프트→구조화 출력→요약·분류를 확실히 |
| 2주차 | 툴 & 멀티모달 | tool_use/ + multimodal/. 함수 호출, 비전, 서브에이전트(Haiku↔Opus) 이해 |
| 3주차 | RAG & 평가 | retrieval_augmented_generation/ + evals/. contextual retrieval와 평가 지표 설계를 한 세트로 |
| 4주차 | 에이전트 & 운영 | patterns/agents/ → claude_agent_sdk/ → managed_agents/. 5대 패턴 → SDK 조립 → 호스팅·human-in-the-loop |
먼저 Anthropic의 "Building Effective Agents" 글을 읽고 patterns/agents/ 코드와 대조하면 이론↔구현이 맞물린다. 완전 초심자라면 README가 가리키는 Claude API Fundamentals 코스를 0주차로.
claude_agent_sdk/ 튜토리얼의 기반.uv sync로 lock 파일을 그대로 재현 설치한다.