The Claude Cookbook Developer's Guide: Best Practices for Building with Claude AI

The Claude Cookbook is Anthropic's official collection of Jupyter notebooks and Python examples for developers building with the Claude API. This guide distills the essential practices and patterns from the repository to help you build robust, maintainable Claude applications while avoiding common pitfalls.

Setting Up Your Development Environment

Installation and Configuration

The Cookbook uses modern Python tooling with uv for dependency management. Here's how to set up your environment:

# Install all dependencies with extras
uv sync --all-extras
Set up pre-commit hooks for quality control
uv run pre-commit install
Configure your API key securely
cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

Critical Security Note: Never commit .env files to version control. The Cookbook enforces this through .gitignore and pre-commit hooks. Always load environment variables using:

import os
from dotenv import load_dotenv
load_dotenv()  # Loads from .env file
api_key = os.getenv("ANTHROPIC_API_KEY")

Development Workflow Commands

The repository includes a comprehensive Makefile for common development tasks:

make format    # Format code with ruff
make lint      # Run linting checks
make check     # Run format-check + lint (pre-commit)
make fix       # Auto-fix issues + format
make test      # Run pytest tests

You can also run these commands directly with uv:

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

Code Quality and Style Guidelines

Consistent Code Formatting

The Cookbook enforces strict formatting rules to maintain consistency:

• Line length: 100 characters maximum
• Quotes: Double quotes for strings
• Formatter: Ruff (replaces black, isort, and flake8)
• Notebook exceptions: Notebooks have relaxed rules for:

- Mid-file imports (E402) - Redefinitions (F811) - Variable naming (N803, N806)

Dependency Management

Always use uv for adding dependencies:

# Add production dependency
uv add anthropic
Add development dependency
uv add --dev pytest

Never edit pyproject.toml directly for dependencies. This ensures consistent version resolution and lockfile management.

Model Selection: Critical Best Practices

Claude Model IDs: What to Use (and What to Avoid)

Choosing the right model ID is crucial for application stability. The Cookbook provides clear guidelines:

# ✅ CORRECT: Use non-dated model aliases
model = "claude-sonnet-4-6"      # Latest Sonnet
model = "claude-haiku-4-5"       # Latest Haiku
model = "claude-opus-4-6"        # Latest Opus
❌ WRONG: Never use dated model IDs
model = "claude-sonnet-4-6-20250514"  # Avoid!

Using non-dated aliases ensures your application automatically uses the latest version of each model family without code changes.

Amazon Bedrock Model IDs

For Bedrock deployments, use the specific Bedrock model IDs:

# Bedrock model IDs (different format!)
bedrock_models = {
    "opus": "anthropic.claude-opus-4-6-v1",
    "sonnet": "anthropic.claude-sonnet-4-5-20250929-v1:0",
    "haiku": "anthropic.claude-haiku-4-5-20251001-v1:0"
}
For global endpoints (recommended)
global_model = "global.anthropic.claude-opus-4-6-v1"

Important Note: Bedrock models before Opus 4.6 require dated IDs in their Bedrock model ID format. Always check the latest documentation for current model IDs.

Project Structure and Organization

The Cookbook organizes examples into logical 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

This structure helps developers find relevant examples quickly. When contributing, place your notebook in the most appropriate directory.

Git Workflow and Collaboration

Branch Naming Convention

Use descriptive branch names:

<username>/<feature-description>

Examples:

john/rag-multilingual-support
sarah/fix-temperature-parameter

Commit Message Format

Follow Conventional Commits specification:

feat(rag): add multilingual document support
fix(api): handle rate limit errors gracefully
docs(examples): update vision API examples
style: apply ruff formatting

Notebook Development Guidelines

Creating Effective Cookbook Notebooks

When creating notebooks for the Cookbook repository:

• One concept per notebook: Each notebook should demonstrate a single, clear concept or pattern
• Keep outputs in notebooks: Outputs are intentional for demonstration purposes
• Test top-to-bottom execution: Ensure notebooks run completely without errors
• Add to registry: Register new notebooks in registry.yaml with:

- Title and description - Path to notebook - Author(s) - Relevant categories

Example registry entry:

- title: "Advanced RAG with Query Rewriting"
  description: "Implement retrieval-augmented generation with query expansion and rewriting"
  path: "capabilities/rag/advanced_rag_query_rewriting.ipynb"
  authors: ["alexj"]
  categories: ["rag", "retrieval"]

Quality Assurance

The repository includes automated quality checks:

• Pre-commit hooks: Validate formatting and structure
• Notebook validation: Ensure notebooks are executable
• Model ID validation: Check for correct model references

Run make check before committing to catch issues early.

Claude Code Integration

The repository includes special slash commands for Claude Code:

• /notebook-review - Get feedback on notebook quality and structure
• /model-check - Validate Claude model references in your code
• /link-review - Check links in changed files for validity

These commands help maintain quality standards when working with Claude as a coding assistant.

Adding Your Own Cookbook

Follow this process to contribute a new example:

• Create the notebook in the appropriate directory
• Add entry to registry.yaml with metadata
• Add author info to authors.yaml if you're a new contributor
• Run quality checks: make check
• Submit a pull request with descriptive title and changes

Common Pitfalls to Avoid

• Hardcoding API keys: Always use environment variables
• Using deprecated model IDs: Stick to non-dated aliases
• Ignoring quality checks: Always run make check before committing
• Overly complex notebooks: Keep examples focused and runnable
• Missing metadata: Ensure all notebooks are properly registered

Key Takeaways

• Always use non-dated model aliases like claude-sonnet-4-6 instead of dated versions for API stability
• Secure API key management through environment variables and never commit .env files
• Maintain code quality with the provided make commands and pre-commit hooks
• Follow the project structure when organizing your Claude AI projects
• Contribute effectively by following the notebook guidelines and registration process

By following these practices from the official Claude Cookbook, you'll build more robust, maintainable, and production-ready Claude AI applications that align with Anthropic's recommended patterns and best practices.