Key Points

• A business requirement translates into functional requirements (what the system must do) and infrastructure requirements (latency, throughput, residency, availability, budget).
• Five extraction questions: latency sensitivity, volume, accuracy/criticality, data sensitivity, and cost ceiling.
• A low-latency, user-facing chat and an overnight bulk-analysis job sit at opposite ends of nearly every one of these axes.
• Solution architecture is driven by the requirement, not by defaulting to the biggest model or the realtime API.

Decision Rules

Key Points

• Claude applications still follow the standard SDLC: requirements -> design -> implementation -> testing/evaluation -> deployment -> operation -> maintenance.
• Non-deterministic, model-version-dependent behavior means evals with success criteria replace single equality assertions.
• Model-version pinning and regression testing gate every upgrade, not just the initial launch.
• Production monitoring of quality, latency, token cost, and error rate is an ongoing life-cycle activity.

Decision Rules

Key Points

• A request is a messages list (alternating user/assistant), plus model, required max_tokens, and optional top-level system, tools, temperature, stream.
• The system prompt is a top-level parameter, not a message with role: "system".
• stop_reason (end_turn, max_tokens, stop_sequence, tool_use) tells integration code why generation stopped and what to do next.
• usage reports input_tokens/output_tokens plus cache read/creation tokens -- the basis for cost modeling.
• The API is stateless: it keeps no memory between calls, so the full conversation must be resent every request.
• Streaming (server-sent events) lowers perceived latency without changing total tokens or cost; a tool_use stop_reason requires executing the tool and returning a tool_result; vision uses image content blocks alongside text.

Decision Rules

Key Points

• Extended thinking is an explicit reasoning budget spent before the answer; thinking tokens are billed as output tokens -- not a free upgrade.
• Prompt caching (cache_control) discounts a stable, reused prefix: cache reads are much cheaper, cache writes cost slightly more than normal input; it pays off through reuse.
• The Message Batches API processes many requests asynchronously within 24 hours at a substantial (roughly 50%) per-token discount.
• Realtime (Messages API, often streaming) fits interactive, user-waiting work; batch fits high-volume, cost-sensitive, 24h-tolerant work.
• The same Claude models are available via Amazon Bedrock and Google Vertex AI -- differences are auth, endpoint/region, and model-ID naming, not model behavior.

Decision Rules

Key Points

• The Claude API is HTTPS + JSON: status codes, headers, request/response shape, idempotency, and pagination apply like any REST service.
• Async/await and concurrency are the right tools for I/O-bound LLM calls; the SDKs ship async clients for exactly this.
• Git branching, PRs, and history are the substrate for reviewing and rolling back prompt/model changes, same as any code change.
• Prompts and model IDs are reviewable, versioned artifacts, not incidental strings exempt from SDLC/code review.
• 429/529/5xx are transient -- retry with exponential backoff and jitter; 400/401 are your bug -- fix and resend, retrying unchanged won't help.

Decision Rules

Key Points

• Four interfaces, four distinct instruction mechanisms: API/SDKs (system param + messages/tools/params), claude.ai (chat + Project instructions/knowledge), Claude Desktop (chat + connected MCP servers), Claude Code (CLAUDE.md + settings.json + slash commands).
• Each row is a genuinely different authoring surface, not a stylistic variant of the same thing.
• Instructions don't transfer verbatim across surfaces -- a CLAUDE.md shapes Claude Code, it does not configure a raw Messages API call.

Decision Rules

Key Points

• Content boundaries: keep trusted instructions separate from untrusted data (user input, retrieved documents, tool output); delimit clearly (e.g., XML-style tags).
• Schema design: define a JSON schema and use structured output/tool-forcing for machine-readable output that is strict but not brittle.
• Session hygiene: because the API is stateless and context is finite, deliberately decide what carries forward -- compact long threads, start fresh when polluted, don't let stale tool output accumulate.
• Plugin management: explicitly track which MCP servers/plugins are enabled, their permissions, and their versions.

Decision Rules

Key Points

• CLAUDE.md is project/repo memory for Claude Code and belongs in version control, reviewed like code.
• settings.json is Claude Code's settings surface: permissions, hooks, tool allow/deny lists, environment, model selection, MCP servers.
• Model-version pinning: use an explicit model ID rather than a floating "latest" alias -- a reproducibility hazard.
• Prompt versioning: treat prompts as artifacts with version history so a quality regression can be traced to a specific change.
• Plugin dependencies: track plugin/MCP-server versions like any other software dependency.

Decision Rules

Key Points

• Five component types: Rules (standing conventions, often in CLAUDE.md), Skills (SKILL.md, loaded when relevant), Commands (built-in + custom slash commands in .claude/commands/), Agents (delegated subagents), Agent Memory (persisted context, notably CLAUDE.md).
• Skill vs. Command distinction: Skills load implicitly on relevance; Commands are explicitly invoked by name.
• CLAUDE.md is the primary instance of Agent Memory, not a separate mechanism.
• Built-in slash commands include /clear (reset context), /init (bootstrap CLAUDE.md), /help.

Decision Rules

Key Points

• CLAUDE.md is auto-loaded project memory, not executable configuration.
• Four hierarchy levels, broadest to most specific: enterprise/system, user (~/.claude/CLAUDE.md), project (./CLAUDE.md), subdirectory.
• More specific files layer on top of broader ones -- they refine, they don't replace.
• Project-level CLAUDE.md is checked into version control so the whole team shares the same guidance.
• /init bootstraps a starter CLAUDE.md from an existing codebase.

Decision Rules

Key Points

• settings.json (user: ~/.claude/settings.json, project: .claude/settings.json) configures tool allow/deny lists, hooks, environment variables, model selection, and MCP servers.
• It is the deterministic control surface -- an allow/deny rule or hook blocks a dangerous command regardless of what the model proposes.
• CLAUDE.md is context/memory (probabilistic influence on the model); settings.json is executable configuration (deterministic enforcement).

Decision Rules

Key Points

• Session management: conversations persist as resumable sessions; /clear resets context to stay focused.
• Headless mode runs non-interactively (e.g., claude -p) for scripting/CI, with no interactive TUI.
• Streaming mode emits incremental output, including structured stream-JSON, for programmatic consumption.
• Auto-mode is reduced-friction autonomous operation with fewer confirmations -- pair it with settings.json permission rules and hooks.
• Headless mode (interactivity) and auto-mode (autonomy) are independent axes, frequently confused.
• Best-practice loop: gather context -> plan -> act -> verify, tightened with custom commands and hooks rather than long, brittle prompts.

Decision Rules

Key Points

• Five failure buckets: transport/HTTP (429/529/5xx/timeouts), request error (400/401), parsing/validation (code throws reading output), model-output error (well-formed but wrong), tool-loop error (wrong tool/malformed args/result not fed back).
• Three buckets live in the integration layer, one lives in the model's output, tool-loop errors straddle both.
• Core discipline: don't "fix" the prompt when the bug is in your code, and don't patch code when the model output is the problem.
• A JSON parse crash on a 200/end_turn response is an integration-layer parsing bug, not evidence the model is wrong.

Decision Rules

Key Points

• Reproduce-inspect-localize procedure: reproduce with the exact failing request; inspect the raw response (status, stop_reason, usage, content blocks) before any post-processing; localize by status and content quality.
• Non-2xx status localizes to the integration/transport layer; 2xx-but-throws localizes to parsing/validation; 2xx-and-parses-but-wrong localizes to model output.
• stop_reason: max_tokens means the output was truncated -- a common, easily misdiagnosed cause of "invalid JSON".
• Fix truncation by raising max_tokens, not by rewriting the schema or lowering temperature.

Decision Rules

Key Points

• A bad final answer in a multi-step agent is usually the end of a chain of steps, not an isolated event.
• Trace analysis: log every model call, tool call, arguments, tool result, and intermediate message, then walk the sequence.
• Look for the earliest deviation, not just the most visible or final one.
• Late-session quality degradation exposed in a trace often points to context bloat/drift, not a model defect.

Decision Rules

Key Points

• Recovery strategy follows diagnosis: retry+backoff for 429/529/5xx; fix-and-resend for 400/401; defensive parsing+reprompt/repair for malformed output; raise max_tokens for truncation; ground-and-constrain for hallucination; graceful degradation/human-in-the-loop when automated recovery can't guarantee correctness.
• Evals close the loop: a representative test set, a scoring method (exact match, graded rubric, or LLM-as-judge), and a target metric.
• Non-deterministic output means a single manual spot-check cannot verify a fix -- only a repeatable eval can, and it also catches future regressions.

Decision Rules

Key Points

• A token is roughly 3-4 characters of English; limits and billing are measured in tokens, not characters or words.
• Generation is autoregressive: the model predicts one next token from everything so far, appends it, and repeats until a stop condition.
• The context window is the max tokens (input + output combined) a model can consider in one request; exceeding it fails the request or forces truncation/summarization.
• The window is one shared budget across system prompt, conversation history, tool definitions, tool results, and the response -- not separate per-category allowances.

Decision Rules

Key Points

• Generation samples from a probability distribution at each step; temperature controls how focused (low) vs. diverse (high) that sampling is.
• Temperature 0 reduces randomness but does NOT guarantee identical output -- LLMs remain non-deterministic.
• Extended thinking is an explicit reasoning budget spent before the answer; adaptive thinking/effort levels vary depth automatically by difficulty -- both cost billed output tokens plus latency.
• Zero-shot, one-shot, and multi-shot/few-shot are the fundamental spectrum of example-based prompting; more examples cost more input tokens.
• Because exact reproducibility is never guaranteed, test with evals, not equality assertions.

Decision Rules

Key Points

• The official Python and TypeScript SDKs are a convenience layer over the REST API (auth, serialization, typed errors, retries, streaming helpers), not a separate protocol.
• Raw HTTPS + JSON calls to the same API are always available as a fallback to the SDK.
• Async clients parallelize independent, I/O-bound calls; sync clients block per call -- this affects wall-clock time, not token cost.
• Streaming (server-sent events) and websockets (bidirectional) are transport/delivery concerns -- they change when/how tokens arrive, not how many are billed.

Decision Rules

Key Points

• Three tiers: Haiku (fastest/cheapest, high-volume/simple tasks), Sonnet (balanced workhorse for most production logic), Opus (most capable, highest cost/latency, hardest reasoning).
• Right-sizing means matching capability to task difficulty and value, not defaulting to the most capable tier "to be safe."
• Quality, latency, and cost trade against each other -- anchor the choice on the specific requirement.
• Mixed-model architectures route cheap steps to Haiku and hard steps to Sonnet/Opus within one workflow.
• A newer model release can change behavior even with an unchanged API contract -- pin the version and re-run evals before upgrading.

Decision Rules

Key Points

• Input and output tokens are priced differently; output tokens are typically more expensive than input tokens.
• Cache writes and cache reads have their own distinct rates within the overall pricing structure.
• Cost modeling = estimated tokens per request type x per-token price, summed across expected traffic.
• The usage field (input/output/cache tokens) on every response is the instrumentation for tracking real cost and catching bloat.
• Capping max_tokens to a realistic ceiling prevents paying for runaway generations.

Decision Rules

Key Points

• cache_control caches a stable, reused prefix; cache reads are heavily discounted, cache writes cost slightly more than normal input -- the savings come from reuse, not the first call.
• Cache checkpointing keeps a long, incrementally-growing prompt mostly cached as new content is appended.
• The Message Batches API gives a roughly 50% per-token discount for asynchronous jobs completed within 24 hours.
• Batching reduces cost, not latency -- it is slower by design; caching and right-sized models reduce both cost and latency.

Decision Rules

Key Points

• State the task, constraints, and desired output explicitly -- ambiguity is the top cause of poor output.
• Positive framing ("respond only in JSON matching this schema") steers more reliably than long "don't" lists.
• Durable role, rules, and constraints go in the system prompt; the specific request and per-request data go in the user message.
• Output constraints (exact shape, length, structure) usually belong with the durable rules in the system prompt.

Decision Rules

Key Points

• Worked examples (zero-/one-/multi-shot) often lock in format and style more effectively than a paragraph of description.
• With long inputs, place the document first and the key instruction near the end, right before the response.
• XML-style tags and headings separate instructions from data and enable input sanitization.
• Untrusted user/retrieved text must be delimited and sanitized so it isn't read as an instruction -- ties directly to prompt-injection defense.
• Iterative refinement: diagnose the specific gap, change one thing, re-run, compare, and fold recurring lessons into the standing system prompt.

Decision Rules

Key Points

• The context window is one shared budget: system prompt, tool schemas, history, tool results, and retrieved docs all compete for the same space.
• The goal is the smallest set of high-signal tokens that maximizes the odds of the desired outcome.
• Context rot is attention degradation as the window fills with irrelevant or stale content, even with room technically left.
• Context drift is the gradual loss of track of instructions or facts over a long interaction.
• Compaction, pruning, isolation, and re-stating key constraints counter drift -- not temperature or more prohibitions.

Decision Rules

Key Points

• Tool-output pruning: keep only what later steps need from a large tool payload; drop raw dumps from the ongoing history.
• Compaction: periodically summarize older turns into a compact recap, reclaiming budget while preserving the thread.
• Compaction is not truncation -- truncation blindly drops tokens and can lose critical facts.
• Context isolation: delegate a heavy subtask to a subagent with its own window; it returns a condensed result.
• Just-in-time retrieval: pull information in when needed rather than front-loading everything.

Decision Rules

Key Points

• For machine-readable output, use tool use/tool-forcing (a tool whose input schema is the target shape) or structured-output features; prefilling (e.g., "{") can nudge JSON-only output.
• Validate structure AND semantics -- well-formed JSON can still be wrong.
• Defensive parsing: tolerate extra prose, handle truncation (stop_reason: max_tokens), and retry, repair, or fall back on failure.
• Claude can be confidently wrong -- polish and certainty are not evidence of correctness; ground high-stakes claims and keep a human in the loop.

Decision Rules

Key Points

• Prompt injection hides malicious instructions inside data the model processes (a web page, document, email, or tool result) -- the model cannot inherently distinguish data from instructions.
• A jailbreak is input crafted to bypass safety constraints directly (role-play framing, obfuscation, "developer mode").
• There is no syntactic boundary between instruction and data in natural language, unlike SQL injection -- the fix must be architectural, not linguistic.
• Core mitigations: isolate/delimit untrusted content, apply least privilege on tools, back both with guardrails/hooks, validate input and output.
• A larger, more instruction-following model can be MORE susceptible to injection, not less -- capability is not a security control.

Decision Rules

Key Points

• Minimize PII sent to the model; redact or tokenize sensitive identifiers before they reach it; only send what policy permits.
• Guard against the model or its tools exposing secrets, other users' data, or internal system details.
• Scope tool and data access per user so the agent structurally cannot read data it shouldn't see.
• Never put secrets in prompts or logs -- both are leakage surfaces.
• CIA + privacy (authentication, authorization, confidentiality, privacy, integrity) must hold end to end; the LLM is one component, not a replacement for ordinary security practice.

Decision Rules

Key Points

• Effective guardrails are multiple independent layers -- input filtering, restricted tool permissions, output validation/moderation, monitoring -- so one layer failing doesn't defeat the system.
• Deployments must respect Anthropic's Usage Policy (AUP).
• Secure-by-design: privacy, identity/access management, and least privilege belong in the design from the start, not bolted on later.
• Hooks (PreToolUse, PostToolUse, stop hooks) are deterministic code callbacks that run every time regardless of the model's decision.
• A prompt instruction is probabilistic; a hook is deterministic -- this is why hooks are the answer for "prevent a destructive action."

Decision Rules

Key Points

• API keys and secrets belong in environment variables or a secrets manager -- never hard-coded, committed to version control, or pasted into prompts/logs.
• Use separate keys per environment (dev/staging/prod); rotate on a schedule; revoke immediately on exposure.
• Authenticate every request (identity) and separately verify authorization/access level (least privilege) before the agent acts on a caller's behalf.
• Log and monitor authorized and attempted access so misuse is detectable.

Decision Rules

Key Points

• Tool-use loop: pass a tools array (name, description, input_schema) -> Claude emits a tool_use block (stop_reason "tool_use") -> your code executes it -> return a tool_result matched by tool_use_id -> Claude continues to end_turn.
• Claude never executes a tool itself -- it only requests the call; your application code runs it.
• Tool description quality (what it does, when to use it, what each parameter means) is the single biggest driver of correct tool selection.
• A precise input_schema (types, required fields, enums, per-field descriptions) produces well-formed arguments but doesn't replace a good description.
• Structured errors (an is_error flag or message) let Claude recover or retry instead of guessing; right-size the tool set to avoid overlap and context bloat.

Decision Rules

Key Points

• MCP (Model Context Protocol) is an open standard ("a USB-C port for AI") for connecting AI applications to external systems; build once, reuse across any MCP-compatible client.
• Three core primitives: tools (model-callable actions), resources (readable data/content loaded into context), and prompts (reusable parameterized templates) -- not just tools.
• The client lives inside the AI application and connects to one or more servers; each server advertises and handles its own tools/resources/prompts.
• Transports: stdio (local subprocess, single-user) vs. Streamable HTTP/sockets (remote, multi-client).
• Canonical use case: a capability that must be reusable across multiple Claude applications and maintained independently.

Decision Rules

Key Points

• Four mechanisms: built-in tools (Anthropic-provided, least effort), custom tools (app-specific logic living with one app), Skills (packaged instructions/procedures via SKILL.md, no running service), MCP servers (reusable across apps, independently maintained).
• Selection heuristic: does a built-in already do it? Use it. App-specific? Custom tool. Reusable know-how, no service needed? Skill. Shared across apps, independently maintained? MCP server.
• Built-in tools have fixed capabilities and cannot automatically reach an arbitrary internal API.

Decision Rules