The Claude Developer Handbook

Tokenization
  → Count tokens, not words, when estimating context usage
  → Special tokens and whitespace consume budget unexpectedly

Attention + context window
  → Critical instructions: top of system prompt
  → Current task: end of user message
  → Middle of long contexts: systematically underweighted

Next-token prediction
  → Claude cannot verify facts — it predicts plausible text
  → Confident-sounding ≠ correct. Use tools or RAG for facts
  → "Think step by step" works because it forces slow generation

RLHF + Constitutional AI
  → Claude is trained to be helpful AND honest AND harmless
  → It will push back on requests that violate those principles
  → Sycophancy is a training artifact — combat it explicitly

Temperature / sampling
  → High temp (0.9): creative, varied, sometimes wrong
  → Low temp (0.1): deterministic, consistent, less creative
  → Most production tasks: 0.0–0.3. Creative tasks: 0.7–1.0

# Current models (June 2026)
OPUS   = "claude-opus-4-8"       # $5/$25 per MTok — complex reasoning, agentic
SONNET = "claude-sonnet-4-6"     # $3/$15 per MTok — production default
HAIKU  = "claude-haiku-4-5-20251001" # $1/$5 per MTok  — fast, high-volume

# Query available models programmatically
import anthropic
client = anthropic.Anthropic()
models = client.models.list()
for m in models.data:
    print(m.id, m.created_at)

# Always use the models list in production — IDs change on deprecation

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,    # required — no default, omitting returns 400
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "Explain prompt caching."}
    ]
)
print(response.content[0].text)

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": prompt}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

const stream = await client.messages.stream({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: prompt }]
})
for await (const event of stream) {
  if (event.type === "content_block_delta")
    process.stdout.write(event.delta.text)
}

tools = [{
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
        "type": "object",
        "properties": {
            "location": {"type": "string",
                          "description": "City and state"}
        },
        "required": ["location"]
    }
}]

response = client.messages.create(
    model="claude-sonnet-4-6", max_tokens=1024, tools=tools,
    messages=[{"role": "user", "content": "Weather in Istanbul?"}]
)

if response.stop_reason == "tool_use":
    tool_use = next(b for b in response.content if b.type == "tool_use")
    result = execute_tool(tool_use.name, tool_use.input)
    # Continue conversation with {"role":"user", "content":[{
    #   "type":"tool_result", "tool_use_id": tool_use.id, "content": result}]}

response = client.messages.create(
    model="claude-sonnet-4-6", max_tokens=1024,
    system="""Return ONLY valid JSON matching this exact schema.
No preamble. No markdown fences. No explanation.
Schema: {"sentiment": "positive"|"negative"|"neutral",
         "confidence": 0.0-1.0,
         "key_topics": ["string"]}""",
    messages=[{"role": "user", "content": text_to_analyze}]
)
import json
result = json.loads(response.content[0].text)

# ❌ WRONG — breakpoint after user message, system prompt not cached
messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": question,
     "cache_control": {"type": "ephemeral"}}  # ← wrong position
]

# ✅ RIGHT — breakpoint after stable system prompt
messages = [
    {"role": "system", "content": SYSTEM_PROMPT,
     "cache_control": {"type": "ephemeral", "ttl": "1h"}},  # ← correct
    {"role": "user", "content": question}
]

# Adaptive: model decides when+how much to think
# Preserves cache breakpoints (switching modes breaks them)
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=8192,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": complex_task}]
)
# steering if thinking too often:
# add to system prompt: "Only use thinking for genuinely complex steps"

# Create batch — up to 10,000 requests per batch
batch = client.messages.batches.create(
    requests=[
        {"custom_id": f"item-{i}",
         "params": {"model": "claude-sonnet-4-6",
                    "max_tokens": 512,
                    "messages": [{"role": "user",
                                   "content": item}]}}
        for i, item in enumerate(items)
    ]
)

# Poll until done (or use webhooks)
import time
while batch.processing_status != "ended":
    time.sleep(60)
    batch = client.messages.batches.retrieve(batch.id)

# Stream results
for result in client.messages.batches.results(batch.id):
    if result.result.type == "succeeded":
        print(result.custom_id, result.result.message.content[0].text)

import anthropic, time

def call_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}]
            )
        except anthropic.RateLimitError:
            time.sleep(2 ** attempt)  # exponential backoff
        except anthropic.APIStatusError as e:
            if e.status_code == 529:  # overloaded
                time.sleep(30)
            elif e.status_code >= 500:  # server error, retry
                time.sleep(5)
            else:
                raise  # 4xx = bad request, don't retry
    raise Exception("Max retries exceeded")

Classify the sentiment of each review. Reply with only: positive, negative, or neutral.

<examples>
<example>
Review: The API is fast and the docs are excellent.
Sentiment: positive
</example>

<example>
Review: Pricing is fine but onboarding took forever.
Sentiment: neutral
</example>

<example>
Review: Keeps timing out under load. Unusable.
Sentiment: negative
</example>
</examples>

Review: {user_review}

<role>
You are a senior code reviewer specializing in Python security.
</role>

<task>
Review the provided code for security vulnerabilities.
Report every issue you find, including low-severity ones.
For each finding: severity (critical/high/medium/low), location,
description, and recommended fix.
</task>

<output_format>
Return a JSON array. Each item:
{ "severity": string, "line": number, "issue": string, "fix": string }
No preamble. No markdown fences.
</output_format>

<code>
{code_to_review}
</code>

Analyze this dataset and find the top 3 anomalies.

Use <thinking> tags for your analysis process.
Use <answer> tags for your final response to the user.
The user only sees <answer>.

<thinking>
← Claude reasons here, checks edge cases, explores hypotheses
</thinking>

<answer>
← Clean, verified output goes here
</answer>

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=64000,  # start at 64k for xhigh/max effort
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},  # best for coding + agents
    messages=[{"role": "user", "content": task}]
)

# If seeing shallow reasoning: raise effort first, then prompt
# system: "This task involves multi-step reasoning. Think carefully."
# If thinking too often at xhigh with large system prompts:
# system: "Thinking adds latency. Only use when it meaningfully
#          improves quality — multi-step reasoning only."

# Opus 4.8 spawns fewer subagents by default — steerable:

Do not spawn a subagent for work you can complete directly
in a single response (e.g. refactoring a function you can already see).

Spawn multiple subagents in the same turn when fanning out
across items or reading multiple files simultaneously.

# To increase tool usage in knowledge work tasks:
# raise effort to high/xhigh before prompting around it
# "Use web_search whenever you need current information
#  rather than relying on your training data"

# Style: Draft for Publication

- Open with one concrete number or named entity. No "I've been thinking..."
- Sentences under 18 words where possible.
- No em-dashes unless rhythm requires.
- No "delve", "leverage", "robust", "unlock", "game-changing".
- If listing 3+ items: hyphen list, not numbered.
- End on a statement, not a question.
- If draft exceeds 280 chars and user didn't ask for a thread, say so first.

you are a wise and incredibly effective teacher. your goal is to make
sure the human deeply understands the session.

do this incrementally with each step instead of all at once at the end.
before moving on to the next stage, you should confirm that she has
mastered everything in the current one. this should be high level
(e.g. motivation) and low level (e.g. business logic, edge cases).

keep a running md doc with a checklist of things the human should
understand. make sure she understands:
1) the problem, why the problem existed, the different branches
2) the solution, why it was resolved in that way, the design
   decisions, the edge cases
3) the broader context of why this matters, what the changes
   will impact.

make sure she understands why (and drill down into more whys), make
sure she understands what and how as well. understanding the problem
well is imperative.

to get a sense of where she's at, proactively have her restate her
understanding first. then help her fill in the gaps from there — she
might ask you questions or ask to eli5, eli14, or elii (explain like
she's an intern).

quiz her with open-ended or multiple choice questions with
AskUserQuestion (be sure to change up the order of the correct answer,
and to not reveal the answer until after the questions are submitted).
show her code or have her use the debugger if necessary!

/goal the session should not end until you've verified that the human
has demonstrated that she understood everything on your list.

┌─────────────────────────────────────────┐
│  SYSTEM PROMPT                          │  ← highest attention
│  (role, instructions, CLAUDE.md)        │
├─────────────────────────────────────────┤
│  TOOL DEFINITIONS                       │  ← loaded once, schema cost
│  (each MCP server: 800–6,000 tokens)    │
├─────────────────────────────────────────┤
│  UPLOADED FILES / KNOWLEDGE             │
│  (PDFs, docs, code)                     │
├─────────────────────────────────────────┤
│  CONVERSATION HISTORY                   │  ← degrades as it grows
│  (user turns + assistant responses)     │
├─────────────────────────────────────────┤
│  TOOL RESULTS                           │  ← often re-fetchable
│  (API responses, search results)        │
├─────────────────────────────────────────┤
│  CURRENT USER MESSAGE                   │  ← highest attention
└─────────────────────────────────────────┘

# Beta header required: compaction-2025-03-20
response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=8192,
    system=system_prompt,
    messages=conversation_history,
    betas=["compaction-2025-03-20"],
    compaction_control={
        "enabled": True,
        "context_token_threshold": 100000,  # compact at 100k tokens
        "summary_prompt": SUMMARY_PROMPT
    }
)

# Check if compaction was applied:
if hasattr(response, "context_management"):
    print(response.context_management.applied_edits)
    # shows how many tool uses and tokens were cleared

SUMMARY_PROMPT = """
You have been working on the task described above but have not yet completed it.
Write a summary inside <summary></summary> tags that captures:
1. The overall goal and current progress
2. Key decisions made and why
3. What has been completed
4. What remains to be done (next immediate step first)
5. Any important constraints or discoveries

Do not call any tools while writing this summary; respond with text only.
"""

# Critical: tell it not to call tools during summarization
# Without this, model may call a tool instead of writing a summary
# causing compaction to return content: null

Your context window will be automatically compacted as it approaches
its limit, allowing you to continue working indefinitely from where
you left off. Therefore, do not stop tasks early due to token budget concerns.

As you approach your token budget limit, save your current progress
and state to memory before the context window refreshes.

Always be as persistent and autonomous as possible and complete tasks
fully, even if the end of your budget is approaching.
Never artificially stop any task early regardless of context remaining.

# Step 1: Extract — focused on one task
extraction = client.messages.create(
    model="claude-sonnet-4-6", max_tokens=2048,
    messages=[{"role": "user",
               "content": f"Extract all action items from: {transcript}"}]
)
action_items = extraction.content[0].text

# Step 2: Prioritize — receives only the extracted output
prioritized = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024,
    messages=[{"role": "user",
               "content": f"Prioritize by urgency and owner: {action_items}"}]
)

# Step 3: Draft — receives only the prioritized list
email_draft = client.messages.create(
    model="claude-sonnet-4-6", max_tokens=512,
    messages=[{"role": "user",
               "content": f"Draft a summary email: {prioritized.content[0].text}"}]
)

## Definition of Done

Every task is complete ONLY when ALL of the following pass:

1. pytest tests/ -x             # all tests green
2. mypy src/ --strict           # zero type errors
3. ruff check src/              # zero lint errors
4. make e2e                     # end-to-end flow passes

Do NOT declare a task complete until all four commands pass.
Do NOT skip verification because context is running low.
If you cannot complete verification, say so explicitly.

# Install globally
npm install -g @anthropic-ai/claude-code

# ── Interactive sessions ─────────────────────────────────────
claude                         # start REPL in current directory
claude "fix the tests"          # start with initial prompt
claude -c                      # continue last session
claude -r                      # resume (opens session picker)
claude --session-id ID         # resume specific session by ID
claude --bg "refactor auth"    # dispatch to background Agent View

# ── One-shot (non-interactive) ───────────────────────────────
claude -p "explain this file"            # print mode, no REPL
cat file.ts | claude -p "analyze"       # pipe stdin to Claude
git diff | claude -p "summarize changes" # pipe diff for review

# ── Model and effort ─────────────────────────────────────────
claude --model opus -p "hard task"        # specify model
claude --effort max -p "deep analysis"    # set effort level
export CLAUDE_CODE_EFFORT_LEVEL=high       # persist via env var

# ── Permissions ──────────────────────────────────────────────
claude --allowedTools "Read,Write,Bash(git *)"  # no prompts for these
claude --tools "Read,Grep"                    # restrict to ONLY these tools
claude --tools ""                              # no tools — pure text mode
claude --disallowedTools "Bash(git push *)"   # block specific commands
claude --permission-mode auto                  # mostly auto, prompt rarely

# ── Output and limits ────────────────────────────────────────
claude -p --output-format json "query"        # structured JSON output
claude -p --output-format stream-json "q"    # streaming JSON
claude -p --max-turns 5 "query"              # cap agent iterations
claude --max-budget-usd 5                    # hard spending cap

# ── CI/CD pattern ────────────────────────────────────────────
claude -p "run full review" \
  --output-format json \
  --max-turns 10 \
  --permission-mode bypassPermissions          # CI: no interactive prompts

# ── Advanced ─────────────────────────────────────────────────
claude --enable-auto-mode                      # fully autonomous (same as Shift+Tab)
claude --channels discord,telegram             # chat integration
claude --remote                                # enable WebSocket remote control
claude agents                                  # open Agent View (manage parallel sessions)

---
name: sprint-review
description: Review all changes since last sprint tag. Output:
  completed features, open bugs, tech debt introduced.
allowed-tools: Read, Bash, Grep, Glob
---

Run git log since the last sprint tag.
For each merged PR: summarize what changed in one sentence.
Group into: Features · Bug Fixes · Tech Debt.
Flag any changes that lack test coverage.
Output as markdown suitable for a standup update.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }  ← env var, not hardcoded
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

your-skill-name/          ← kebab-case, no spaces, no capitals
├── SKILL.md              ← required, exact name (case-sensitive)
├── scripts/              ← optional: Python, Bash executables
│   └── validate.py
├── references/           ← optional: docs loaded on demand
│   └── api-guide.md
└── assets/               ← optional: templates, fonts, icons

No README.md inside the skill folder
No XML angle brackets anywhere in frontmatter
Skills named with "claude" or "anthropic" prefix are reserved

---
name: figma-handoff          # kebab-case only
description: Analyzes Figma design files and generates developer
  handoff documentation. Use when user uploads .fig files,
  asks for "design specs", "component documentation", or
  "design-to-code handoff".   # WHAT + WHEN — both required
license: MIT
metadata:
  author: Your Company
  version: 1.0.0
---

# Bad descriptions (don't do these):
# description: Helps with projects.          ← too vague, never triggers
# description: Creates documentation.        ← no trigger phrases

import { expect } from 'vitest'
import { describeEval, toolCalls } from 'vitest-evals'
import { refundAgentHarness } from '../harness'

describeEval('refund agent', { harness: refundAgentHarness() }, (it) => {
  it('approves refundable invoice', async ({ run }) => {
    const result = await run('Refund invoice inv_123')

    expect(result.output.status).toBe('approved')
    expect(toolCalls(result.session).map(c => c.name))
      .toEqual(['lookupInvoice', 'createRefund']) // assert tool sequence
  })
})

def judge_response(user_input: str, agent_output: str, rubric: str) -> dict:
    response = client.messages.create(
        model="claude-opus-4-8",  # strong model as judge
        max_tokens=512,
        system="""Impartial evaluator. Return JSON only:
{"score": 1-5, "pass": true/false,
 "failure_type": null|"retrieval"|"reasoning"|"tool"|"hallucination"|"format",
 "reason": "one sentence"}""",
        messages=[{"role": "user", "content": f"""
<rubric>{rubric}</rubric>
<input>{user_input}</input>
<output>{agent_output}</output>
Evaluate."""}]
    )
    import json
    return json.loads(response.content[0].text)

# Batch API: 50% cheaper for eval runs
results = [judge_response(inp, out, RUBRIC) for inp, out in test_cases]
pass_rate = sum(1 for r in results if r["pass"]) / len(results)
from collections import Counter
failure_types = Counter(r["failure_type"] for r in results if not r["pass"])
print(f"Pass: {pass_rate:.0%} | Failures: {dict(failure_types)}")

## Rubric: Customer Support Agent

PASS (4-5) — ALL must be true:
  □ Directly addresses the specific question (not generic)
  □ Cites correct policy/data from tools actually called
  □ Does not promise beyond stated policy
  □ Under 150 words

MARGINAL (3) — correct answer but one of:
  □ Generic language instead of specific account data
  □ 150-250 words

FAIL (1-2) — ANY of:
  □ Wrong answer / wrong policy cited     → failure_type: reasoning
  □ Hallucinated account details          → failure_type: hallucination
  □ Required tool not called             → failure_type: tool
  □ Over 250 words                       → failure_type: format

1. Define success criteria first
   Write "correct" as a rubric, not prose.
   Name 5-10 cases that matter most. Name 3 that must never fail.

2. Write the eval suite — before the prompt
   Golden:      5-10 critical paths (gate for every release)
   Regression:  every bug already fixed (stays fixed)
   Edge cases:  unusual inputs that reveal brittleness
   Adversarial: injection, malformed input, empty/huge responses

3. Run against baseline — expect failure
   First run mostly fails. That is the point.
   You now have a precise picture of what needs fixing.

4. Improve the prompt — one change at a time
   Fix labeled failures. Re-run. Improved? Regressed anything?
   Never change two things at once — you cannot attribute the effect.

5. Gate on golden cases
   All golden cases must pass before promotion.
   Aggregate improved but golden case broke → reject.

6. Maintain as living documentation
   Every new production failure → new regression case.
   Case untriggered 3 months → candidate for deletion.

# 1. Morning briefing (schedule trigger, 7am weekdays)
Pull yesterday's metrics from the dashboard.
Summarize new GitHub issues opened since 5pm yesterday.
List any Slack messages in #alerts that need a response.
Post a digest to #standup. Be brief — bullet points only.

# 2. PR review (GitHub event trigger: pull_request.opened)
Review the diff in this PR.
Check for: SQL injection, auth bypass, hardcoded secrets,
  missing input validation, N+1 queries.
Post findings as inline comments. Severity: critical/major/minor.
Do not approve. Human review required before merge.

# 3. Inbox triage (schedule trigger, every hour 9am-6pm)
Scan Gmail for emails marked urgent or from VIP senders.
For each: draft a reply in my writing style.
Save drafts — do not send. I review before sending.

Remember the following about me for future conversations:
- I work in [field] and my main projects are [X, Y]
- I prefer direct prose, no bullet points, short replies
- Never use em-dashes or passive voice in drafts
- My timezone is [TZ] and I work [hours]

Inline forget: "forget what you remembered about [topic]"
Claude parses against your memory store and confirms removal.

## Preferences
- Bullet summaries over prose for status updates
- Always cite the source file for any claim

## Decisions
- 2026-04-18 — chose Postgres over Mongo (relational reporting)
- 2026-05-02 — API versioning: date-based, not semantic

## Known workarounds
- Export tool chokes on files >50MB; split first

## Recurring mistakes to avoid
- Do not auto-approve PRs touching the auth module

# Required beta headers (SDK sets automatically on managed agents calls):
# anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21

dream = client.beta.dreams.create(
    inputs=[
        {"type": "memory_store", "memory_store_id": store_id},
        {"type": "sessions",      "session_ids": recent_sessions},
    ],
    model="claude-opus-4-8",   # or claude-sonnet-4-6
    instructions="Focus on coding-style preferences; "
                 "ignore one-off debugging notes.",
)

# Input store stays READ-ONLY — output is a separate new store
output_store_id = next(
    o.memory_store_id for o in dream.outputs
    if o.type == "memory_store"
)
# Inspect before swapping — inspect(), then point agent at new ID

{
  "model": "claude-sonnet-4-6",

  "enabledPlugins": {
    "formatter@acme-tools":  true,
    "old-experiment@personal": false  // installed but unloaded
  },

  "permissions": {
    "deny": [
      "Read(.env)", "Read(.env.*)", "Read(**/*secret*)",
      "Bash(rm -rf:*)", "Bash(sudo:*)"
    ]
  },

  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "cat .claude/context-$(git branch --show-current).md 2>/dev/null || true"
      }]
    }]
  },

  "disableAllHooks": false,  // panic switch — flip when hooks misbehave

  "mcpServers": {
    "github":   { "command": "npx", "args": ["..."], "enabled": true  },
    "postgres": { "command": "npx", "args": ["..."], "enabled": false },
    "slack":    { "command": "npx", "args": ["..."], "enabled": false }
  },

  "cleanupPeriodDays": 180   // default 30 — 6x more signal for Dreaming
}