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

The Claude Cookbook repository serves as the official collection of examples and best practices for developers building applications with Claude's API. This guide distills the essential development practices, model selection rules, and workflow guidelines that ensure your Claude integrations are robust, maintainable, and effective.

Setting Up Your Development Environment

Proper environment setup is crucial for secure and reproducible Claude development. The Cookbook emphasizes a streamlined approach using modern Python tooling.

Initial Setup Commands

# Install all dependencies with uv (modern Python package manager)
uv sync --all-extras
Set up pre-commit hooks for automated quality checks
uv run pre-commit install
Configure your API key securely
cp .env.example .env
Edit .env and add your ANTHROPIC_API_KEY

Environment Configuration Best Practices

Always load API keys from environment variables, never hardcode them:

import os
from dotenv import load_dotenv
from anthropic import Anthropic
Load environment variables from .env file
load_dotenv()
Access API key securely
api_key = os.getenv("ANTHROPIC_API_KEY")
Initialize the client
client = Anthropic(api_key=api_key)

Critical Security Rule: Never commit .env files to version control. The .env.example file should contain placeholder values without actual secrets.

Development Workflow and Quality Assurance

The Cookbook enforces strict quality standards through automated tooling and consistent commands.

Essential Development Commands

# Format code according to project standards
make format
Run linting checks
make lint
Combined format and lint check
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

• Line length: 100 characters maximum
• Quotes: Double quotes for strings
• Formatter: Ruff (modern, fast Python linter/formatter)
• Notebook exceptions: Jupyter notebooks have relaxed rules for mid-file imports (E402), redefinitions (F811), and variable naming (N803, N806) to accommodate exploratory workflows

Git and Collaboration Workflow

Branch Naming Convention

Use the format: <username>/<feature-description>

Examples:

• alice/rag-implementation
• bob/fix-temperature-parameter
• charlie/add-multimodal-examples

Commit Message Format (Conventional Commits)

feat(api): add streaming response support
fix(tools): resolve JSON parsing error in function calls
docs(examples): update vision API usage examples
style: apply ruff formatting to all files

Dependency Management

Always use uv for dependency management:

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

Important: Never edit pyproject.toml directly for dependency changes. Always use uv commands to ensure proper version resolution and lock file updates.

Model Selection: Critical Guidelines

Choosing the right Claude model and using the correct model IDs is essential for reliable applications.

Standard API Model IDs

# CORRECT: Use non-dated model aliases
MODELS = {
    "sonnet": "claude-sonnet-4-6",
    "haiku": "claude-haiku-4-5",
    "opus": "claude-opus-4-6",
}
NEVER use dated model IDs like these:
"claude-sonnet-4-6-20250514"  # WRONG
"claude-opus-4-6-20250514"    # WRONG

AWS Bedrock Model IDs

Bedrock requires different model ID formats:

# Bedrock model IDs (AWS 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_BEDROCK_MODELS = {
    "opus": "global.anthropic.claude-opus-4-6-v1",
    "sonnet": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "haiku": "global.anthropic.claude-haiku-4-5-20251001-v1:0",
}

Important Notes:

• Bedrock models before Opus 4.6 require dated IDs in their Bedrock model ID
• Always check docs.anthropic.com for the latest model versions and IDs
• Global endpoints (global.) are recommended for Bedrock deployments

Jupyter Notebook Best Practices

Cookbook notebooks follow specific conventions for clarity and reproducibility:

# Notebook structure example
1. Clear title and description in markdown
2. Import statements at the top (with E402 exception)
3. One main concept per notebook
4. Keep outputs visible for demonstration
5. Test that notebooks run top-to-bottom without errors
Example notebook cell structure:
"""
Title: Implementing RAG with Claude
Description: Learn to build a Retrieval-Augmented Generation system
"""
Imports (mid-file imports allowed in notebooks)
import anthropic
import pandas as pd
import numpy as np
Main content with clear sections
...

Testing Notebooks

Always verify that notebooks execute completely:

# Run notebook from command line to test
uv run jupyter nbconvert --to notebook --execute your_notebook.ipynb

Project Structure and Organization

The Cookbook follows a logical directory structure:

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 a New Cookbook

When contributing to the repository:

• Create notebook in the appropriate directory
• Add entry to registry.yaml with:

- Title and description - File path - Author(s) - Relevant categories

• Add author info to authors.yaml if new contributor
• Run quality checks with make check
• Submit PR following branch naming conventions

Automated Quality Checks

The repository includes several automated checks:

Slash Commands (Claude Code and CI)

• /notebook-review - Review notebook quality and structure
• /model-check - Validate Claude model references are current
• /link-review - Check links in changed files for validity

Pre-commit Hooks

Automatically run on each commit:

• Code formatting with Ruff
• Notebook structure validation
• Model ID verification
• Link checking

Key Takeaways

• Security First: Never commit API keys or .env files; always use environment variables and dotenv for local development.

• Model Selection Matters: Use non-dated model aliases for the standard API (claude-sonnet-4-6), and follow the specific Bedrock format for AWS deployments, preferring global endpoints when available.

• Automate Quality: Leverage the provided make commands and pre-commit hooks to maintain code quality, with make check as a mandatory step before committing changes.

• Structured Development: Follow the established project organization, placing notebooks in appropriate directories and maintaining the one-concept-per-notebook principle for clarity and maintainability.

• Modern Tooling: Utilize uv for dependency management and ruff for formatting/linting to ensure consistency and speed in your Claude development workflow.

By following these guidelines from the official Claude Cookbook, you'll build more reliable, maintainable, and effective Claude AI applications that align with Anthropic's best practices and can easily integrate with the broader ecosystem of examples and tools.