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

The Claude Cookbook repository is Anthropic's official collection of examples, patterns, and best practices for developers building with the Claude API. This guide distills the essential practices and workflows that will help you build more effective, maintainable, and secure Claude-powered applications.

Setting Up Your Development Environment

Installation and Configuration

The Cookbook uses modern Python tooling with uv for dependency management. Here's how to get started:

# Clone the repository (or adapt for your own project)
git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
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

Secure API Key Management

Never commit .env files or hardcode API keys. The Cookbook enforces this critical security practice:

# CORRECT: Load from environment variables
import os
from dotenv import load_dotenv
load_dotenv()  # Loads from .env file
api_key = os.environ.get("ANTHROPIC_API_KEY")
Use with the Anthropic client
from anthropic import Anthropic
client = Anthropic(api_key=api_key)

# WRONG: Never do this!
api_key = "sk-ant-..."  # Hardcoded key
client = Anthropic(api_key="sk-ant-...")  # Hardcoded in constructor

Model Selection: Critical Guidelines

Choosing the right Claude model is essential for performance, cost, and compatibility. The Cookbook provides specific rules:

Always Use Non-Dated Model Aliases

# CORRECT: Use the current alias
model = "claude-3-5-sonnet-20241022"  # Current model
Or use the latest available
model = "claude-3-5-sonnet-latest"
WRONG: Never use dated model IDs in production
model = "claude-3-5-sonnet-20241022"  # This will eventually become outdated

Bedrock Model IDs Follow Different Formats

When using Claude through AWS Bedrock, you must use the specific Bedrock model IDs:

# AWS Bedrock model IDs (examples - check docs for current versions)
bedrock_models = {
    "opus": "anthropic.claude-3-opus-20240229-v1:0",
    "sonnet": "anthropic.claude-3-sonnet-20240229-v1:0",
    "haiku": "anthropic.claude-3-haiku-20240307-v1:0",
}
For global endpoints (recommended)
global_model = "global.anthropic.claude-3-opus-20240229-v1:0"

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

Code Quality and Development Workflow

Automated Code Quality Checks

The Cookbook includes a comprehensive Makefile with quality commands:

# Format your code according to Cookbook standards
make format
Run linting checks
make lint
Check formatting and linting (run before commits)
make check
Auto-fix issues and format
make fix
Run tests
make test

You can also run these commands directly with uv:

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

Code Style Standards

The Cookbook enforces consistent styling:

• 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), and variable naming (N803, N806) to maintain educational clarity

Git and Collaboration Workflow

Branch Naming Convention

Use descriptive branch names following this pattern:

<username>/<feature-description>

Examples:

john/rag-implementation
sarah/fix-tool-use-example

Commit Messages (Conventional Commits)

Follow the conventional commits specification for clear, searchable commit history:

feat(rag): add vector similarity search implementation
fix(api): resolve timeout issue in batch processing
docs(examples): update vision API usage examples
style: apply ruff formatting to tool_use notebooks
chore(deps): update anthropic SDK to version 0.25.0

Working with Jupyter Notebooks

Notebook Best Practices

When contributing notebooks to the Cookbook (or creating your own educational materials):

• Keep outputs in notebooks - Outputs are intentional for demonstration purposes
• One concept per notebook - Focus on teaching a single skill or pattern
• Test execution - Ensure notebooks run top-to-bottom without errors
• Clear structure - Use markdown cells to explain concepts before code

Notebook Validation

The Cookbook includes automated notebook checks. Before submitting a notebook:

# Run the notebook quality review
make check  # Includes notebook validation
Or use the specific Claude Code command
/notebook-review

Project Structure and Organization

Understanding the Cookbook's organization helps you find relevant examples:

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

Adding Your Own Cookbook

If you want to contribute to the official repository:

• Create notebook in the appropriate directory
• Add entry to registry.yaml with title, description, path, authors, categories
• Add author info to authors.yaml if you're a new contributor
• Run quality checks with make check
• Submit PR with descriptive title and conventional commit messages

Claude Code Integration

The Cookbook repository includes special slash commands for Claude Code (Claude's IDE integration):

• /notebook-review - Automated notebook quality review
• /model-check - Validate Claude model references in your code
• /link-review - Check links in changed files for validity

These commands run automatically in CI but can also be used during development for immediate feedback.

Dependency Management

Adding Dependencies

Always use uv for dependency management:

# Add production dependency
uv add anthropic
Add development dependency
uv add --dev pytest
Never edit pyproject.toml directly for dependencies!

Version Pinning

While the Cookbook may use specific versions for reproducibility, in your own projects consider:

# For production: pin major versions
anthropic = "^0.25.0"
For development: can be less strict
pytest = ">=8.0.0"

Testing and Validation

Running Tests

The Cookbook uses pytest for testing. Run tests with:

make test
or
uv run pytest

Pre-commit Hooks

Pre-commit hooks automatically check your code before commits. They validate:

• Code formatting with ruff
• Notebook structure and cleanliness
• No committed secrets or API keys
• Conventional commit messages

To manually run all pre-commit checks:

uv run pre-commit run --all-files

Key Takeaways

• Always use non-dated model aliases like claude-3-5-sonnet-latest instead of specific dated versions to ensure compatibility and access to the latest improvements.

• Never commit API keys - Use environment variables with .env files (excluded via .gitignore) and load them securely with dotenv.load_dotenv().

• Maintain code quality automatically - Use the provided make commands or uv run with ruff to format, lint, and fix code before committing.

• Follow conventional commits for clear, searchable commit history that helps with maintenance and collaboration.

• Structure notebooks intentionally - Keep outputs for demonstration, focus on one concept per notebook, and ensure they run error-free from top to bottom.

By following these practices from the Claude Cookbook, you'll build more robust, maintainable, and secure Claude AI applications while staying aligned with Anthropic's recommended development patterns.