Claude Cookbooks

ID breaks) | 15–20 mins | 65% | | Standardized Cookbook Workflow | 5–10 mins | 100% | Zero (alias enforcement) | 2–4 mins | 98% |

Key Findings:

• Enforcing non-dated model aliases eliminates endpoint rotation failures.
• uv + ruff + pre-commit hooks reduce CI feedback loops by ~80%.
• Top-to-bottom notebook validation with relaxed E402/F811/N803/N806 rules maintains pedagogical clarity while ensuring execution stability.
• Centralized registry.yaml and authors.yaml streamline contribution tracking and discoverability.

Core Solution

The Claude Cookbooks architecture standardizes environment provisioning, code quality enforcement, model routing, and contribution workflows through a unified uv-managed Python ecosystem.

Environment & Dependency Management

# Install dependencies
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

# Set up API key
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

Development & Quality Commands

make format        # Format code with ruff
make lint          # Run linting
make check         # Run format-check + lint
make fix           # Auto-fix issues + format
make test          # Run pytest

Or directly with uv:

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

Code Style & Git Workflow

• Line length: 100 characters
• Quotes: Double quotes
• Formatter: Ruff

Notebooks have relaxed rules for mid-file imports (E402), redefinitions (F811), and variable naming (N803, N806).

Branch naming: <username>/<feature-description>

Commit format (conventional commits):

feat(scope): add new feature
fix(scope): fix bug
docs(scope): update documentation
style: lint/format

Model & API Routing Rules

1. API Keys: Never commit .env files. Use dotenv.load_dotenv() then access keys via os.environ or os.getenv()
2. Dependencies: Use uv add <package> or uv add --dev <package>. Never edit pyproject.toml directly.
3. Models: Use current Claude models. Check docs.anthropic.com for latest versions.
   • Sonnet: claude-sonnet-4-6
   • Haiku: claude-haiku-4-5
   • Opus: claude-opus-4-6
   • Never use dated model IDs (e.g., claude-sonnet-4-6-20250514). Always use the non-dated alias.
   • Bedrock model IDs follow a different format. Use the base Bedrock model ID from the docs:
     • Opus 4.6: anthropic.claude-opus-4-6-v1
     • Sonnet 4.5: anthropic.claude-sonnet-4-5-20250929-v1:0
     • Haiku 4.5: anthropic.claude-haiku-4-5-20251001-v1:0
     • Prepend global. for global endpoints (recommended): global.anthropic.claude-opus-4-6-v1
     • Note: Bedrock models before Opus 4.6 require dated IDs in their Bedrock model ID.
4. Notebooks:
   • Keep outputs in notebooks (intentional for demonstration)
   • One concept per notebook
   • Test that notebooks run top-to-bottom without errors
5. Quality checks: Run make check before committing. Pre-commit hooks validate formatting and notebook structure.

Slash Commands (Claude Code & CI)

• /notebook-review - Review notebook quality
• /model-check - Validate Claude model references
• /link-review - Check links in changed files

Project Architecture

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

Contribution Workflow

1. Create notebook in the appropriate directory
2. Add entry to registry.yaml with title, description, path, authors, categories
3. Add author info to authors.yaml if new contributor
4. Run quality checks and submit PR

Pitfall Guide

1. Hardcoding API Credentials: Committing .env files or embedding keys directly in notebooks exposes secrets to version control. Always use dotenv.load_dotenv() and retrieve values via os.environ or os.getenv().
2. Manual pyproject.toml Edits: Directly modifying dependency lists breaks uv's lockfile resolution and causes environment drift. Always use uv add <package> or uv add --dev <package> to maintain reproducible builds.
3. Using Dated Model IDs: Relying on snapshot IDs (e.g., claude-sonnet-4-6-20250514) causes silent failures when Anthropic rotates endpoints. Always use non-dated aliases (claude-sonnet-4-6, claude-haiku-4-5, claude-opus-4-6).
4. Misrouting Bedrock Endpoints: Bedrock requires distinct ID formats and regional/global routing. Forgetting the global. prefix or using incorrect version suffixes (e.g., :0) results in ValidationException or routing failures. Pre-Opus 4.6 Bedrock models still require dated IDs in their Bedrock identifier.
5. Ignoring Top-to-Bottom Notebook Execution: Notebooks that rely on out-of-order cell execution or untracked state will fail in CI or when shared. Ensure every notebook runs cleanly from cell 1 to the last without manual intervention.
6. Bypassing Pre-commit & CI Validation: Skipping make check or disabling pre-commit hooks allows unformatted code, broken links, and invalid model references to merge. This increases review overhead and destabilizes the registry.

Deliverables

• 📘 Claude Cookbook Standardization Blueprint: Architecture guide covering uv environment provisioning, Ruff linting configuration, model alias routing strategies, Bedrock endpoint mapping, and CI/CD validation pipelines.
• ✅ Pre-Submission Validation Checklist: Step-by-step verification for API key safety, model alias compliance, top-to-bottom notebook execution, linting/formatting pass, registry metadata completeness, and author attribution.
• ⚙️ Configuration Templates: Ready-to-use .env.example structure, pyproject.toml (uv-managed dependency schema), registry.yaml entry format, and .pre-commit-config.yaml hook definitions for immediate project bootstrapping.