The Complete Guide to Building with Claude: Cookbook Setup, Workflow, and Best Practices

If you're building applications with the Claude API, the Anthropic Cookbook is your essential companion. It's a collection of Jupyter notebooks and Python examples that demonstrate everything from basic API calls to advanced patterns like tool use, multimodal processing, and extended thinking.

But the cookbook isn't just a set of examples—it's a well-structured development environment with strict conventions for code quality, model usage, and collaboration. Whether you're contributing to the cookbook or using it as a template for your own projects, understanding these conventions will save you hours of debugging.

In this guide, you'll learn:

• How to set up the cookbook environment in minutes
• The exact Claude model IDs you should (and shouldn't) use
• Code style rules enforced by Ruff and pre-commit hooks
• Git workflow with conventional commits
• How to run quality checks and validate your notebooks

Let's dive in.

Setting Up the Cookbook Environment

The cookbook uses uv—a fast Python package manager—to manage dependencies. Here's how to get started.

Step 1: Install Dependencies

uv sync --all-extras

This command installs all required packages, including Jupyter, Ruff, and the Anthropic SDK.

Step 2: Install Pre-commit Hooks

uv run pre-commit install

Pre-commit hooks automatically check your code for formatting and structural issues before every commit. This catches problems early.

Step 3: Configure Your API Key

cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

Critical rule: Never commit .env files. The .gitignore already excludes them, but double-check before pushing. Use dotenv.load_dotenv() in your code, then access keys via os.environ or os.getenv().

Step 4: Verify Your Setup

Run the format check to ensure everything is working:

uv run ruff check .

If you see no errors, you're ready to build.

Development Commands You'll Use Daily

The cookbook provides a Makefile with convenient shortcuts. Here are the most important ones:

If you prefer using uv directly (recommended for CI/CD pipelines):

uv run ruff format .           # Format all files
uv run ruff check .            # Lint all files
uv run ruff check --fix .      # Auto-fix issues
uv run pre-commit run --all-files  # Run all pre-commit hooks

Pro tip: Run make check before every commit. It's faster than waiting for CI to fail.

Code Style: The Ruff Rules

The cookbook enforces a consistent code style using Ruff, a fast Python linter and formatter. Here's what you need to know:

• Line length: 100 characters (not the standard 88)
• Quotes: Double quotes (") everywhere
• Formatter: Ruff (no Black, no isort)

Notebooks (.ipynb files) have relaxed rules for:

• Mid-file imports (E402) — allowed for demonstration flow
• Redefinitions (F811) — sometimes necessary in tutorials
• Variable naming (N803, N806) — more flexibility for educational clarity

But for Python scripts (.py files), all rules are enforced strictly.

Claude Model IDs: Get This Right

One of the most common mistakes developers make is using dated model IDs. The cookbook explicitly warns against this.

Correct Model IDs (Non-dated Aliases)

Always use the alias, not the specific version date:

Never use claude-sonnet-4-6-20250514 or similar dated IDs. The alias always points to the latest stable version.

Bedrock Model IDs

If you're using Claude through AWS Bedrock, the IDs follow a different format:

Important: Prepend global. for global endpoints (recommended for better latency):

model_id = "global.anthropic.claude-opus-4-6-v1"

Also note: Bedrock models before Opus 4.6 require dated IDs. Always check docs.anthropic.com for the latest.

Example: Correct API Call

import anthropic
from dotenv import load_dotenv
import os
load_dotenv()
client = anthropic.Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY")
)
response = client.messages.create(
    model="claude-sonnet-4-6",  # Correct: non-dated alias
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)
print(response.content[0].text)

Git Workflow: Conventional Commits

The cookbook uses conventional commits for clear, automated changelogs. Here's the format:

<type>(<scope>): <description>

Common Types

Branch Naming

<username>/<feature-description>

Example: johndoe/add-rag-notebook

Example Commits

feat(tool_use): add weather API integration notebook
fix(multimodal): correct image encoding in base64 example
docs: update README with new cookbook structure
style: apply ruff formatting to all notebooks

Quality Checks: Before You Commit

Before submitting a pull request, run these checks:

1. Run make check

This validates formatting and linting. If it fails, run make fix to auto-correct issues.

2. Validate Notebooks

The cookbook includes slash commands that work in Claude Code and CI:

• /notebook-review — Reviews notebook quality (structure, outputs, clarity)
• /model-check — Validates that all Claude model references are correct (non-dated)
• /link-review — Checks that all links in changed files are valid

3. Test Notebooks Run Top-to-Bottom

Notebooks should execute without errors from the first cell to the last. Keep outputs in the notebook (they're intentional for demonstration).

Project Structure: Where to Find What

The cookbook is organized into clear directories:

capabilities/       # Core Claude capabilities (RAG, classification, etc.)
skills/             # Advanced skill-based notebooks
tool_use/           # Tool use and integration patterns
multimodal/         # Vision and image processing
misc/               # Batch processing, caching, utilities
third_party/        # Pinecone, Voyage, Wikipedia integrations
extended_thinking/  # Extended reasoning patterns
scripts/            # Validation scripts
.claude/            # Claude Code commands and skills

When adding a new cookbook, place it in the appropriate directory.

Adding a New Cookbook: Step by Step

If you want to contribute a new notebook:

• Create the notebook in the appropriate directory (see structure above)
• Add an entry to registry.yaml with:

- Title - Description - Path to notebook - Authors - Categories

• Add author info to authors.yaml if you're a new contributor
• Run quality checks (make check and slash commands)
• Submit a PR with a conventional commit message

registry.yaml Entry Example

- title: "Advanced RAG with Claude"
  description: "Build a retrieval-augmented generation system using Claude and vector search"
  path: capabilities/advanced_rag.ipynb
  authors: ["johndoe"]
  categories: ["capabilities", "rag"]

Key Takeaways

• Use uv for dependency management — uv sync --all-extras installs everything you need, and uv add is the only way to add new packages (never edit pyproject.toml directly).
• Always use non-dated Claude model aliases — claude-sonnet-4-6 instead of claude-sonnet-4-6-20250514. For Bedrock, prepend global. and check the docs for the correct format.
• Run make check before every commit — This enforces Ruff formatting (100 char line length, double quotes) and catches issues early.
• Follow conventional commits — Use feat(scope):, fix(scope):, docs:, etc., with branch names like <username>/<feature-description>.
• Validate notebooks with slash commands — Use /notebook-review, /model-check, and /link-review in Claude Code or CI to ensure quality before merging.

Now you're ready to build with Claude like a pro. Happy coding!