anth-known-pitfalls

name	anth-known-pitfalls
description	Identify and avoid common Claude API anti-patterns and integration mistakes. Use when reviewing code, onboarding developers, or debugging subtle issues with Anthropic integrations. Trigger with phrases like "anthropic pitfalls", "claude anti-patterns", "claude mistakes", "anthropic common issues", "claude gotchas".
allowed-tools	Read, Write, Edit, Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","ai","anthropic"]
compatible-with	claude-code

Anthropic Known Pitfalls

Pitfall 1: Wrong Import / Class Name

# WRONG — common mistake from OpenAI muscle memory
from anthropic import AnthropicClient  # Does not exist

# CORRECT
import anthropic
client = anthropic.Anthropic()

// WRONG
import { Anthropic } from '@anthropic-ai/sdk';

// CORRECT
import Anthropic from '@anthropic-ai/sdk';  // Default export

Pitfall 2: Forgetting max_tokens (Required)

# WRONG — max_tokens is REQUIRED, unlike OpenAI
msg = client.messages.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Hello"}]
)  # Error: max_tokens is required

# CORRECT
msg = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,  # Always specify
    messages=[{"role": "user", "content": "Hello"}]
)

Pitfall 3: System Prompt in Messages Array

# WRONG — putting system message in messages array (OpenAI pattern)
messages = [
    {"role": "system", "content": "You are helpful."},  # Will cause error
    {"role": "user", : }
]


msg = client.messages.create(
    model=,
    max_tokens=,
    system=,  
    messages=[{: , : }]
)