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

The Claude Cookbook is Anthropic's official collection of examples and patterns for working with the Claude API. As a professional technical resource, it establishes important development standards that every Claude developer should follow. This guide distills the key practices from the cookbook into actionable recommendations for building reliable, maintainable Claude applications.

Setting Up Your Development Environment

Initial Setup with UV

The cookbook uses uv as its package manager, which provides faster dependency resolution and installation. Here's the proper setup sequence:

# Clone the repository (or adapt for your own project)
git clone https://github.com/anthropics/anthropic-cookbook.git
cd anthropic-cookbook
Install all dependencies including extras
uv sync --all-extras
Set up pre-commit hooks for automated quality checks
uv run pre-commit install
Configure your environment variables
cp .env.example .env
Now edit .env and add your ANTHROPIC_API_KEY

Environment Configuration Best Practices

Never commit .env files to version control. The cookbook demonstrates the proper pattern:

import os
from dotenv import load_dotenv
Load environment variables from .env file
load_dotenv()
Access your API key securely
api_key = os.environ.get("ANTHROPIC_API_KEY")
or
api_key = os.getenv("ANTHROPIC_API_KEY")

Code Quality and Development Workflow

Automated Quality Checks

The cookbook provides a comprehensive Makefile with essential commands:

# Format your code according to project standards
make format
Run linting checks
make lint
Combined format check and linting
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: Use double quotes (") for strings
• Formatter: Ruff (the modern replacement for Black and isort)
• Notebook exceptions: Jupyter notebooks have relaxed rules for:

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

Proper Model Selection and Usage

Claude Model Naming Conventions

One of the most critical aspects of building with Claude is using the correct model identifiers. The cookbook provides clear guidelines:

# ✅ CORRECT - Use non-dated model aliases
MODEL_OPUS = "claude-opus-4-6"
MODEL_SONNET = "claude-sonnet-4-5"
MODEL_HAIKU = "claude-haiku-4-5"
❌ WRONG - Never use dated model IDs
BAD_MODEL = "claude-sonnet-4-6-20250514"  # Avoid!

AWS Bedrock Model IDs

When using Claude through AWS Bedrock, the model IDs follow a different format:

# Bedrock model IDs (check docs.anthropic.com for latest)
BEDROCK_OPUS = "anthropic.claude-opus-4-6-v1"
BEDROCK_SONNET = "anthropic.claude-sonnet-4-5-20250929-v1:0"
BEDROCK_HAIKU = "anthropic.claude-haiku-4-5-20251001-v1:0"
For global endpoints (recommended)
GLOBAL_BEDROCK_OPUS = "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 official documentation for the latest model identifiers.

Git and Collaboration Workflow

Branch Naming Convention

Use descriptive branch names following this pattern:

<username>/<feature-description>

Examples:

john/rag-implementation
sarah/fix-token-counting
team/add-multimodal-examples

Commit Message Format

Follow conventional commits for clear, standardized commit messages:

feat(api): add streaming response support
fix(notebook): correct temperature parameter usage
docs(readme): update installation instructions
style: apply ruff formatting
chore(deps): update anthropic SDK to v0.25.0

The format is: type(scope): description

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style/formatting
• chore: Maintenance tasks

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 creating your own Claude projects, consider adopting a similar organizational pattern based on functionality.

Working with Jupyter Notebooks

Notebook Best Practices

• Keep outputs in notebooks - Unlike typical code repositories, the cookbook intentionally includes notebook outputs for demonstration purposes
• One concept per notebook - Each notebook should focus on teaching or demonstrating a single concept or pattern
• Test execution flow - Ensure notebooks run from top to bottom without errors
• Clear documentation - Include markdown cells that explain the purpose and steps

Example Notebook Structure

# Example of a well-structured notebook cell
Import with explanation
import anthropic
from dotenv import load_dotenv
import os
Load environment variables
load_dotenv()
Initialize client with clear configuration
client = anthropic.Anthropic(
    api_key=os.getenv("ANTHROPIC_API_KEY"),
    # Additional configuration as needed
)
Demonstrate a specific pattern
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1000,
    temperature=0.7,
    messages=[
        {"role": "user", "content": "Explain the concept of few-shot prompting."}
    ]
)
print(response.content[0].text)

Adding New Examples to the Cookbook

If you're contributing to the official cookbook or creating similar documentation for your team:

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

- title: "Advanced RAG with Query Rewriting"
     description: "Demonstrates query rewriting techniques for improved retrieval"
     path: "capabilities/rag_query_rewriting.ipynb"
     authors: ["your-username"]
     categories: ["rag", "retrieval"]

• Register authors in authors.yaml if new contributor
• Run quality checks with make check before submitting

Slash Commands for Development

The cookbook includes specialized commands for Claude Code and CI:

• /notebook-review - Automated review of notebook quality and structure
• /model-check - Validation of Claude model references to ensure they're current
• /link-review - Checks links in changed files for validity

These commands help maintain quality and catch common issues before they reach production.

Dependency Management

Always use uv for dependency management:

# Add production dependencies
uv add anthropic python-dotenv
Add development dependencies
uv add --dev ruff pre-commit pytest
Never edit pyproject.toml directly for dependencies

This ensures consistent dependency resolution across all environments.

Testing and Validation

Before committing any changes:

• Run make check to ensure code quality
• Verify notebooks execute without errors
• Check that all model references use current, non-dated aliases
• Ensure no sensitive data (API keys) is committed
• Validate links and references

The pre-commit hooks automate much of this, but manual verification is still important for complex changes.

Key Takeaways

• Always use non-dated model aliases like claude-sonnet-4-5 instead of dated versions. For Bedrock, use the specific Bedrock model IDs from the official documentation.

• Secure API key management is critical. Never commit .env files, use dotenv.load_dotenv() for local development, and access keys via os.environ or os.getenv().

• Maintain code quality with automated tools. Use make check before committing, follow the established code style (100 char lines, double quotes), and leverage pre-commit hooks.

• Organize projects logically following the cookbook's structure. Group related functionality together and maintain clear separation between concepts.

• Document thoroughly in notebooks. Keep outputs for demonstration, focus on one concept per notebook, and ensure they run top-to-bottom without errors.

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