Claude Cookbooks: bộ notebook chính thức để build với Claude API, kèm lộ trình 4 tuần

Đọc tài liệu API xong, phần lớn dev vẫn kẹt ở câu hỏi "ghép lại thành sản phẩm thế nào?": tool use chạy vòng lặp ra sao, prompt caching đặt breakpoint ở đâu, agent dài hơi thì nén context thế nào. Claude Cookbooks (repo anthropics/claude-cookbooks, trước đây tên là anthropic-cookbook) là bộ notebook chính thức của Anthropic trả lời đúng câu hỏi đó: mỗi notebook là một "công thức" chạy được, có code để copy vào dự án.

GitHub: https://github.com/anthropics/claude-cookbooks · khoảng 54 nghìn sao · Jupyter Notebook (Python) · MIT

Repo có gì?

README chỉ liệt kê một phần; cây thư mục thực tế rộng hơn nhiều. Dưới đây là các thư mục đáng chú ý nhất vào thời điểm viết:

Ảnh chụp cho thấy các commit gần đây cập nhật model mặc định lên thế hệ 5.5 và SDK 2.0, tức repo được bảo trì song song với API, không phải kho mẫu bỏ hoang.

Bắt đầu thế nào?

Bạn cần một API key. README gợi ý người mới học khoá Claude API Fundamentals (repo anthropics/courses) trước. Cách chạy gọn nhất:

git clone https://github.com/anthropics/claude-cookbooks.git
cd claude-cookbooks
export ANTHROPIC_API_KEY="sk-ant-..."   # hoặc dùng file .env theo .env.example
uv sync                                  # repo có pyproject.toml + uv.lock
uv run jupyter lab

Một số thư mục (ví dụ claude_agent_sdk/, managed_agents/) có pyproject.toml và .env.example riêng; đọc README của thư mục trước khi chạy. Không muốn clone? Mở notebook ngay trên GitHub để đọc như một bài hướng dẫn.

Lộ trình đọc gợi ý

1. Tuần 1, nền tảng: tool_use/calculator_tool → tool_use/customer_service_agent → tool_use/extracting_structured_json. Hiểu vòng lặp gọi tool và cách ép đầu ra có cấu trúc.
2. Tuần 2, chi phí: misc/prompt_caching → misc/batch_processing → cost_optimization. Đây là ba notebook trả tiền cho chính chúng nhanh nhất. Đọc kèm bài Prompt caching.
3. Tuần 3, chất lượng: misc/building_evals → tool_evaluation → capabilities/contextual-embeddings. Có eval rồi mới tối ưu prompt.
4. Tuần 4, agent: chuỗi claude_agent_sdk/00 đến 08, rồi chọn vài notebook managed_agents phù hợp kiến trúc của bạn.

Lưu ý và rủi ro

• Tốn tiền thật: mọi cell gọi API đều tính phí vào tài khoản của bạn. Các notebook về agent, evals hay batch có thể gọi model nhiều lần; đặt giới hạn chi tiêu trong Console trước khi chạy hàng loạt.
• Link trong README có thể cũ: nhiều link còn trỏ tới tên repo cũ anthropic-cookbook (GitHub tự chuyển hướng), và một số notebook đã đổi chỗ. Tìm theo tên file trong cây thư mục nếu link lỗi.
• Code mẫu không phải code production: notebook ưu tiên dễ đọc, thường thiếu retry, xử lý lỗi, giới hạn rate. Khi copy, thêm phần này (xem lỗi và rate limit).
• Tên model thay đổi: notebook cũ có thể còn ID model đã ngừng. Luôn đối chiếu với trang models trong tài liệu chính thức.
• Phần tích hợp bên thứ ba (Pinecone, Voyage AI, MongoDB…) cần tài khoản riêng và có thể phát sinh chi phí.

Áp dụng thế nào?

• Dev: Trước khi tự viết một tính năng Claude, tìm notebook gần nhất trong repo và bắt đầu từ đó. Thường tiết kiệm được vài giờ thử sai về định dạng message và vòng lặp tool.
• Tech Lead: Chọn 4–5 notebook làm "giáo trình onboarding" AI cho team. Notebook cost_optimization và latency_optimization là mẫu tốt để chuẩn hoá cách đo trước khi chọn model.
• PM: Lướt capabilities/ và managed_agents/ để biết cái gì đã có mẫu sẵn. Tính năng có cookbook chính thức thường rủi ro thấp hơn, ước lượng nhanh hơn.