Cheat sheet

while (true) {
  const response = await claude.messages.create({...});
  if (response.stop_reason === 'end_turn') break;
  // stop_reason === 'tool_use' — execute tools
  const toolResults = await executeTools(response.content);
  messages.push({ role: 'assistant', content: response.content });
  messages.push({ role: 'user', content: toolResults });
}

// Transient — retry appropriate
{ isError: true, errorCategory: 'transient', isRetryable: true, message: 'DB timeout' }

// Business rule — do not retry
{ isError: true, errorCategory: 'business', isRetryable: false, message: 'Refund exceeds $500 limit' }

// Valid empty result — NOT an error
{ isError: false, content: [], message: 'No records found' }

# .claude/rules/testing.md
---
paths: ["**/*.test.tsx", "**/*.spec.ts"]
---
# Testing conventions
- Use React Testing Library
- Prefer userEvent over fireEvent
- Always test accessibility

# .claude/skills/analyze-codebase.md
---
context: fork
allowed-tools: Read, Grep, Glob
argument-hint: "module-name to analyze (e.g., auth, payments)"
---
Analyze the architecture of the specified module...

// .mcp.json (committed to version control)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

// Guarantee a specific tool runs first
const response = await claude.messages.create({
  tools: [extractMetadata, enrichContent],
  tool_choice: { type: 'tool', name: 'extract_metadata' },
  messages,
});

// Then allow free tool selection for enrichment
const enriched = await claude.messages.create({
  tools: [enrichContent, validateOutput],
  tool_choice: { type: 'any' },
  messages: [...messages, response],
});

// Injected at the top of every prompt in the session
const caseFacts = {
  customerId: 'C-98234',
  disputedAmount: 43.27,  // exact — never summarize
  orderIds: ['ORD-1122', 'ORD-1133'],
  confirmedIssue: 'double charge on 2024-11-03',
};

// Structured error context returned by a subagent
return {
  isError: true,
  errorCategory: 'transient',
  isRetryable: true,
  failureType: 'timeout',
  attemptedQuery: 'AI adoption in healthcare 2024',
  partialResults: ['article1.pdf summary'],
  alternativeApproach: 'Try splitting query into two narrower searches',
};

// Before appending tool result to context, extract only needed fields
const rawOrder = await getOrder(orderId); // 40 fields
const relevantOrder = {
  orderId: rawOrder.orderId,
  status: rawOrder.status,
  amount: rawOrder.amount,
  customerId: rawOrder.customerId,
  lastUpdated: rawOrder.lastUpdated,
  // 35 fields omitted — not needed for this agent's task
};
messages.push({ role: 'user', content: JSON.stringify(relevantOrder) });

# CI step: structured review output
claude -p "Review for security issues" \
  --output-format json \
  --json-schema .claude/review-schema.json \
  > findings.json

# findings.json shape (defined by review-schema.json):
# [{ "file": "src/auth.ts", "line": 42, "severity": "high", "message": "..." }]

// Schema
{
  "category": {
    "type": "string",
    "enum": ["medical", "dental", "pharmacy", "vision", "other"]
  },
  "category_detail": {
    "type": ["string", "null"],
    "description": "Required when category is 'other'. Null otherwise."
  }
}

// Valid outputs:
{ "category": "dental", "category_detail": null }
{ "category": "other", "category_detail": "holistic wellness treatment" }

// Structured finding with pattern annotation
{
  "file": "src/renderer.js",
  "line": 88,
  "severity": "medium",
  "message": "Dynamic code execution via eval()",
  "detected_pattern": "eval_in_userland",  // ← enables false positive analysis
  "dismissed": false  // set to true when developer dismisses
}

// Extraction output per field
{
  "invoice_number": { "value": "INV-2024-0892", "confidence": 0.97 },
  "invoice_date":   { "value": "2024-11-03",    "confidence": 0.91 },
  "line_items":     { "value": [...],             "confidence": 0.61 }  // → human review
}

// Routing logic (threshold calibrated from labeled validation set)
const REVIEW_THRESHOLD = 0.87; // empirically: accuracy ≥ 95% above this
const needsReview = fields.filter(f => f.confidence < REVIEW_THRESHOLD);