Claude Code with the Anthropic SDK: Build Apps With Claude
Why the Anthropic SDK without CLAUDE.md generates apps that overspend and underperform
Claude Code is the agent you use to write code. The Anthropic SDK is what you use when the code you are writing needs to call Claude. The relationship is recursive in a useful way: Claude Code can help you build a Claude-powered feature in your own product, and the result is often the highest-value AI integration in the codebase.
The catch is that Claude (writing your application code) does not automatically know how to use Claude (the model your application calls) efficiently. Without explicit constraints, Claude Code generates SDK integrations that work but bleed money or quality on every request. The most common patterns: choosing Opus for tasks Sonnet would handle equally well at one-fifth the cost, omitting prompt caching on the system prompt so identical context is re-billed on every turn, streaming without backpressure handling so client disconnects pile up unfinished streams in memory, defining tools without the strict JSON Schema that prevents Claude from inventing fields, dropping the stop_reason so retries on max_tokens go undetected, and skipping the Batch API for offline workloads where 50% cost reduction is available.
This guide covers the CLAUDE.md configuration that locks Claude Code into the Anthropic SDK's actual cost and quality model: per-task model selection, prompt caching on stable context, streaming with cancellation, tool use with strict schemas, message batches for non-realtime work, and the model migration patterns for Opus 4.7 and Sonnet 4.6. For the broader AI integration context, Claude Code with LangChain covers the orchestration framework that wraps direct SDK calls, and Claude Code with the OpenAI SDK shows the comparable pattern for the other major model provider.
The Anthropic SDK CLAUDE.md template
The CLAUDE.md at your project root is read at the start of every Claude Code session. For an Anthropic SDK integration it needs to declare: the SDK version, the model selection rules, the prompt caching pattern, the streaming and tool use conventions, the batch API usage, and the hard rules that block the cost and quality mistakes Claude makes most often.
# Anthropic SDK rules
## Stack
- @anthropic-ai/sdk ^0.39.x (TypeScript) or anthropic ^0.40.x (Python)
- ANTHROPIC_API_KEY in .env.local (NEVER hardcode)
- Default model: claude-sonnet-4-6 unless task requires Opus
- Streaming: use SDK helpers, not raw event handling
- TypeScript 5.x strict, Python 3.11+ with type hints
## Project structure
- src/lib/anthropic.ts , SDK client singleton with API key validation
- src/lib/prompts/ , versioned prompt templates (.ts files exporting strings)
- src/lib/tools/ , tool definitions with JSON Schema
- src/lib/streaming.ts , SSE wrapper for client streams
- src/app/api/chat/ , Next.js chat endpoint with caching
## Model selection (COST AWARE)
- claude-opus-4-7: reasoning-heavy, multi-step planning, sensitive content review
- claude-sonnet-4-6: general agentic, code generation, summarisation (DEFAULT)
- claude-haiku-4: classification, simple extraction, embeddings replacement
- Default to Sonnet, escalate to Opus only when an eval shows Sonnet underperforms
- NEVER hardcode a model name in business logic, route through src/lib/models.ts
## Prompt caching (MANDATORY for stable context)
- ALWAYS cache the system prompt: { type: 'text', text: '...', cache_control: { type: 'ephemeral' } }
- ALWAYS cache tool definitions when calling more than once per session
- ALWAYS cache documents and reference material that repeat across turns
- Cache breakpoints: max 4 per request, place at stable/dynamic boundary
- A cache hit costs 10% of normal input tokens, miss costs 125%
- ALWAYS log cache_read_input_tokens vs cache_creation_input_tokens to verify hits
## Streaming
- Use client.messages.stream() helper, NOT raw client.messages.create({ stream: true })
- ALWAYS handle 'message_stop' to know when to close downstream connections
- ALWAYS handle 'message_delta' for usage updates (tokens, stop_reason)
- For client streaming: pipe SSE through Web Streams API with cancellation
- AbortController.signal on the request, AbortController.abort() on client disconnect
## Tool use (STRICT SCHEMAS)
- Every tool MUST have a JSON Schema with: name, description, input_schema
- input_schema MUST be: { type: 'object', properties: {...}, required: [...] }
- ALWAYS include 'required' (use [] for tools with optional-only inputs)
- Tool names: snake_case, descriptive, under 64 characters
- description: imperative, what the tool DOES (not what it RETURNS)
- ALWAYS handle stop_reason === 'tool_use' loop until stop_reason === 'end_turn'
## Hard rules
- NEVER hardcode ANTHROPIC_API_KEY
- NEVER call Opus for tasks Sonnet handles equally well (it is 5x the cost)
- NEVER skip prompt caching on stable context (every cache miss is 12.5x the hit cost)
- NEVER stream without cancellation handling (memory leak on client disconnect)
- NEVER define a tool without input_schema.required (Claude will invent fields)
- NEVER use the legacy /v1/complete endpoint, use /v1/messages
- ALWAYS check stop_reason, retry on 'max_tokens' if completion was needed
- ALWAYS use the Batch API for non-realtime work (50% cost reduction)
Three rules here prevent the majority of cost and quality issues Claude generates without them.
The prompt caching rule is the single most impactful cost optimisation available with the Anthropic SDK. Cache reads are billed at 10% of the standard input rate. Cache misses (the initial write) cost 125% of standard. The crossover is one cache hit. For a system prompt that fires on every message in a conversation, prompt caching delivers a 10x cost reduction on the cached portion within the first follow-up message. Claude omits caching by default because the cache_control parameter is not required by the SDK type definition.
The model selection rule prevents the most common cost mistake. Claude Code naturally reaches for the strongest model when generating example code (Opus is more impressive in a demo). For most production tasks (summarisation, classification, structured extraction, chat) Sonnet performs at or above Opus quality at one-fifth the cost. The CLAUDE.md rule forces routing through a central file that documents which model handles which task.
The tool schema rule prevents the most common quality bug. Without input_schema.required declared, Claude (the model) confabulates field names when calling tools. The model might call lookup_user({ userId: 'abc' }) when the function expected { id: 'abc' }. The CLAUDE.md rule forces every tool to declare its required fields, which the API enforces at validation time.
Install and client setup
Install the SDK:
npm i @anthropic-ai/sdk
Set the API key in .env.local:
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
Create the singleton client:
// src/lib/anthropic.ts
import Anthropic from '@anthropic-ai/sdk';
if (!process.env.ANTHROPIC_API_KEY) {
throw new Error('ANTHROPIC_API_KEY is not defined');
}
export const anthropic = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY,
// Optional: bump these for production traffic
maxRetries: 3,
timeout: 60_000,
});
The startup check surfaces missing credentials immediately. The retry and timeout settings handle transient 429s and slow first-token latency without manual code on every call site. Claude omits both by default; the CLAUDE.md singleton example with them present makes Claude reproduce them.
Add a singleton pattern to CLAUDE.md:
## SDK singleton
- src/lib/anthropic.ts exports a configured Anthropic client
- Validate ANTHROPIC_API_KEY at startup, NOT at first call
- maxRetries: 3, timeout: 60_000 in production
- NEVER instantiate new Anthropic() inline in route handlers
- For Vercel Edge: use the same SDK, set runtime: 'edge' on the route
Model selection and routing
The model registry pattern centralises model selection in one file, so the rest of the codebase references task names instead of model IDs:
// src/lib/models.ts
export const MODELS = {
// Reasoning-heavy tasks: long-form analysis, sensitive content review, multi-step planning
reasoning: 'claude-opus-4-7',
// General agentic and code generation
agent: 'claude-sonnet-4-6',
// Chat: user-facing conversation
chat: 'claude-sonnet-4-6',
// Summarisation: long documents, transcripts, code reviews
summarisation: 'claude-sonnet-4-6',
// Classification: yes/no, category selection, intent detection
classification: 'claude-haiku-4',
// Extraction: pulling structured data from unstructured text
extraction: 'claude-haiku-4',
} as const;
export type ModelTask = keyof typeof MODELS;
Usage:
import { anthropic } from '@/lib/anthropic';
import { MODELS } from '@/lib/models';
const response = await anthropic.messages.create({
model: MODELS.summarisation,
max_tokens: 1024,
messages: [{ role: 'user', content: 'Summarise this transcript...' }],
});
Migrating models becomes a one-line change in models.ts. Pricing changes become a one-line change. Eval results that surface a new winner become a one-line change. Without this indirection, every prompt scattered across the codebase becomes its own migration.
Rough cost comparison as of mid-2026 (per million tokens, USD):
| Model | Input | Output | Best for |
|---|---|---|---|
| Claude Opus 4.7 | $15 | $75 | Reasoning, planning, high-stakes content |
| Claude Sonnet 4.6 | $3 | $15 | General agentic, code, chat (DEFAULT) |
| Claude Haiku 4 | $0.80 | $4 | Classification, extraction, embeddings replacement |
The 5x cost gap between Opus and Sonnet is what makes lazy model selection so expensive. For a chat application doing 100,000 conversations a month at 10K tokens each, the difference between routing everything to Opus versus routing everything to Sonnet is roughly $5,500/month input + $25,000/month output. Sonnet pays for the entire team's eval infrastructure before the month ends.
Add a model routing section to CLAUDE.md:
## Model routing
- One file: src/lib/models.ts exports a MODELS const with task names
- Every API call references MODELS.<task>, never a hardcoded model string
- Default new tasks to MODELS.agent (Sonnet)
- Promote to MODELS.reasoning (Opus) only after eval shows Sonnet fails
- Demote to MODELS.classification (Haiku) for high-volume simple tasks
- NEVER mix models in a single request flow without a clear reason
Get Claudify. The CLAUDE.md template Anthropic SDK developers use to cut their model spend in half.
Prompt caching for stable context
Prompt caching is the highest-impact cost optimisation in the Anthropic SDK. Any portion of the prompt marked with cache_control: { type: 'ephemeral' } is stored on Anthropic's servers and reused on follow-up requests. The cache has a 5-minute TTL that resets on each hit, so a moderately active conversation keeps it warm indefinitely.
Without caching:
// EVERY request bills the full 5000-token system prompt at $3/1M
const response = await anthropic.messages.create({
model: MODELS.chat,
max_tokens: 1024,
system: 'You are Claudify support... (5000 tokens of context)',
messages: history,
});
With caching:
const SYSTEM_PROMPT = 'You are Claudify support... (5000 tokens of context)';
const response = await anthropic.messages.create({
model: MODELS.chat,
max_tokens: 1024,
system: [
{
type: 'text',
text: SYSTEM_PROMPT,
cache_control: { type: 'ephemeral' },
},
],
messages: history,
});
// usage.cache_creation_input_tokens: 5000 (first call, 125% cost)
// usage.cache_read_input_tokens: 5000 (subsequent calls, 10% cost)
For tool-using agents, cache the tool definitions too:
const response = await anthropic.messages.create({
model: MODELS.agent,
max_tokens: 1024,
system: [
{ type: 'text', text: SYSTEM_PROMPT, cache_control: { type: 'ephemeral' } },
],
tools: [
{ name: 'lookup_user', description: '...', input_schema: { ... } },
{ name: 'create_ticket', description: '...', input_schema: { ... } },
{
name: 'search_docs',
description: '...',
input_schema: { ... },
cache_control: { type: 'ephemeral' }, // cache breakpoint AFTER all tools
},
],
messages: history,
});
The cache breakpoint after the last tool definition causes all preceding content (system prompt, all tools) to be cached as a single block. Up to four cache_control markers are allowed per request, which lets you have multiple cached blocks (e.g. system + docs + tools, each cached independently).
For RAG-style use cases where you inject retrieved documents:
const response = await anthropic.messages.create({
model: MODELS.chat,
max_tokens: 1024,
system: [
{ type: 'text', text: SYSTEM_PROMPT, cache_control: { type: 'ephemeral' } },
],
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: retrievedDocs, // 20K tokens of context
cache_control: { type: 'ephemeral' }, // cache the docs block
},
{
type: 'text',
text: userQuestion, // the dynamic part, NOT cached
},
],
},
],
});
The user question changes every turn but the retrieved docs (for that session) stay stable. Caching the docs block delivers a 90% cost reduction on the bulk of the input.
Add a caching section to CLAUDE.md:
## Prompt caching
- Mark stable content with cache_control: { type: 'ephemeral' }
- Cacheable: system prompt, tool definitions, documents, reference material
- Max 4 cache breakpoints per request
- Place breakpoints at stable/dynamic boundaries (after the last cacheable block)
- TTL is 5 minutes, resets on each hit, so warm caches stay warm
- ALWAYS log usage.cache_read_input_tokens to verify cache hits
- Cache miss = 125% input cost, cache hit = 10% input cost (12.5x difference)
- For evals: turn caching OFF in eval runs to measure cold-start cost
Streaming with cancellation
Streaming is essential for any user-facing chat. The SDK provides client.messages.stream() which exposes an async iterator over events. The most important events are text (incremental text), tool_use (model called a tool), and message_stop (turn ended).
A minimal streaming endpoint in Next.js:
// src/app/api/chat/route.ts
import { NextRequest } from 'next/server';
import { anthropic } from '@/lib/anthropic';
import { MODELS } from '@/lib/models';
export const runtime = 'edge';
export async function POST(req: NextRequest) {
const { messages, system } = await req.json();
const stream = anthropic.messages.stream({
model: MODELS.chat,
max_tokens: 4096,
system: [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }],
messages,
});
const encoder = new TextEncoder();
const readable = new ReadableStream({
async start(controller) {
try {
for await (const event of stream) {
if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
const sse = `data: ${JSON.stringify({ text: event.delta.text })}\n\n`;
controller.enqueue(encoder.encode(sse));
}
if (event.type === 'message_stop') {
controller.enqueue(encoder.encode('data: [DONE]\n\n'));
controller.close();
}
}
} catch (error) {
const errSSE = `data: ${JSON.stringify({ error: (error as Error).message })}\n\n`;
controller.enqueue(encoder.encode(errSSE));
controller.close();
}
},
cancel() {
// Client disconnected: abort the upstream stream
stream.controller.abort();
},
});
return new Response(readable, {
headers: {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache, no-transform',
'Connection': 'keep-alive',
},
});
}
The cancel() handler on the ReadableStream is what prevents memory leaks. When a client closes the SSE connection (browser tab closed, navigation, network drop), the cancel() method fires and stream.controller.abort() tells the Anthropic SDK to stop reading from the upstream connection. Without this, the upstream connection stays open until the full response generates, consuming server memory and API tokens for output the client will never receive.
Add a streaming section to CLAUDE.md:
## Streaming
- Use client.messages.stream() helper, NOT manual SSE parsing
- For Next.js: pipe through Web Streams API ReadableStream
- ALWAYS implement cancel() to abort the upstream on client disconnect
- ALWAYS handle 'message_stop' to close the downstream connection
- For tool use: also handle 'content_block_start' with type 'tool_use'
- For usage tracking: handle 'message_delta' which carries the final usage
- runtime: 'edge' is fine for streaming; Node runtime also works
Tool use with strict schemas
Tool use turns Claude into an agent that can call functions in your codebase. The model decides when to call a tool based on the conversation context, your application executes the tool, and the result feeds back into the conversation.
Defining a tool:
// src/lib/tools/lookup-user.ts
import { z } from 'zod';
export const lookupUserToolDefinition = {
name: 'lookup_user',
description: 'Look up a user by their email address. Returns the user account record including subscription status and creation date.',
input_schema: {
type: 'object' as const,
properties: {
email: {
type: 'string',
format: 'email',
description: 'The email address of the user to look up',
},
},
required: ['email'],
},
};
export const lookupUserInputSchema = z.object({
email: z.string().email(),
});
export async function executeLookupUser(input: unknown) {
const { email } = lookupUserInputSchema.parse(input);
const user = await db.users.findUnique({ where: { email } });
if (!user) {
return { found: false };
}
return {
found: true,
id: user.id,
email: user.email,
subscriptionStatus: user.subscriptionStatus,
createdAt: user.createdAt.toISOString(),
};
}
Running the agent loop:
import { anthropic } from '@/lib/anthropic';
import { MODELS } from '@/lib/models';
import { lookupUserToolDefinition, executeLookupUser } from './tools/lookup-user';
async function runAgent(userMessage: string) {
const tools = [lookupUserToolDefinition];
const messages: Anthropic.MessageParam[] = [
{ role: 'user', content: userMessage },
];
while (true) {
const response = await anthropic.messages.create({
model: MODELS.agent,
max_tokens: 4096,
system: 'You are a helpful support agent. Use tools to look up users when needed.',
tools,
messages,
});
messages.push({ role: 'assistant', content: response.content });
if (response.stop_reason === 'end_turn') {
// Final assistant response
return response.content
.filter((b): b is Anthropic.TextBlock => b.type === 'text')
.map((b) => b.text)
.join('\n');
}
if (response.stop_reason === 'tool_use') {
// Execute each tool call and feed results back
const toolResults: Anthropic.ToolResultBlockParam[] = [];
for (const block of response.content) {
if (block.type !== 'tool_use') continue;
let result: unknown;
try {
if (block.name === 'lookup_user') {
result = await executeLookupUser(block.input);
} else {
result = { error: `Unknown tool: ${block.name}` };
}
} catch (error) {
result = { error: (error as Error).message };
}
toolResults.push({
type: 'tool_result',
tool_use_id: block.id,
content: JSON.stringify(result),
});
}
messages.push({ role: 'user', content: toolResults });
continue;
}
if (response.stop_reason === 'max_tokens') {
throw new Error('Agent exceeded max_tokens, response truncated');
}
break;
}
}
Two patterns worth highlighting. First, Zod validation of block.input before executing. The model usually generates valid JSON matching the schema, but a strict runtime check prevents the rare case where it does not. Second, explicit handling of stop_reason === 'max_tokens'. If the agent runs out of tokens mid-thought, the response is truncated and any tool calls are incomplete. Detecting this lets you retry with a larger max_tokens or signal the failure cleanly.
Add a tool use section to CLAUDE.md:
## Tool use
- Every tool: name (snake_case), description (imperative), input_schema (JSON Schema)
- input_schema MUST include 'required' field, even if empty array
- Zod schema in parallel for runtime validation of model-generated input
- Agent loop: check stop_reason after each response, exit on 'end_turn'
- Tool results returned as { type: 'tool_result', tool_use_id, content: JSON.stringify(result) }
- ALWAYS handle stop_reason === 'max_tokens', it means response is incomplete
- Cap iterations (e.g. 10) to prevent runaway loops, log if cap is hit
For the broader agent orchestration pattern, Claude Code with LangChain shows how to layer this loop inside a graph-based execution engine.
The Batch API for cost reduction
The Batch API processes message requests asynchronously at 50% of standard cost. The trade-off is a 24-hour SLA on completion (usually much faster, but no realtime guarantee). For analytics workloads, periodic reports, bulk document processing, and evals, the Batch API delivers immediate cost savings with zero quality compromise.
Creating a batch:
import { anthropic } from '@/lib/anthropic';
import { MODELS } from '@/lib/models';
async function classifyDocumentsBatch(documents: Array<{ id: string; text: string }>) {
const batch = await anthropic.messages.batches.create({
requests: documents.map((doc) => ({
custom_id: doc.id,
params: {
model: MODELS.classification,
max_tokens: 256,
messages: [
{
role: 'user',
content: `Classify this document into one of: contract, invoice, receipt, other.\n\n${doc.text}\n\nRespond with only the category.`,
},
],
},
})),
});
return batch.id;
}
async function retrieveBatchResults(batchId: string) {
let batch = await anthropic.messages.batches.retrieve(batchId);
while (batch.processing_status !== 'ended') {
await new Promise((resolve) => setTimeout(resolve, 30_000));
batch = await anthropic.messages.batches.retrieve(batchId);
}
const resultsStream = await anthropic.messages.batches.results(batchId);
const results: Array<{ custom_id: string; result: string }> = [];
for await (const line of resultsStream) {
if (line.result.type === 'succeeded') {
const message = line.result.message;
const text = message.content
.filter((b): b is Anthropic.TextBlock => b.type === 'text')
.map((b) => b.text)
.join('');
results.push({ custom_id: line.custom_id, result: text });
}
}
return results;
}
Add a batch section to CLAUDE.md:
## Batch API
- Use for: nightly analytics, bulk classification, eval runs, periodic reports
- 50% cost reduction vs realtime, 24-hour SLA (usually <1 hour in practice)
- Up to 10,000 requests per batch, 100MB total payload
- custom_id per request: use your application's stable identifier
- Poll for processing_status === 'ended', then stream results
- ALWAYS use Batch for offline workloads, NEVER for interactive ones
Common Claude Code mistakes with the Anthropic SDK
Six patterns Claude generates incorrectly without CLAUDE.md constraints, with the correct replacement for each.
1. Opus for everything
Claude generates: model: 'claude-opus-4-7' for simple summarisation.
Correct pattern: model: MODELS.summarisation which resolves to Sonnet. Opus is reserved for reasoning-heavy tasks.
2. No prompt caching
Claude generates: system: 'You are...' as a plain string.
Correct pattern: system: [{ type: 'text', text: '...', cache_control: { type: 'ephemeral' } }] for any system prompt over a few hundred tokens.
3. Streaming without cancellation
Claude generates: for await (const event of stream) { ... } with no cancel() handler.
Correct pattern: cancel() { stream.controller.abort(); } on the downstream ReadableStream.
4. Tool definitions without required
Claude generates: input_schema: { type: 'object', properties: { ... } } with no required.
Correct pattern: input_schema: { type: 'object', properties: { ... }, required: ['fieldName'] }. Without required, the model invents fields.
5. Ignoring stop_reason
Claude generates: agent loop that exits after the first response regardless of stop_reason.
Correct pattern: while loop that continues on stop_reason === 'tool_use' and only exits on 'end_turn', with a separate branch for 'max_tokens'.
6. Realtime for offline work
Claude generates: await Promise.all(documents.map((doc) => anthropic.messages.create({ ... }))) for batch classification.
Correct pattern: anthropic.messages.batches.create({ requests: [...] }). 50% cost savings, no quality difference.
Add a common mistakes section to CLAUDE.md with these six pairs. The before/after format helps Claude match what it would otherwise generate to the corrected form.
Permission hooks for Anthropic SDK scripts
An Anthropic SDK integration accumulates scripts: eval runs, batch dispatch, prompt diffs, cost reports. Some are cheap. Some can cost thousands of dollars per run. Permission hooks gate the expensive ones.
In .claude/settings.local.json:
{
"permissions": {
"allow": [
"Bash(node scripts/run-eval.js --sample-size=10*)",
"Bash(node scripts/diff-prompts.js*)",
"Bash(node scripts/cost-report.js*)",
"Bash(node scripts/check-batch-status.js*)"
],
"deny": [
"Bash(node scripts/run-eval.js --sample-size=*1000*)",
"Bash(node scripts/dispatch-batch.js*)",
"Bash(node scripts/migrate-model.js*)"
]
}
}
Small eval runs (10 samples) and cost reporting are safe. Full eval runs (1000+ samples) and batch dispatches require explicit confirmation because they can cost hundreds of dollars. Model migration scripts (which rewrite production traffic to a new model) require manual approval.
Building applications that use Claude efficiently
The Anthropic SDK CLAUDE.md in this guide produces integrations where model selection routes through a central file, prompt caching is applied to every stable context block, streaming handles client cancellation, tools have strict JSON schemas with required fields declared, agent loops respect stop_reason, and offline workloads use the Batch API for 50% cost reduction.
The underlying principle is recursive in a useful way. Claude Code writing applications that use the Anthropic SDK without explicit constraints produces code that bleeds money on every request: Opus where Sonnet would do, full input cost where caching would cut 90%, realtime where batches would cut 50%. The CLAUDE.md template removes each cost leak by making the efficient pattern the only pattern Claude can generate.
For the broader AI integration picture, the Anthropic SDK works alongside Claude Code with LangChain for graph-based agent orchestration, and Claudify includes an Anthropic-SDK-specific CLAUDE.md template with the model routing pattern, prompt caching defaults, streaming cancellation, tool use schema rules, batch API usage, and all six common-mistake rules pre-configured.
Get Claudify. The CLAUDE.md template developers use to ship Claude-powered features that scale without bankrupting the budget.
More like this
Ready to upgrade your Claude Code setup?
Get Claudify
