Blog

Anthropic runs four role-based Claude certifications: Associate – Foundations, Developer – Foundations, Architect – Foundations and Architect – Professional. Most guides online repeat numbers from each other. This one sticks to what Anthropic's own pages state (the certifications article and the Partner Academy certification FAQ, both read on 2026-11-09) and says plainly where they are silent. The first thing to know is not the syllabus but the gate: the exams are currently open only to people at organizations in the Claude Partner Network. After that, the useful questions are which exam matches the work you do, what the exam session looks like, what it costs to sit and keep, and how to prepare without memorizing facts that change with every model release.

One of the most persistent frustrations in AI-assisted development is API Drift. You ask an AI coding assistant to write a Next.js 15 route, configure Tailwind CSS v4, or query a database with Drizzle ORM, and it confidently emits deprecated syntax, non-existent methods, or broken configuration flags. The model is not broken—its parametric weights are simply frozen at its pretraining knowledge cutoff date. Generic web search tools fail to solve this because they flood agent context windows with messy HTML, outdated 2021 Medium tutorials, and SEO spam. To bridge this gap, modern agent architectures rely on Documentation Model Context Protocol (Doc MCP) servers—exemplified by projects like Context7 (developed by Upstash). Documentation MCP servers give AI agents direct, on-demand access to real-time, version-pinned, AST-pruned official documentation for over 2,000+ libraries. Explore our complete agentic coding guide and our LLM internals masterclass for deep architectural context. This guide explains why Documentation MCP servers are essential, how Context7's ingestion pipeline operates, and how to integrate live documentation tools across Claude Code, Cursor, and autonomous agent swarms.

Most multi-agent software engineering frameworks suffer from the same fatal flaw: they treat coding as a simulated conversational chat. Frameworks like AutoGen, CrewAI, and ChatDev assemble anthropomorphic personas ("Product Manager", "Architect", "Developer", "QA") and pass volatile in-memory JSON messages across conversational loops. As soon as token limits are reached, a process crashes, or multiple agents write to the same repository, the entire session collapses under Context Rot and Git merge chaos. Created by Steve Yegge in early 2026, Gastown (or "Gas Town") fundamentally redefines multi-agent software development. Instead of building conversational roleplay chat rooms, Gastown treats software engineering as an industrial factory runtime—coordinating 20 to 30 concurrent headless AI coding agents (such as Claude Code instances) across isolated environments. Explore our complete agentic coding guide and our coding agents comparison for related context. This technical architectural breakdown explores Gastown's core systems contributions: Git-backed durable external memory (Beads), ephemeral worker sessions in isolated Git worktrees (Polecats), autonomous lifecycle watchdogs (Witness and Deacon), dedicated merge queues (Refinery), and the Gastown Universal Propulsion Principle (GUPP).

Large Language Models (LLMs) are often described as black boxes, yet their behavior is the direct outcome of a deterministic, multi-stage engineering pipeline. Transforming raw, unstructured internet scrapes into aligned, tool-using reasoning agents requires mastering five foundational phases: data extraction and deduplication, subword tokenization, high-throughput inference caching, supervised post-training, and reinforcement learning alignment. Understanding these internal mechanisms is essential for modern software architects. Why do models fail at simple letter counting? Why does generation speed stall on long contexts? How does loss masking work during Supervised Fine-Tuning (SFT)? And how do reasoning models scale compute during test-time? See our related LLM architecture guide and post-training techniques comparison for architectural context. This deep-dive guide traces the complete technical lifecycle of frontier LLMs from raw pretraining web crawls to autonomous tool execution and verifiable reasoning.

Software engineering has undergone a fundamental architectural shift. The era of inline tab-autocomplete copilots has given way to autonomous agentic coding systems—harnesses capable of decomposing multi-file architectural specifications, managing their own context windows, invoking compilers through standardized protocols, and orchestrating teams of specialized subagents in sandboxed environments. However, naive reliance on raw LLM generation quickly collapses into Context Rot, infinite hallucination loops, and catastrophic production regressions. Moving from fragile "vibe coding" to production Vibe Engineering requires understanding the complete systems stack: tool interfaces, token budget management, protocol standards like MCP, repository steering directives (AGENTS.md), and self-correcting feedback loops (Ralph Loops). Explore our coding agents comparison and our Claude Code workflow guide for related foundations. This master guide dissects the full architecture of modern agentic coding systems, comparing current tooling paradigms, multi-agent coordination models, and the exact workflows required to ship verified code autonomously.

Claude Code has a dense vocabulary because it is more than a chat box beside your editor. The important terms describe where the model runs, what it can see, what it may do without approval, how it remembers context, and how teams package repeatable agent work. This guide turns the buzzwords into an engineering map, current as of 2026-08 and checked against the official Claude Code overview, docs index, and glossary. For a deeper architecture reference, see our Claude Code overview guide; for the broader agent stack, read Prompt vs Context vs Harness.

AI coding agents change where engineering effort is spent: the hard problem moves from typing code to defining boundaries, checking outputs, and recovering from unsafe or incorrect actions. The useful mental model is a controlled execution loop—request, plan, tool call, verification, and human review—not a group of agents that can be trusted because they are autonomous. This guide maps delegation topologies, Claude Code extension points, state coordination, and isolation. It uses a small hypothetical finance-analysis service as a running example; provider names and performance figures are intentionally omitted unless they are measured for a stated workload.

Claude Code is an agentic coding tool that can inspect a repository, propose edits, run permitted commands, and work through a task in a terminal session. The important boundary is not the interface label; it is the permission mode, working directory, tools, credentials, and network access available to that session. This guide gives a practical overview of installation, project instructions, MCP, hooks, and non-interactive CLI use. Fast-moving features such as cloud sessions and integrations should be checked against the current Anthropic documentation before adoption.

Claude Code can run shell commands, edit files, and fetch URLs. Permission rules decide which of those actions run without asking, which prompt you, and which never run at all. Get them right and you can let Claude run npm test all day while npm publish and your .env file stay out of reach. This guide covers the rule system as documented by Anthropic: the evaluation order, the Tool(specifier) syntax for each tool, how Bash rules handle compound commands and wrappers, what they cannot match, how symlinks are checked, and when to reach for a PreToolUse hook instead. Permission modes, which set the baseline that rules sit on, are covered in Claude Code Auto Mode; OS-level isolation is in Claude Code Sandboxing and Isolation.

Claude Code is an agent that works in your project: it reads files, edits them, and runs commands such as your test suite. That makes the first session different from using a chat assistant. The useful habits are less about prompts and more about setup: which permission mode you are in, what Claude can run to check its own work, and how to undo a change that went wrong. This guide walks through a first session in the terminal, following Anthropic's quickstart and best-practices pages: install, log in, generate a CLAUDE.md, ask questions before changing anything, make a change with a test as the check, and recover with Esc, /rewind, and git. The last sections cover the other places Claude Code runs (VS Code, JetBrains, the desktop app, the web, and the Claude mobile app) and a short exercise. If agents are new to you, read What Is Agentic AI first. For the loop underneath, see How Claude Code Works.

Claude Code follows your CLAUDE.md most of the time. A hook makes something happen every time. Hooks are shell commands (or HTTP calls, prompts, or MCP tool calls) that Claude Code runs at fixed points in a session: before a tool call, after it, when Claude finishes a reply, when a session starts. Because they run outside the model, they give you deterministic control: the formatter always runs after an edit, and a push to main is always refused, whatever the model decides. This guide follows the official hooks reference. It covers the event list, the three-level configuration shape, the JSON a hook receives on stdin, what exit codes and JSON output mean, and four working hooks: blocking pushes to main, protecting files, formatting after edits, and a Stop hook that sends Claude back when tests fail. It ends with the security model, which matters more than any example, because a hook runs with your full user permissions. Hooks sit next to permission rules, which are covered in Claude Code Permissions, and permission modes, covered in Claude Code Auto Mode. For where hooks fit in the agent loop, see How Claude Code Works.

The Claude Agent SDK gives your own programs the same agent loop that runs Claude Code: you call query() with a prompt and options, and Claude reads files, runs tools, observes the results, and keeps going until the task is done, while you consume a stream of messages. The SDK handles orchestration, tool execution, context management, and retries. It is not the plain Messages API, where you would have to implement every tool yourself; here the built-in tools (Read, Edit, Bash, Glob, Grep, WebSearch, and others) already work. This guide follows Anthropic's SDK quickstart and custom-tools pages to build a small agent that finds and fixes crash bugs in a Python file, in both Python and TypeScript. It then covers the options that matter (tools, permission modes, system prompt), how to add a custom tool through an in-process MCP server, authentication rules, and where to go next. For a broader tour of the SDK, see Claude Agent SDK Guide.

Running several Claude Code sessions in separate terminals works until you lose track of which one is waiting for you. Agent view, opened with claude agents, is one screen for all your background sessions: what is running, what needs your input, and what is done. You dispatch work from it, peek at a session or reply without leaving the list, attach when you need the full conversation, and detach again without stopping anything. Agent view is a research preview: the interface and shortcuts may change. This guide follows Anthropic's documentation for it: opening it and dispatching sessions, the supervisor process that keeps them running, the six states, peeking and attaching, how file edits are isolated in worktrees, the shortcuts worth learning, and the limits, which matter more than the feature list. For the worktree mechanics underneath, see Claude Code Worktrees; for sessions that run in the cloud instead of on your machine, see Claude Code Cloud Sessions.

Some tasks are bigger than one conversation can coordinate: audit every route handler for missing auth checks, migrate 500 files, cross-check a research question against many sources. Claude Code's dynamic workflows handle these by moving the plan into code. Claude writes a JavaScript script that spawns and coordinates subagents; a runtime executes it in the background while your session stays responsive; and you get one result at the end instead of a long turn-by-turn transcript. Because the orchestration is a script, you can read it, rerun it, and save it as a command. Workflows are available on all paid plans, with Anthropic API access, and on Bedrock, Google Cloud, and Foundry (on Pro, turn them on in /config). This guide follows Anthropic's workflows documentation: when a workflow fits better than subagents or agent teams, running the bundled /deep-research, asking Claude for a workflow or turning on ultracode, approval and permissions, the script format, the runtime's limits, resuming, and cost. For the worker primitive underneath, see Claude Code Workflows for everyday subagent use, and Agent View for parallel full sessions.

When a few engineers use Claude Code, each person's ~/.claude/settings.json is enough. When a company rolls it out to hundreds, someone has to make sure every session blocks reads of .env, cannot switch to bypass mode, uses approved models, and reports usage, and that no developer can quietly turn those off. Claude Code's answer is managed settings: a settings layer that sits above every user and project file and that only administrators control. This guide follows Anthropic's admin documentation. It covers the settings hierarchy, the two ways to deliver a managed policy (from the claude.ai admin console, or onto each device through MDM or a system file), a starter policy, model restrictions, OpenTelemetry, and how to check that a policy actually reached a machine. It ends with the gaps, because a managed policy that silently does not apply is worse than none: you believe a control exists when it does not. For the permission rules a policy contains, see Claude Code Permissions. For routing traffic through your own proxy, see Claude Code Gateway Routing and Security.

Many companies already run an LLM gateway, such as LiteLLM, a cloud API gateway, or an in-house proxy, between their developers and the model providers. Claude Code works behind one: point it at the gateway's URL, give it a gateway-issued credential, and every model request goes through the gateway instead of straight to Anthropic or your cloud provider. The setup is two environment variables. The hard part is everything around them: which credential variable puts the key in which header, how to distribute the configuration so developers do not set it by hand, which headers and body fields the gateway must pass through untouched, and what still bypasses the gateway. This guide follows Anthropic's gateway documentation for each of those, and ends with the errors you are most likely to hit. Anthropic also ships its own self-hosted gateway, the Claude apps gateway, aimed at organisations that run Claude through Bedrock, Google Cloud, or Foundry. It is covered in Claude Apps Gateway. For the managed settings used to distribute gateway configuration, see Claude Code Enterprise Setup.

Claude Code cloud sessions normally run on Anthropic-managed VMs. A self-hosted environment keeps the same developer experience (start a session from claude.ai, the desktop or mobile app, claude --cloud, or a routine) but runs the session on runners, processes you operate inside your own network, much like self-hosted CI runners. Sessions can then reach internal services, databases, and registries, use your pre-built toolchain, and keep checkouts and build artifacts on your machines. It is in public beta on Team and Enterprise plans and off by default. This guide follows Anthropic's self-hosted documentation: how environments, runners, and sessions fit together, what stays on your infrastructure and what does not, a first runner, the runner lifecycle that production deployments must design around, and the limitations. It is not a way to run Claude Code fully on-premises: the control plane, the conversation, and by default model inference stay with Anthropic. For local sessions on developer machines, nothing here applies. See also Claude Code Cloud Sessions.

Claude Code is billed by tokens, and its token use is driven less by how much you type than by how much context it carries: every request sends the conversation so far, including the files Claude read and the output of every command it ran. That is why one person's costs can be several times another's for similar work, and why the most effective cost controls are habits, not settings. This guide follows Anthropic's cost documentation. It starts with the only published benchmark numbers, then covers reading /usage, where spend is seen and capped for each way of accessing Claude Code, the rate limits Anthropic recommends by team size, why usage climbs in long sessions, and the changes that reduce it. For organisation-wide telemetry, see Claude Code Enterprise Setup; for how context fills up, see Claude Code Context Window.

A security review of Claude Code has to answer two kinds of question. What happens to our data once it leaves the laptop: is it used for training, how long is it kept, where is it encrypted? And what can the agent do on the laptop: which commands it runs without asking, how it handles untrusted content, and what we can enforce centrally? Anthropic documents both, and this guide collects the answers in one place, quoting the policy pages rather than paraphrasing them into stronger claims. It covers the data policy (training, retention, Zero Data Retention, encryption), telemetry and how to turn it off, the client's built-in protections and their documented limits, prompt injection, MCP and cloud-session security, and a practical checklist for a regulated rollout. Certifications and compliance artefacts live in Anthropic's Trust Center; this guide does not restate them as guarantees. For enforcement mechanics, see Claude Code Enterprise Setup and Claude Code Permissions.

anthropics/claude-code-action runs Claude Code inside your repository's GitHub Actions workflows. Mention @claude in an issue or pull request and Claude reads the code, answers, or pushes commits; give the workflow a prompt and it runs on any event you choose, including a schedule. It is built on the Claude Agent SDK and uses the same CLI arguments as Claude Code on your machine. This guide follows Anthropic's GitHub Actions documentation: the two run modes, quick and manual setup, three working workflows (respond to @claude, review pull requests with a skill, run a daily report), who is allowed to trigger runs, the GitHub App's permissions, costs, troubleshooting, and upgrading from the beta. Check the action's configuration reference for the full input list before relying on an input not shown here. If you want automatic reviews on every pull request without maintaining a workflow file, Anthropic's separate Code Review product does that. For GitLab, see Claude Code in GitLab CI/CD; for running Claude non-interactively in your own scripts, see Claude Code CLI Reference.

Mention @Claude with a coding task in a Slack channel and Claude can start a Claude Code cloud session, work on one of your GitHub repositories, post progress in the thread, and hand back a pull request. The context the request needs, such as a bug report and the discussion around it, is already in the conversation, which is what makes Slack a natural place to start the work. There are now two Slack integrations, and which one applies depends on your plan and workspace. The earlier Claude Code in Slack runs each session under the mentioning user's own Claude account, and answers channel mentions only from Pro and Max accounts in workspaces not connected to Claude Tag. Claude Tag is the organisation-managed version for Team and Enterprise, where @Claude acts as the organisation's shared identity with admin-configured access. This guide follows Anthropic's documentation for the earlier version, notes where Claude Tag differs, and covers setup, routing, the session flow, the security model, and limits. Sessions run in the cloud, so Claude Code Cloud Sessions explains the environment underneath.

A routine is a saved Claude Code job: a prompt, one or more GitHub repositories, a cloud environment, and a set of connectors, packaged once and run automatically on Anthropic's cloud infrastructure. Triggers start it: a schedule, an HTTP call to its own endpoint, or a GitHub event such as a pull request being opened. Because runs happen in the cloud, they continue while your laptop is closed. Routines are in research preview, so limits and the API may change. This guide follows Anthropic's routines documentation: creating one, each trigger type (including the /fire API call), what a run can do without asking, how to scope it, the hourly limits, and troubleshooting. Each run is a cloud session, so Claude Code Cloud Sessions is useful background. For scheduling inside an open CLI session instead, see Claude Code Scheduled Tasks.

Claude Code runs in GitLab CI/CD as an ordinary pipeline job: the job installs the Claude Code CLI on your runner, calls claude -p with a prompt, and the changes come back as a merge request that goes through your normal approvals. Anthropic documents the integration, but it is in beta and maintained by GitLab, so expect it to change and look to the linked GitLab issue for support. This guide follows that documentation: the quick-setup job, line by line; what it takes to make @claude comments start a pipeline (it is not automatic); Bedrock and Google Cloud through OIDC with no stored keys; security and cost controls; and troubleshooting. If you use GitHub instead, the native action is covered in Claude Code GitHub Actions; for the -p flag and its options, see Claude Code CLI Reference.

Most Claude Code work is one of a handful of jobs: understand unfamiliar code, fix a bug, refactor, add tests, write documentation, open a pull request. Each one goes better with the same discipline: narrow the scope, give Claude something it can run to check itself, and review the evidence rather than the claim. This guide turns Anthropic's common-workflows and best-practices pages into recipes for each job, with prompts you can copy, and adds the session tools that keep long tasks on track: plan mode, subagents, rewind, and /clear. It assumes you have a working setup; if not, start with Getting Started with Claude Code. For making checks run automatically after edits, see Claude Code Hooks.

There are two ways to use Claude Code in VS Code. The extension gives you a graphical chat panel with side-by-side diffs, plans you can annotate, and conversations in editor tabs. The CLI, run in VS Code's integrated terminal, gives you the full command set and still opens its diffs in VS Code's diff viewer, through a small local server the extension runs. Both share the same settings, CLAUDE.md files, MCP servers, and conversation history. This guide follows Anthropic's VS Code documentation: installing and opening the extension, what context it sends with each prompt (and what it withholds), reviewing changes, plan mode, checkpoints, the settings that matter, how the CLI connects, and the shortcuts worth learning. Version numbers are noted where features are recent; the extension's version is the Claude Code version it bundles. For JetBrains IDEs, see Claude Code for JetBrains. For the permission modes referenced throughout, see Claude Code Auto Mode.

Claude Code's JetBrains integration is different from its VS Code extension. There is no chat panel: the plugin runs the claude CLI in the IDE's integrated terminal and connects it to the IDE, so Claude's edits open in the IDE's diff viewer, your current selection is shared as context, and Claude can read the IDE's inspection results. It works with IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm, GoLand, and most other JetBrains IDEs. This guide follows Anthropic's JetBrains documentation: what to install, how to launch and connect, configuration, the security issue specific to JetBrains, remote development and WSL2, and troubleshooting. For the VS Code equivalent, see Claude Code in VS Code; for the CLI basics, see Getting Started with Claude Code.

The Claude desktop app has three tabs: Chat, Cowork, and Code. The Code tab is Claude Code with a graphical interface. It runs the same engine as the CLI, reads the same settings and CLAUDE.md files, and adds things a terminal cannot easily show: a sidebar of parallel sessions, a diff viewer you can comment on line by line, a browser pane for previewing your app, and panes you can arrange side by side. This guide follows Anthropic's desktop documentation. It covers installing the app, where a session can run (locally, in the cloud, or over SSH), the review loop, parallel sessions in Git worktrees, the workspace panes, and how Desktop relates to the CLI, including the features that only the CLI has. New to Claude Code itself? Start with Getting Started with Claude Code. For running parallel work from the terminal instead, see Claude Code Worktrees and Parallel Sessions.

A cloud session is a Claude Code session that runs on a virtual machine Anthropic manages instead of on your laptop. You start it from [claude.ai/code](https://claude.ai/code), the Claude mobile app, the desktop app, or the terminal with claude --cloud. It clones your GitHub repository, works on its own branch, keeps running after you close the tab, and pushes the branch for you to review. That makes cloud sessions good for tasks you can describe well and do not need to steer constantly: a flaky test, a documentation update, a well-specified refactor, or several of those in parallel. It also makes them different from a local session in ways that catch people out: only what is committed to the repository is available, network access is limited by default, and secrets need special handling. This guide follows Anthropic's cloud-session documentation: setup, environments and network access, setup scripts, what carries over from your machine, moving work between terminal and cloud, auto-fixing pull requests, and the limits. For the local alternatives, see Claude Code Desktop App and Getting Started with Claude Code.

There is no separate Claude Code mobile app. The Claude app for iOS and Android has a Code tab, and it is a client: no code runs on your phone. From it you reach work that runs somewhere else: a cloud session on an Anthropic-managed VM, a Claude Code session running on your own computer through Remote Control, or the desktop app through Dispatch. Which one you use decides almost everything: whether your laptop must stay on, whether Claude can see your local files and tools, which permission modes you get, and what data is stored where. This guide follows Anthropic's mobile and Remote Control documentation and covers each path, push notifications, the connection's security model, and the limitations. For cloud sessions in depth, see Claude Code Cloud Sessions. For the desktop app and Dispatch, see Claude Code Desktop App.

"MCP or OpenAPI?" is a common question when connecting AI agents to tools, and it is slightly the wrong question. The Model Context Protocol is a protocol: a client and a server exchange JSON-RPC 2.0 messages at runtime to discover and call tools, read resources, and fetch prompt templates. The OpenAPI Specification is a description format: a YAML or JSON document that describes an HTTP API's paths, operations, parameters, and responses, so that tools (and models) can understand and call it without reading its source. One is a conversation, the other is a contract. Both can end in the same place, a model calling a function, and both are used that way: MCP servers by hosts such as Claude Code, Gemini CLI, and ChatGPT, and OpenAPI documents by tools that turn an API description into function definitions, such as ChatGPT's Custom GPT Actions. This guide compares how each works, where each fits, and how they are often combined. It follows the MCP specification (2025-06-18) and the OpenAPI 3.1 specification. For a hands-on MCP setup, see MCP with ChatGPT and the OpenAI API.

Asking a model to "reply in JSON" works until it does not: a missing field, a trailing comment, a number returned as a string, a polite sentence before the opening brace. Production code needs output it can parse and trust. There are three levels of help available: JSON mode, which only promises valid JSON; native structured outputs, where the provider constrains decoding so the response follows your JSON Schema; and validate-and-retry libraries such as Instructor, which check the result against a Pydantic or Zod model and ask again on failure. This guide explains how each works, using OpenAI's and Anthropic's structured-output documentation and the Instructor docs: the request shapes, the SDK helpers for Pydantic and Zod, the JSON Schema subset the providers support, and the exceptions they document, because "always matches the schema" has fine print. For giving models tools rather than output formats, see MCP vs OpenAPI.

Google's Gemini CLI is an open-source coding agent for the terminal. Three mechanisms decide what it knows and what it can do: context files (GEMINI.md), which give it instructions; MCP servers, which give it tools; and extensions, which package context, MCP servers, commands, and more into something you can install and share. This guide covers all three, following the project's own documentation in the google-gemini/gemini-cli repository, with the exact file locations, settings keys, and commands. It replaces three shorter posts that covered these topics separately, some with commands that do not exist. For how Claude Code handles the same ideas (CLAUDE.md, MCP, plugins), see Claude Code Directory Structure; for MCP itself, see Claude Code MCP and Plugins.

LangChain, LlamaIndex, and the Claude Agent SDK all help you build applications where a model calls tools, but they start from different centres of gravity. LangChain gives you a configurable agent harness (create_agent) on top of a graph-and-state runtime, with middleware for retries, human approval, and summarisation, across many model providers. LlamaIndex starts from your data: loaders, chunking, indexes, and query engines, with agents built on top. The Claude Agent SDK packages Claude Code's own agent loop, with working file, shell, and search tools, permissions, and hooks, for Claude models. This guide compares them by what each is built around, shows a current minimal agent in each (from each project's documentation), and covers trade-offs, failure modes, and a common hybrid. Framework APIs move fast, so treat the code as a starting point and check the linked docs for your version. For the Agent SDK in depth, see Claude Agent SDK Quickstart; for retrieval itself, see RAG Evaluation: Retrieval vs Answer Quality.

The Model Context Protocol (MCP) is an open protocol for exposing tools, resources, and prompts to AI applications over JSON-RPC 2.0. One server can serve many hosts: Claude Code, Gemini CLI, ChatGPT, and your own agents built on the OpenAI Responses API. This guide covers the OpenAI side of that picture: what your server must implement, how to connect it to ChatGPT as a custom server, how the Responses API's mcp tool works (including its approval flow), and the risks OpenAI itself warns about. One caution up front. OpenAI has renamed the ChatGPT side of this several times (connectors, apps, and now plugins), so the exact UI path will change. The protocol and the API fields change much less, so this guide anchors on those and dates the UI steps. For the same server in Claude Code, see Claude Code MCP and Plugins.

Claude Code reads configuration from a small set of files in your project and in ~/.claude, and writes session data to ~/.claude as it works. Knowing which file does what answers most "why didn't that apply?" questions, keeps personal settings and secrets out of your repository, and tells you where transcripts of everything Claude read are sitting on disk. This guide follows Anthropic's .claude directory reference. It covers the project files, the personal and global files, how to choose the right file for a change, the frontmatter each kind of file accepts, and the application data Claude Code stores, including what is cleaned up automatically and how to delete the rest. For the settings precedence that decides which value wins, see Claude Code Enterprise Setup; for CLAUDE.md in large repositories, see Claude Code in Monorepos.

Two Claude Code sessions in the same checkout edit the same files, and sooner or later one overwrites the other's work or runs the tests in the middle of the other's change. A git worktree fixes that: a separate working directory with its own files and branch that shares the repository's history and remote with your main checkout. Claude Code builds this in: claude --worktree <name> creates a worktree and starts the session inside it. This guide follows Anthropic's worktrees documentation. It covers starting sessions in worktrees, setting up each one (including copying .env with .worktreeinclude), what happens on exit, resuming, how Claude Code enforces isolation and where that stops, worktrees for subagents, choosing the base branch, manual git worktree use, and the errors you may hit. It replaces two older posts on this site that covered the same topic. For the desktop app's worktree option, see Claude Code Desktop App. For sparse worktrees in a monorepo, see Claude Code in Monorepos.

An agent that runs for four seconds inside one HTTP request can afford to fail: the user retries and nothing else happened. An agent that runs for eleven minutes, calls a payments API, waits on a human approval, and then sends an email cannot. When the worker process dies at minute seven, you are left with a half-applied transaction that no retry can safely repeat — the refund already left your account, but nothing recorded that it did. Durable execution is the pattern that fixes this class of bug. The idea is narrow and old: write every completed step to a log before moving on, and on restart, rebuild the in-memory state by reading the log instead of redoing the work. This guide traces that mechanism through one running example — a refund agent handling ticket TCK-4417 for order ORD-9912 — and shows exactly where LLM non-determinism has to be quarantined for replay to stay correct. If you want the surrounding context first, read Agent Planning vs Workflow Orchestration and browse AI, LLM & Agentic Systems.

A base language model finishes text. It does not answer questions, refuse harmful requests, or stop talking at the right moment — those behaviors are installed after pre-training, in a phase that now has four distinct algorithm families and a lot of confused vocabulary around them. Teams routinely say "we fine-tuned it with RLHF" when they ran DPO on a preference file, or "we used RL" when the only reward was a unit-test exit code. The distinctions matter because each method applies a different gradient, needs a different number of models resident in GPU memory, and fails in a different way. This guide traces all four on one running task: teaching a 7B model to write correct Python for a small internal library, evaluated by a fixed suite of 200 held-out problems. You will see the exact loss each method optimizes, the memory it demands, the failure it produces, and the condition under which it beats the alternatives. For the prerequisite view of what fine-tuning is for at all, start with Fine-Tuning vs RAG vs Prompting, and browse AI, LLM & Agentic Systems for the surrounding stack.

A 70B-parameter model does not fit on an 80GB GPU, and the reason is not the parameters. In mixed-precision training with Adam you carry roughly sixteen bytes per parameter — half-precision weights, half-precision gradients, a full-precision master copy, and two full-precision optimizer moments — before a single activation is stored. That is about 1.1TB of state for 70B parameters. No single accelerator on the market holds it. So the model gets cut apart, and there are four distinct ways to cut it. Each one shards a different axis, each one pays for itself with a different collective communication operation, and picking the wrong one for your interconnect turns an expensive cluster into an idle one. This guide traces all four on one concrete configuration — a 70B dense transformer on 64 H100s across 8 nodes — and shows the exact collective each strategy issues per layer. If you need the architecture background first, read Transformer Architecture and Self-Attention Explained; for the training stage that comes after this one, see LLM Post-Training: SFT vs DPO vs GRPO and RLVR.

Artificial intelligence terminology moves so fast that concept definitions quickly become bloated with marketing fluff and overlapping jargon. Understanding the underlying mechanisms—how Transformers process tokens, how RAG retrieves vectors, how agents execute tools via MCP, and how LoRA fine-tunes models—is essential for engineering reliable production systems. This guide establishes a working vocabulary of 60+ core AI terms grouped logically across 6 domain pillars. Each section includes technical definitions, engineering comparison matrices, architecture diagrams, and a clear-eyed evaluation of industry buzzwords. For orchestration patterns, see our Agentic Engineering Masterclass.

In a small repository, Claude Code's defaults work: one CLAUDE.md, launch from the root, let it search. In a monorepo with dozens of packages, the same defaults fill the context window with instructions for code you are not touching and with file reads you did not need. The cost shows up as more tokens per task and as instructions that get followed less consistently. This guide follows a three-package monorepo (packages/api, packages/web, packages/shared) and applies the settings Anthropic documents for large codebases: where to launch, how to split CLAUDE.md, how to keep committed generated code out of reads, and how to keep worktrees small. For how the context window fills and compacts, see Inside Claude Code's Context Window; for running parallel sessions, see Parallel Coding with Git Worktrees.

Plan mode is the Claude Code permission mode for thinking before touching code. Claude reads files, runs commands to explore, and writes a plan, but does not edit your source until you approve it. Approving the plan then switches the session into the permission mode you choose, and Claude starts working. That sounds simple, and mostly is, but a few details decide whether it protects you: which shell commands still run during planning, the one kind of session where plan mode's blocks are not enforced, what each approval option switches you to, and how it behaves in the Agent SDK and headless runs. This guide covers each, from the Claude Code documentation, plus practical advice on getting plans worth approving. It replaces our earlier Ultraplan guide: Anthropic has removed the Ultraplan research preview, and the docs now point to plan mode for local planning. For the other permission modes, see Claude Code Permissions and Claude Code Auto Mode.

A CLAUDE.md file is where you write down what you would otherwise re-explain to Claude Code every session: the build command it cannot guess, the directory where handlers live, the convention that differs from the language default. Claude reads it at the start of every conversation. The catch is in how it is read. CLAUDE.md is context, not enforced configuration: it arrives as a message after the system prompt, and Claude tries to follow it, with no guarantee. So the quality of the file decides how much it helps. Long, vague, or contradictory files get followed less, and the documentation is direct about it: target under 200 lines per file. This guide covers what to put in a CLAUDE.md and what to leave out, how to phrase instructions so they can be checked, how files load and combine, when to move content to path-scoped rules, skills, or hooks, how AGENTS.md fits in, and how to debug an instruction Claude ignores. It is based on the Claude Code memory and best-practices documentation. For where every Claude Code configuration file lives, see Claude Code Directory Structure.

A Claude Code skill is a folder with a SKILL.md file: YAML frontmatter that says what the skill is for, and markdown instructions Claude follows when it runs. You can type /skill-name to run it, and Claude can load it on its own when your request matches its description. The documentation's rule of thumb for when to write one: you keep pasting the same instructions, checklist, or procedure into chat, or a section of CLAUDE.md has grown into a procedure rather than a fact. The reason skills scale better than CLAUDE.md is how they load. Only the description sits in context all the time; the body loads when the skill is invoked, and supporting files load only if Claude reads them. Long reference material costs almost nothing until it is needed. This guide builds one real skill end to end, a pr-ready check that runs before you open a pull request, and covers each piece on the way: where skills live, frontmatter, descriptions that trigger correctly, injected live context, a bundled script that runs without a permission prompt, invocation control, running in a subagent, and how to evaluate whether the skill helps. Everything is checked against the Claude Code skills documentation. For what belongs in CLAUDE.md instead, see How to Write a CLAUDE.md; for ready-made skills, see Top Claude Skills.

An AI agent that calls tools sounds like it needs a framework. It doesn't. The model never runs anything itself: it returns a structured request to call a tool, your code runs the tool, and you send the result back in the next request. Repeat that until the model says it is finished, and you have an agent. The Claude docs describe the canonical shape as a while loop keyed on stop_reason. This guide builds that loop in about 50 lines of Python on the raw Claude Messages API, with two read-only tools (list_files and read_file) that can answer questions about a codebase. It covers each part a real loop needs: tool definitions, the message history, the pairing of tool_use and tool_result blocks, every stop reason, a turn limit, and error handling. Then it ports the same loop to the OpenAI Responses API, so you can see which parts are universal and which are one vendor's wire format. The code was run against the official anthropic (1.15) and openai (3.35) Python SDKs using a local stub server that returns scripted API responses, including parallel tool calls, a path-escape attempt, an unknown tool and malformed JSON arguments. It was not run against the live APIs, so check the model name before you use it. For the pattern behind the loop, see The ReAct Pattern; for what frameworks add on top, see LangChain vs LlamaIndex vs Agent SDK.

A language model does not output text. At each step it outputs one score per vocabulary token, and a separate piece of code, the sampler, turns those scores into a single chosen token. Temperature, top-k, top-p and min-p are settings on that sampler. They do not change what the model knows; they change how much of its probability distribution you are willing to draw from. The settings are easy to describe and easy to misuse, because their effect depends on the shape of the distribution at each step. This guide works through each one with numbers: a five-token example for temperature, a peaked and a flat distribution for truncation, and a 1,005-token example for what happens at high temperature. Every figure was computed with the short Python implementation included below, and the method definitions follow the original papers: Holtzman et al. (2020) for top-p and Nguyen et al. (2025) for min-p. It also covers two practical facts that change how you use these settings in 2026. The order in which samplers run differs between engines. And several hosted APIs no longer let you change them at all: Claude models released after Claude Opus 4.6 reject non-default temperature, top_p and top_k, and OpenAI's reasoning models reject temperature and top_p unless reasoning effort is none. For where logits come from, see LLM Architecture Explained.

BM25 is a ranking function from the 1990s that still runs behind Lucene, Elasticsearch and OpenSearch, and it is still the baseline that new retrieval models are measured against. It scores documents by the query words they contain, weighted by how rare each word is, with two corrections: repeated words help less and less, and long documents need more matches to score the same. That simplicity is the reason it still matters in retrieval-augmented generation. An embedding model compares meaning, which handles paraphrases well but can blur near-identical identifiers. BM25 compares exact tokens, which fails on paraphrases but is precise for error codes, product IDs and rare names. This guide builds BM25 in 31 lines of Python and explains each part with computed numbers. It then tests it against a real embedding model (BAAI/bge-small-en-v1.5) on a ten-document corpus and combines the two with reciprocal rank fusion. The formula and parameter guidance follow Robertson and Zaragoza's survey The Probabilistic Relevance Framework: BM25 and Beyond (2009). The benchmark evidence comes from BEIR (Thakur et al., 2021), and the fusion method from Cormack, Clarke and Büttcher (2009). For where retrieval fits in a RAG system, see Hybrid Search: Vector and Keyword.

Model APIs fail in ordinary ways: rate limits, overloaded capacity, server errors, dropped connections and calls that run longer than a timeout. Most of these are transient, so retrying is correct. But a retry policy that treats every error the same will hammer an API that is already overloaded, retry errors that can never succeed, and repeat text the user has already seen when a stream fails halfway through. This guide builds a retry policy for model APIs from the providers' own documentation and the SDKs' source code. It covers which errors to retry (including the 429s that look retryable but are not), what the official Python SDKs already do by default, why backoff needs jitter, how to honour retry-after, and how to set timeouts for long and streaming calls. The policy is a 74-line module for the Claude Python SDK. It was tested against a local stub server that returns scripted errors, and the results are in this guide. The facts are from the Claude API errors, rate-limit and streaming documentation, OpenAI's error-code guide, the source of anthropic 1.15 and openai 3.35, and Marc Brooker's Exponential Backoff and Jitter on the AWS Architecture Blog. For queueing work when you hit rate limits, see AI API Rate Limits and Queues.

A customer clicks Pay. Your server charges the card, and then the connection drops before the response reaches the browser. The client cannot tell whether the charge happened. If it gives up, a paid order may never be recorded; if it retries, the customer may be charged twice. Stripe's documentation puts the problem plainly: restoring connectivity doesn't tell you whether the original request succeeded. An idempotency key solves this. The client attaches a unique key to the request and reuses it on every retry. The server records the key with the outcome of the first attempt, and when the same key arrives again it returns that stored outcome instead of doing the work twice. Stripe has used this design for years, and an IETF draft proposes standardising it as the Idempotency-Key HTTP header. This guide implements idempotency keys end to end on PostgreSQL: the client contract, the table, claiming a key safely under concurrency, calling an external payment provider, recovering from a crash mid-request, replaying responses, and expiry. The 57-line implementation was tested against PostgreSQL 17 with concurrent clients and injected crashes, and the results are below. For the consumer-side version of the same idea in message queues, see Exactly-Once Delivery: Myth vs Reality.

A URL shortener turns https://example.com/a/very/long/path?campaign=autumn into something like sho.rt/6ZY3LCH, and sends anyone who opens the short link to the original. It is a classic system design exercise because the core is tiny, a key-value lookup, while the decisions around it are not: how to generate codes that never clash, which redirect status to return, how to keep redirects fast at thousands of requests a second, and how to count clicks without slowing them down. This guide designs one from requirements to failure modes, with every estimate computed from stated assumptions by a short script you can rerun with your own numbers. The short-code logic is a 41-line Python implementation, tested including forced collisions. The redirect semantics come from RFC 9110, the HTTP specification. For the general method behind the estimates, see Capacity Planning for Beginners; for a one-page summary of the patterns used here, see the System Design Interview Cheatsheet.

PostgreSQL never overwrites a row in place. An UPDATE writes a new version of the row and marks the old one as replaced; a DELETE only marks the row. That design, multiversion concurrency control (MVCC), is why readers never wait for writers: each query sees the versions that were current for its snapshot. The cost is garbage. Old versions stay in the table until something removes them, and that something is VACUUM. Most Postgres performance surprises trace back here: tables that grow without more data, queries that slow down over months, an autovacuum that "runs all the time", and, in the worst case, a database that stops accepting writes to avoid transaction ID wraparound. This guide explains the mechanism from the row header up, with output from experiments run on PostgreSQL 18.6, and checks every threshold against the PostgreSQL 18 documentation. For the isolation levels that MVCC implements, see ACID and Isolation Levels Explained.

Manual permission prompts protect you only while you read them. After the twentieth "Allow npm test?" in a refactoring session, most people approve on reflex, and the prompt stops doing its job. Auto mode is Claude Code's answer: a separate classifier model reviews each risky action in place of you, so routine work runs without prompts while actions such as curl | bash, force pushes, or production deploys are still stopped. Auto mode is not --dangerously-skip-permissions. That flag selects bypassPermissions, which skips the checks entirely. This guide covers how auto mode decides, what it blocks by default, how deny rules sit above every mode, and which mode to pick for CI. For the full CLI flag list, see Claude Code CLI Reference; for unattended loops built on these modes, see YOLO Mode vs Ralph Loops.

Every request Claude Code sends to the model carries the whole session so far: the system prompt, your CLAUDE.md files, every message, every file Claude read, and every command's output. That one fact explains why long sessions get slower, more expensive, and less precise, why a model switch costs a slow turn, and why /clear is the most underrated command. Anthropic's best-practices page calls the context window the most important resource to manage, because model performance degrades as it fills. This guide follows Anthropic's context-window, prompt-caching, and compaction documentation. It covers what loads before you type, what each action adds, how the prompt cache works and which actions invalidate it (including a common misconception about editing CLAUDE.md), what survives compaction, and how to steer it. For the cost side, see Claude Code Costs; for keeping large repositories in check, see Claude Code in Monorepos.

Organisations that run Claude through Amazon Bedrock, Google Cloud, or Microsoft Foundry, often for data-residency reasons, used to face a choice: give every developer cloud credentials, or build their own proxy and keep it compatible with every Claude Code release. The Claude apps gateway is Anthropic's answer. It is a self-hosted server built into the claude binary itself (claude gateway --config gateway.yaml), tested with each Claude Code release, that signs developers in with your corporate identity provider and forwards their requests to your provider. This guide follows the official gateway documentation: what the gateway gives you over a generic proxy, a minimal gateway.yaml, how developers sign in, per-group model access and managed settings, spend caps, failover, and the features that do not work through it. Every config example here is from Anthropic's docs; check the current configuration reference before production, because the gateway is still gaining options with each release. If you already run an LLM gateway that works, keep it; Claude Code LLM Gateway covers connecting Claude Code to one. For managed settings without a gateway, see Claude Code Enterprise Setup.

The Claude Code CLI has grown from claude plus a few convenience flags into a full control surface: interactive sessions, one-shot SDK-style calls, background agents, remote control, MCP servers, plugins, permission modes, worktrees, structured output, and diagnostics. A flat reference table is accurate, but it does not answer the question developers actually have: which command belongs in which workflow? This guide reorganizes the official CLI reference into a practical map, current as of July 2026. We will follow one running task, PAY-217: stop duplicate refund webhooks, and choose commands by job: start, automate, resume, isolate, authorize, extend, diagnose, and clean up. For the mechanics inside one turn, see How Claude Code Works; for long-running conversations, pair this with How to Manage Claude Code Sessions.

A team building an internal tool that reviews pull requests, runs the test suite, and posts a summary comment reaches for "Claude" and finds five different starting points: the raw Messages API, a beta tool_runner helper, the Claude Agent SDK, the Claude Code CLI itself, or a hosted product called Managed Agents. They all call the same models. None of the marketing copy makes it obvious which one saves you six weeks of infrastructure work and which one quietly limits what you can customize later. Anthropic's own developer docs actually draw this comparison directly — a table titled "Compare the Agent SDK to other Claude tools" — because the confusion is common enough to earn its own doc section. This article works through that comparison mechanistically rather than as a feature checklist: for each layer, what does Anthropic's code run for you, what do you still have to write yourself, and who owns the process the agent actually executes in. One example — an internal PR-review agent we'll call DiffBot, working against pull request #482 in a billing-service repository — runs through every layer, including one intentional failure (DiffBot tries to read a secrets file it shouldn't) and how each layer would catch or miss it. By the end you should be able to place a new project on this stack from one question: what am I refusing to build myself? Facts here describe the Messages API, Tool Runner, Agent SDK, Claude Code, and Managed Agents as documented as of July 2026 — Tool Runner and Managed Agents are both beta products Anthropic is still actively changing, so check current docs before locking in a specific method name, class, or capability.

Close a Claude Code session mid-task and the natural fear is that you just lost an afternoon of debugging context — the files it read, the failed approaches, the decision to skip the flaky test. That fear is usually wrong. A Claude Code session is a saved conversation tied to a project directory, written to disk continuously as you work, and the CLI gives you several distinct ways back into it: some that pick up exactly where you left off, some that deliberately start clean, and some that let you fork one conversation into two so you can try a risky idea without losing the safe path. This article is a practical reference for that lifecycle: how claude, --continue, and --resume differ, where the transcript actually lives on disk and what does and doesn't survive a resume, when /clear beats /compact beats a brand-new session, how to run more than one conversation against the same repository without them colliding, and how to structure a task that spans several days without re-explaining it each morning. We'll follow one running task through all of it — BILL-451: migrate invoice PDF generation to the new template engine in a billing-service repository — a job realistically too big for one sitting. Facts here describe Claude Code's documented CLI behavior as of July 2026; flag names and defaults can change between releases, so check claude --help or the current docs before scripting around them.

Open a chat with an LLM and ask it to fix a bug, and the best you get back is a suggested diff you copy into your editor by hand — the model never touched your repository, never ran your tests, and forgot the whole exchange the moment you closed the tab. Open Claude Code and give it the same instruction, and it reads the actual files, greps the actual repository, edits code in place, runs the actual test suite, and reports what changed — inside your real working directory, with real side effects. That gap is not a smarter model; the same model can sit behind either interface. It is a different piece of software wrapped around the model, commonly called a harness or agent loop, that gives the model eyes (tools that read), hands (tools that write and execute), and a way to keep going without a human retyping the next instruction after every reply. This article opens the harness up. We follow one running example — a ticket, PAY-217: refund webhook double-processes when Stripe retries, in a payments-api repository — through the mechanics that make Claude Code an agent rather than a chatbot: the read-plan-act-observe loop, the tool-call system that turns model output into filesystem and shell changes, how context grows and gets compacted as a session runs long, the permission gate that decides what the model is allowed to do without asking, and how subagents, MCP servers, and skills extend the same loop without changing how it fundamentally works. Facts here describe Claude Code's documented architecture as of July 2026 — check current release notes before relying on exact tool names or defaults in production.

Every few months a new system gets called a "world model" — Genie generating playable game worlds from a single image, Sora producing minutes of physically plausible video, Meta's V-JEPA learning from raw video without labels, robotics labs training arms entirely inside a learned simulation. It is tempting to treat "world model" as a rebrand of "big generative model," but the term names a specific, older idea from control theory and reinforcement learning: a model that predicts what happens to an environment's state if you take a specific action — not what word comes next in a sentence. That distinction is not academic. It determines whether a system can be used to plan, and it explains why a model that produces gorgeous video can still fail badly the moment you ask it to support a real decision. This guide assumes you understand next-token prediction in a transformer — see Transformer Architecture and Self-Attention Explained if you need that first — and treats language models as the point of contrast, not the subject. You will learn the encoder–predictor(–decoder) shape every world model shares, the real architectural split between predicting raw pixels and predicting compressed latent state (JEPA-style), how a world model is used to plan an action before taking it, and the specific failure mode — compounding rollout error — that makes "trust the model's imagined future" a genuinely risky sentence in robotics and autonomous systems.

Tell an agent to book a one-way flight from Seattle to Austin and the airline has no public booking API — the only way in is the same website a human customer would use, built for a mouse, a keyboard, and eyes that can tell a Search flights button from a promotional banner next to it. A computer-use or browser agent takes that literally: it looks at a screenshot (or the page's DOM and accessibility tree), decides an action the way a person would — click here, type there, scroll down — and then has to translate that decision into an actual pixel coordinate or DOM element before anything happens on the real page. That translation step, called grounding, is where most of the interesting engineering, and most of the failures, live. This is a different agent modality from the code-writing agents covered in AI Coding Agents Compared and The Rise of Claude Code. Those operate through a sandboxed, machine-legible action space — file diffs, shell commands, test runs — that a human or a git revert can undo cleanly. A browser agent's action space is the GUI itself, and once it dispatches a real click or keystroke, the action already happened on the live page. This guide walks through the perceive-plan-ground-act loop that powers computer-use and browser agents, why round-tripping through screenshots makes them slower and more failure-prone than agents that call APIs directly, and what changes about safety when an agent holds your literal mouse and keyboard.

You have probably seen a claim shaped like this on a model card: "70B total parameters, but only 13B active per token." That is not marketing rounding — it describes a real architecture change inside the transformer. Instead of one dense feed-forward block that every token pushes through in full, the model holds many smaller feed-forward networks called experts, and a small router decides, token by token, which handful of them actually run. Most of the model's weights sit idle for any single token; they only matter in aggregate, across the whole stream of tokens the model ever processes. This guide assumes you already know how attention and dense feed-forward layers work — see Transformer Architecture and Self-Attention Explained if you need that first. Here we go one layer deeper: how a Mixture of Experts (MoE) layer replaces a single dense feed-forward block, how the router picks which experts run, why that trades total parameter count for compute cost instead of just cutting parameters the way quantization or distillation do, and the failure modes — expert imbalance, routing instability, and the communication cost of spreading experts across GPUs — that make MoE genuinely harder to operate than it looks on a slide.

Modern coding agents are no longer just chat boxes beside your editor. The useful power comes from controls around the loop: commands you can invoke, checkpoints you can roll back to, tool servers, reusable skills, distributable plugins, and repeatable fresh-context loops. This guide is for engineers already using a CLI or editor agent and wondering which extension belongs where. We will follow one notification-service bug fix through the six controls, then decide when each one is worth adding. For the broader agent anatomy, start with What Is Agentic AI?; for Claude-specific daily workflow, see Claude Code Workflow. Product examples are current as of July 2026, so verify host-specific commands, checkpoint behavior, and plugin packaging before rollout.

Every agentic coding session forces a trade-off: the more autonomy you give the agent, the faster it moves, and the harder it is to catch a mistake before it cascades. Two community strategies sit at opposite ends of this spectrum. YOLO mode removes the permission prompts, letting the agent read, write, and execute without pausing. Ralph keeps each agent run short and fresh: a loop restarts the agent for every task, so no run inherits the previous run's conversation. This article gives you a working model of both: their execution paths, how each one fails, and the criteria for choosing. We follow one scenario throughout, an orders-service whose event consumer occasionally drops events, and fix it twice. For permission architecture fundamentals, see Claude Code Sandboxing and Isolation. For the wider loop toolkit, see Slash Commands, Checkpoints, MCP, Skills, Plugins, Ralph Loops.

Running one AI coding agent on a task is easy. The moment you want three or thirty of them working at once — without two agents editing the same file, without losing track of who owns what, without the whole thing collapsing the instant a laptop sleeps — you need an orchestrator, and the three most-discussed ones in mid-2026 solve that problem in genuinely different ways. Gas Town treats agents like a fleet with git as the source of truth; Claude Agent Teams builds coordination directly into Claude Code as a lead-and-teammates session; GSD skips persistent agent identity entirely and instead engineers the context each spawned agent receives. This guide is for engineers who have already used a single Claude Code or agentic AI session and are deciding whether — and how — to scale to many agents at once. We follow one running task, fixing a double-charge bug in a checkout-service, through sub-agents, multi-agents, Gas Town, Claude Agent Teams, and GSD. Facts here are current as of July 2026; all three projects ship fast, so check each project's own docs before treating a specific command or flag as durable.

A product manager says PAY-204: next Friday's campaign may double checkout traffic for three hours. The beginner mistake is asking, "How many servers do we need?" before defining the request path, the peak arrival rate, the slowest shared dependency, and the amount of headroom the business is willing to pay for. This guide turns capacity planning into a repeatable design review. We will follow one checkout request through API servers, Postgres, Redis, a payment provider, and a queue; estimate load with simple math; identify the first bottleneck; prove the estimate with a small load test; and choose whether to optimize, scale out, or degrade gracefully. For background on the surrounding concepts, pair this with latency vs throughput and read-heavy vs write-heavy system design.

Timeline slides about Claude Code usually stack five gold dates and call it a rise. Dates are useful only when you ask what capability boundary moved at each mark: from a private Labs prototype, to a repo-native CLI agent, to a programmable harness (hooks, skills, subagents), to a model that can run longer agent loops, to a desktop surface that is no longer only for coding. This guide rebuilds that arc as mechanisms, current as of July 2026. It corrects a few slide habits: Claude Code was not the first CLI coding assistant; general availability landed with the Claude 4 wave on 22 May 2025, not a vague “April first”; and OpenClaw is an adjacent personal-agent control plane, not a Claude Code feature. For day-to-day harness setup see Claude Code Workflow; for product boundaries see AI Coding Agents Compared. Running example: ticket ORD-142 — checkout-api resets after 30 seconds — carried through each stage so you can see what the agent could (and could not) touch.

An issue says ORD-142: checkout-api resets after 30 seconds. Every AI coding product claims it can fix the bug, run tests, and open a pull request. The useful question is not which logo is smartest. It is where the agent runs, what it can touch, who approves actions, and where state survives when the task outlives one chat. Start with the attachment map in AI Coding Surfaces: IDE, Plugin, and CLI; Context Engineering explains the finite-window discipline inside each run. This guide compares Claude Code, GitHub Copilot, OpenAI Codex, Cursor, OpenCode, and Google Antigravity on those boundaries. It also corrects a common category mistake: MCP is a tool protocol, while OpenClaw is a self-hosted personal-agent control plane. Neither is a peer coding agent. The comparison reflects public product surfaces as of July 2026; re-check pricing, preview status, enterprise controls, and hosted-agent behavior before rollout. By the end, you can choose a surface for ORD-142, connect only the tools it needs, and define a test that exposes a bad choice.

An order database's primary data center suffers a catastrophic, unrecoverable event — not a transient node failure, an actual disaster. Two numbers now determine how bad this gets: how much data is permanently lost, and how long the service stays down. Teams often treat those as one "disaster recovery" number. They're not — they're answers to two entirely different questions, measured on opposite sides of the moment the disaster happened. This guide defines RPO and RTO precisely, maps the standard DR strategy tiers to the RPO/RTO numbers each one actually achieves, derives targets from real business impact instead of a template, and traces an incident where a well-tested DR plan protected against exactly the wrong failure class — leaving a much larger data-loss window than the advertised RPO ever promised.

A product-page personalization API needs to answer in under 100ms for a good user experience. A shopper in Sydney hits it, and the request has to reach the origin server in Virginia and come back — a round trip that, even at the physical speed limit of light in fiber, cannot finish in under roughly 160 milliseconds. No amount of server-side optimization fixes that number; the origin server could respond in zero milliseconds and the request would still be too slow, because the distance itself is the bottleneck. This guide follows that personalization request. We will calculate why distance imposes a hard latency floor no engineering removes, apply the edge compute patterns that actually address it — caching, edge functions, and data replication — weigh what moving data to the edge costs, trace a real incident where edge replication quietly violated a data-residency requirement, and decide what should and shouldn't run at the edge.

A multi-tenant analytics platform partitions incoming events by tenant_id, hashed onto 16 shards — a design that looked perfectly balanced in every load test. Then one customer runs a marketing campaign, their event volume jumps 40x overnight, and the one shard that happens to own their tenant_id pegs at 100% CPU while the other fifteen sit nearly idle. Two other, unrelated tenants who happen to share that same physical shard suddenly see their own write latency degrade too — collateral damage from a neighbor they've never heard of. This guide follows that shard. We will define what actually makes a partition "hot," trace the common ways a key distribution turns lopsided, build the monitoring that catches it before customers do, apply concrete mitigation techniques, and trace the noisy-neighbor incident above through trigger, evidence, and prevention.

A URL shortener's redirect endpoint, GET /r/{code}, looks purely read-heavy — billions of redirects against a handful of short codes created per second. But every single redirect also writes a click-analytics event, so the same request that reads a mapping also generates a write. Judged by the product surface, the system is read-heavy. Judged by actual operation counts, its analytics table may be one of the highest-write-throughput tables in the whole company. This guide follows that one redirect request end to end. We will define read-heavy and write-heavy by measured ratio, not intuition, apply the different design patterns each one needs to the read side (resolving the short code) and the write side (recording the click) of the exact same request, trace an incident where a read-optimizing index was added to the wrong side and quietly broke redirects, and decide where read and write concerns need to be physically separated.

An order service runs in two regions, us-east and eu-west. In one design, both regions serve live customer traffic right now, splitting the load. In another, us-east serves everything while eu-west sits ready, replicating data, doing no real work until it's promoted. Both are "redundant" in the sense that the service survives a regional outage — but they cost differently, fail differently, and recover differently. This guide follows that same order service through both shapes. We will define what actually separates active-active from active-passive, build the mechanisms each one needs, compare their RTO/RPO trade-offs, trace a real failover where the standby's database schema had quietly drifted from the primary's, and decide which shape a given workload actually needs.

A permission check in front of a wire-transfer approval endpoint times out. What should happen next? One engineer's instinct says "don't block the transfer over an infrastructure blip — default to allow and log it." That instinct is exactly right for a recommendation feed and exactly wrong here — defaulting to allow on a security gate means the one time the permission check can't run is the one time anything gets approved. This guide follows that wire-transfer approval gate. We will separate two ideas people conflate under "fail-fast vs fail-safe" — when a system should stop versus what state it should stop into — build the mechanisms for each, trace a real incident where a generic "fail open for availability" pattern was wrongly applied to a security check, and decide which default a given failure mode actually needs.

A payment service keeps processing requests with zero dropped transactions while one of its three nodes crashes mid-request — that's fault tolerance. A different payment service goes fully offline for four seconds during a failover, then resumes serving traffic — that's high availability, and it is a real, useful property, even though a request landed in that four-second gap and failed. Teams use these two terms interchangeably and then get surprised when a "highly available" system still drops requests during failover. This guide follows one payment service through both properties. We will define what each one actually promises, build the mechanisms that provide each, show where a system can have one without the other, trace an outage where a genuinely available system still violated an implicit fault-tolerance assumption, and decide which one a given operation actually needs.

A product page shows the item, its price, and an "add to cart" button — the core path — plus a "customers also viewed" recommendation strip powered by a separate service. When the recommendation service goes down, the whole page returning a 500 error is a choice, not a fact: nothing about a broken recommendation feed should stop a customer from buying the product directly below it. This guide follows that product page. We will define the core path explicitly, build fallbacks for the parts that aren't core, add a feature-flag kill switch as a second, human-operated lever alongside automatic fallbacks, trace a real incident where the "safe" fallback path had its own unhandled failure mode, and decide what actually deserves this treatment.

A checkout API runs three replicas across two availability zones behind a load balancer — on paper, no single point of failure. Then one AZ has a networking incident, and checkout fails everywhere, including the replica in the healthy zone, because every replica's outbound call to the payment provider routes through one NAT gateway that happens to live in the AZ that just went down. The API tier was redundant. The system was not. This guide follows that same checkout path. We will define what actually counts as a single point of failure (SPOF), find the ones hiding outside the obvious app tier, check whether a given redundancy setup actually removes one, separate independent failures from correlated ones, trace the shared-NAT outage in detail, and prioritize which SPOFs are worth removing first.

An order-ingestion API writes to an in-memory queue, a worker pool drains it, and a payment provider on the other end gets slow. The queue keeps accepting every request because nothing tells the API to stop — so it grows until the process runs out of memory and crashes, taking every queued order with it. A slow consumer did not cause this outage; an unbounded buffer that hid the slowdown did. The broader synchronous vs asynchronous processing choice determines where that queued work enters the design. This guide follows that same pipeline — API → queue → worker pool → payment provider. We will define what backpressure actually signals, compare the mechanisms that carry that signal (TCP windows, bounded queues, HTTP 429), separate backpressure from load shedding, propagate the signal across every hop instead of just one, trace the OOM failure an unbounded queue causes, and decide where to bound each part of a pipeline. At an HTTP boundary, pair the signal with an appropriate rate-limiting algorithm instead of treating every overload as the same event.

A shopping cart write to cart-77 needs to land on enough replicas that a later read is guaranteed to see it — but "enough" is a number you choose, and the number you choose changes what fails and what stays fast when a node goes down. Quorum systems make that trade-off explicit instead of hiding it inside a database default. This guide follows cart-77 across a 3-replica Dynamo-style store (nodes A, B, C). We will define N, W, and R precisely, tune them for different failure tolerance, fall back to a sloppy quorum when the preferred replicas are unreachable, repair a stale replica after a divergent read, lose a hinted write during a careless deploy, and separate this whole mechanism from the very different thing Raft/Paxos calls a quorum. The partition trade-off sits inside the wider CAP theorem model.

A 4-node session cache scales to 5 nodes to handle more traffic. With hash(key) % N, that single node addition changes almost every key's target node, and the cache that was supposed to absorb load instead misses on nearly everything at once. The fix is not a bigger cluster — it is a different mapping from key to node. Start with Caching 101 if cache layers, hits, and misses are still unfamiliar. This guide follows session keys user-1001 through user-1004 across a cache cluster. We will see exactly why modular hashing remaps almost everything on resize, place both keys and nodes on a hash ring so only a fraction of keys move, add virtual nodes to fix the ring's uneven load, trace a real scale-out that stayed lopsided anyway, and decide when the extra mechanism is worth building. Ring balance does not cure popular keys; hot-partition mitigation covers that separate failure mode.

A user changes their display name, refreshes the page a second later from a phone on a different network, and sees the old name. Nothing crashed. No request failed. The system is working exactly as designed — the design just did not promise that the second read would see the first write. This guide follows PUT /users/u-42/profile replicated across three regions. We will define what strong consistency (linearizability) and eventual consistency actually guarantee, replicate the write both ways, lose an update to a race the eventually consistent path allows, and choose the model from the read-after-write requirement instead of a vague preference for “strong.”

A checkout API can wait until every step finishes, or accept an order and complete work later. The first path gives the caller an immediate final answer but couples its latency and availability to every dependency. The second absorbs slow work behind a queue, but “accepted” no longer means “completed”—the system must expose status, retries, duplicates, and terminal failure. This guide follows POST /orders with idempotency key ord-42. Success means inventory is reserved once, payment is authorized once, and the customer can discover the final result. We will run the order through both paths, crash a worker after charging but before acknowledging its message, and choose boundaries from the user's timing and consistency requirements. See event-driven architecture patterns for the wider design and Kafka vs RabbitMQ vs SQS for broker trade-offs.

A shopping cart must remember items, so the product cannot be literally stateless. The useful design question is where that state lives. Keep the cart inside one web server and the load balancer must keep finding that server. Move it to a shared store and any web server can handle the next request—but the shared store becomes a consistency and availability dependency. This guide follows cart cart-42: a user adds an item, the application instance fails, and the next request lands on another instance. We will separate stateless protocol behavior from application state, trace both architectures, reproduce a sticky-session data-loss failure, and choose state placement from identity, consistency, latency, and recovery requirements. The horizontal vs vertical scaling guide covers replica capacity, while caching strategies explains the shared state and cache layer.

An order API can return responses all day and still charge the wrong amount. It can be temporarily unreachable while every stored order remains safe. It can fail over instantly and lose the order it just acknowledged. Calling all three outcomes “reliability” hides the design decision you actually need to make. This guide follows POST /orders with idempotency key ord-58. Success means the API accepts the request, computes the right order once, and retains that acknowledged order through a primary-node failure. We will separate availability, reliability, and durability, measure each with a different indicator, intentionally lose an acknowledged write, and design the recovery boundary. Continue with logs, metrics, and traces for evidence collection and strong vs eventual consistency for replicated-data guarantees.

A dashboard can look “fast” while users still wait, and a load test can report huge requests-per-second while p99 checkout times explode. Latency is how long one request takes. Throughput is how many requests the system completes per unit time. They are related, but they answer different questions—and optimizing one can quietly destroy the other. This guide is for engineers designing or debugging APIs under load. We follow one service—checkout-api handling POST /checkout—measure both metrics correctly, use Little's Law to couple them, watch a real saturation failure, and leave with a decision rule: set the latency budget first, then maximize sustainable throughput inside that budget. The URL request-path guide identifies where end-to-end time is spent; the horizontal vs vertical scaling guide explains the capacity choices once a bottleneck is measured.

You press Enter on https://shop.example/products/42. A moment later, a product page appears. That small action crosses naming, transport security, HTTP, edge infrastructure, application code, data storage, and the browser renderer. If the page is slow or wrong, “the website is down” is not a diagnosis—you need to identify the stage that failed. This guide is for web developers who know HTTP requests but have not followed a navigation end to end. We will keep one URL for the whole journey, expect an HTTP 200 product page, intentionally route it to an old origin through stale DNS, and use browser and command-line evidence to recover. Use the latency vs throughput guide to measure the path under load and the caching strategies guide to go deeper on browser, CDN, and application caches. The core model is name → connect → request → compute → render → measure.

A support ticket that needs docs, a tool call, and a model reply does not need twelve equal "frameworks." It needs an orchestration lane, a retrieval lane, a serving lane, and a place to store embeddings. Popular roundups flatten those jobs into one grid and call FAISS, Ollama, and XGBoost the same kind of thing. This guide is for engineers choosing a stack for a production AI feature. You will map twelve widely used tools into six lanes, follow one support request through the path, see short code for the hot spots, and leave with a decision rule—including when not to adopt another framework. Product surfaces reflect July 2026 defaults; re-check official docs before a bake-off. For RAG variants see Classic vs Graph vs Agentic RAG; for vector stores see Vector database map.

A travel checkout may call a public weather API, your own booking API, and a partner airline API. All three could use REST, but they should not share the same credentials, rate limits, or change policy. Choosing the audience boundary first makes the system easier to secure and evolve. This guide separates who may call (Open, Internal, Partner) from how calls are shaped (REST, GraphQL, SOAP, gRPC). You will follow that travel request, see short code examples, and choose controls for each lane. For style depth, see REST vs GraphQL vs gRPC.

AI agents rarely work alone. They read files, query databases, call business APIs, and sometimes delegate work to other agents. Without shared contracts, every connection becomes a custom integration with its own discovery, authentication, message format, and failure behavior. Review What Is Agentic AI? first if orchestrators, tools, and specialist agents are new concepts. Four names appear often: MCP for tool and resource access, A2A for remote-agent tasks, SLIM for secure message transport, and ACP for older BeeAI agent integrations now moving toward A2A. They solve different problems rather than competing for one job. Protocol surfaces and migration status are current as of July 2026; verify the linked specifications before implementation. This guide follows one support incident through all four boundaries and shows when a plain function is still the better choice; Communication Protocols Between Services covers service-to-service protocols more broadly.

Checkout slows while product pages remain healthy. CPU is moderate, but the orders table shows rising lock waits and writes queue behind one hot index. Adding a read replica would not fix that incident because the bottleneck is on the write path. This guide separates read load, write or storage limits, large-table scans, and repeated hot reads, then maps them to replicas, sharding, partitioning, or caching. User count and company size do not choose the technique; measurements on one representative request do. For machine-level scale-up versus scale-out, see Horizontal vs Vertical Scaling.

A prompt is only one part of a production AI system. Engineers also need vocabulary for execution loops, tool connections, model access, cost, evaluation, safety, and diagnosis. A gateway cannot repair a weak eval set, and MCP cannot decide whether a task should be agentic. For engineers moving an LLM feature beyond a demo, this map places nine controls around one bug-triage flow. You will be able to locate a failure, run a bounded tool loop, and decide which production control to add next; use What Is Agentic AI? and MCP vs A2A vs ACP for focused depth. Product and protocol examples are current as of July 2026; implementations and defaults may change.

This guide is for developers who can build a frontend, API, and database but have not yet operated the whole request path. By the end, you can trace one checkout from browser to durable state, locate its trust boundaries, and carry a realistic timeout incident through detection and recovery. The thirteen layers are grouped by the questions a shipped app must answer, not presented as a mandatory product list. Use Observability: Logs, Metrics, Traces and CI/CD with GitHub Actions for operating depth, and the linked satellite guides for database, auth, caching, and deployment rather than trying to implement every layer from this map.

HTTPS and a valid JWT only prove the front door locked. Many real API incidents happen after authentication succeeds: a user changes /orders/42 to /orders/99 and reads someone else's data; an internal URL fetch hits cloud metadata; a long-lived signing key never rotates. This guide is the production security layers article — identity and authorization, exposure, secrets and input, traffic control, third-party/egress hardening, and visibility. For how credentials travel on the wire, see REST authentication methods. For sessions vs JWT vs OAuth, see JWT vs Session vs OAuth. For limiter algorithms and 429 contracts, see rate limiting.

Many .NET teams stop at "add [Authorize] and check roles." That covers two of seven authorization models ASP.NET Core ships with — and leaves you reaching for hacks when requirements get nuanced. Authentication answers who the user is. Authorization answers what they can do. ASP.NET Core separates these cleanly: authentication middleware builds a ClaimsPrincipal; authorization runs afterward via policies, handlers, and filters. ASP.NET Core actually ships seven authorization types — simple, role-based, policy-based, claims-based, custom requirements, endpoint-specific, and resource-specific — each solving a different shape of what a user can do, with when to use each and minimal C# you can drop into a project. For token validation at the API boundary, continue with the JWT security deep dive. For dependency boundaries around authorization code, see Clean Architecture in .NET.

A chatbot answers one prompt at a time. An agentic AI system accepts a goal, selects actions, calls tools, observes results, and loops until it reaches a terminal state. From LLM to Agentic AI shows where that loop sits on the broader capability ladder. For application engineers who can read TypeScript but have not built an agent runtime, this guide maps the orchestrator, state, tools, and optional specialists. You will leave with a runnable bounded loop and a test for telling agentic design from a thin model wrapper. Framework and protocol examples are current as of July 2026; APIs and defaults may change.

Job posts and LinkedIn profiles make every engineer sound like a "Senior" with "10+ years building scalable systems." In reality, the software industry runs on internal levels most candidates never see — Google's L3–L8, Amazon's SDE I–Principal, Microsoft's 59–80 band, or a startup's flat Junior / Mid / Senior trio with no Staff title at all. What actually changes between levels isn't buzzwords. It's scope: a junior engineer ships tickets someone else scoped; a senior engineer reframes the problem before the sprint starts; a staff engineer changes how three teams build without managing any of them. This guide is written for what really happens in industry — the three career tracks companies use, a six-level growth pyramid with clear signals, what each level looks like on a typical week, where most engineers plateau, and how promotions actually get decided in calibration. For a specialist quality track, compare the QA engineer career levels. For concrete architecture judgment expected at higher levels, study monoliths, modular monoliths, and microservices.

SOLID is five design heuristics for object-oriented code that must change safely. Robert Martin popularized the acronym; the ideas are older than the name. They are not laws of physics — they are vocabulary for recognizing when a class has too many reasons to change, when extension requires editing tested code, or when a subtype silently breaks a contract. This guide treats SOLID as a knowledge map: each letter is a precise claim, a common violation, and a C# fix you would see in a backend API. We also place SOLID on top of OOP pillars and under Clean Architecture layers — because principles without a place in the dependency graph become slogans. Benefits like “easy testing” and “low coupling” are consequences, not a sixth principle. See how these dependency rules scale into Clean Architecture in .NET. For a broader toolbox around service boundaries, compare the microservices design patterns.

Manual deployments are one of the highest-risk activities in software engineering. A developer SSHes into a production server, runs commands from memory, makes a mistake, and causes an outage at 5pm on a Friday. Continuous Integration and Continuous Deployment (CI/CD) automates the path from a Git commit to a running system — running tests, building containers, and deploying to production without manual intervention. Git Branching Strategy explains how branch shape affects that pipeline. This article covers GitHub Actions workflow patterns valid as of July 2026: workflow anatomy, build and test, container publishing, deployment strategies, and secrets. Action releases and runner images move; verify current action inputs and pin reviewed production dependencies before copying these teaching examples. Place the workflow in the wider operating path with What Full Stack Really Means.

A codebase full of any and as uses TypeScript as punctuation, not evidence. The useful patterns are the ones that preserve information through transformations and force uncertain runtime data through a real check. For JavaScript developers comfortable with interfaces and unions, this article orders five advanced tools from derivation to runtime narrowing. You will be able to remove duplicated types, preserve generic results, and recover safely when an API payload has the wrong shape. Apply these type-safety techniques when designing contracts with the REST API best-practices guide. For architecture context around TypeScript services, compare monoliths and microservices.

A well-designed REST API is a contract. Clients depend on its URLs, error shape, and pagination for years; an accidental breaking change can turn a routine release into a client outage. For backend developers publishing or reviewing an HTTP API, this article gives you conventions for resources, status codes, pagination, versioning, idempotency, and errors. You will finish with a small contract test that can catch drift before deployment. Choose the surrounding interaction style with the service communication protocol map. Protect bearer-token endpoints using the validation rules in the JWT security deep dive.

A product page is easy to cache until a price changes: the CDN still has the old response, one app instance has an older in-process value, and Redis has already been refreshed. The page is fast, but checkout rejects what the customer just saw. That failure is a cache-strategy problem, not a reason to avoid caching. This guide focuses on patterns: cache-aside, read-through, write-through, CDN caching, invalidation, and coordination across cache levels. Use Caching 101 for layers and eviction, and Why Is Redis So Fast? for Redis internals.

Most .NET projects start clean and become entangled within six months. Controllers call repositories that call other services that reach back into controllers. Business logic lives in HTTP action methods. Tests require spinning up a database. A new developer can't tell where to put new code without reading existing code first. Clean Architecture — popularized by Robert Martin and refined by the .NET community — is a set of structural rules that prevent this entanglement. The central rule is simple: dependencies only point inward. Domain code knows nothing about databases, HTTP, or infrastructure. Infrastructure knows everything about domain, but not the other way around. Each layer gets a before/after in real .NET code, along with how CQRS with MediatR fits naturally into the structure. The dependency direction becomes easier to enforce with the SOLID principles in .NET. For request-level access decisions at the API edge, review ASP.NET Core authorization types.

Docker and Kubernetes are not competitors on the same layer, and treating them as an either/or is the mistake that leads teams to run a cluster they cannot operate. Docker builds an image and runs a container on one host. Kubernetes takes that same container and keeps a declared number of copies alive across many hosts, reconciling networking and rollout state as machines and Pods come and go. This guide is for engineers who can already run docker run and now have to decide what production looks like. We follow one service — a checkout-api exposing GET /health — first as a single Docker container, then as a Kubernetes Deployment. You will trace how a request actually reaches it, watch one real crash loop and recover from it, see where the security and scaling boundaries move, and leave with a decision rule that is not based on service-count folklore. For the cluster internals in more detail see Kubernetes Request Flow; for persistence see Docker Volumes Explained.

A partner script scrapes your API with a leaked key. A mobile build ships a password in every header. A "Sign in with GitHub" button works until someone treats the access token as proof of who the user is. Authentication is not one checkbox — it is matching a credential type to a caller and a threat model. This article is the REST wire-format guide: API keys, Basic Auth, Bearer tokens, JWTs, OAuth 2.0, OpenID Connect, HMAC signatures, and mutual TLS — how each request proves something and where it fails. For when to prefer sessions vs JWTs vs OAuth as models, see JWT vs Session vs OAuth. For JWT claim validation, see JWT deep dive. For IDOR and rate limits after auth, see API security.

This guide is for backend engineers who know HTTP and database transactions but need to decide where six microservice patterns fit. By the end, you can trace one checkout, configure representative boundaries, and recover duplicate delivery, timeout, stale read, and compensation failures. The running example is checkout across mobile/web, Order, Payment, Inventory, and Email. For load balancers, brokers, and Kubernetes as one deployment path, use the Microservices Architecture Blueprint instead of turning this pattern guide into an infrastructure catalog. Choose synchronous and asynchronous boundaries with the service communication protocol map. For saga, outbox, and choreography mechanics, continue with event-driven architecture patterns.

Artificial intelligence is not here to replace .NET developers. It is here to extend what they can build. The fundamentals you already know — services, APIs, data access, validation — still matter. What changes is how you compose them. What Is Agentic AI? defines the bounded runtime behind the agent examples. Instead of shipping systems that only move data, you design systems that understand context, reason over it, and take action. Twelve practical shifts turn a traditional .NET codebase into a production-ready AI system. Framework and product examples are current as of July 2026; APIs and defaults may change. For tool and remote-agent boundaries, use MCP vs A2A vs ACP.

A trip booking needs a flight, a hotel room, and a card charge to either all succeed or all unwind — but each lives in a different service with its own database. Wrap them in one ACID transaction and you need every database to agree on commit at the same instant. Let each service commit independently and a card charge can succeed after the hotel booking fails, leaving a customer charged with nowhere to sleep. Two-Phase Commit (2PC) answers this with a coordinator that locks every participant until all agree to commit. The Saga pattern answers it by running each step as its own local transaction and undoing completed steps with compensating actions if a later step fails. This guide follows one trip booking through both mechanisms, compares choreography and orchestration as two ways to run a saga, and traces a real mid-booking failure to its recovery. For the broker mechanics behind an async saga, see Kafka vs RabbitMQ vs SQS and Event-Driven Architecture.

A signup service inserts a new User row, then calls the broker to publish UserRegistered so the welcome-email and loyalty services can react. The database commit and the broker publish are two separate network calls to two separate systems — nothing makes them succeed or fail together. Commit the row, then crash before the publish call, and the user exists with no welcome email, no loyalty account, and no record that anything went wrong. The transactional outbox pattern fixes this by writing the event as a row in the same local database transaction as the business change, then using a separate relay to deliver it to the broker. This guide follows one signup through the dual-write failure, the outbox table and relay that close it, and a relay crash that tests whether your consumers are actually idempotent. For the broker choice behind the relay, see Kafka vs RabbitMQ vs SQS; for the wider event-driven picture, see Event-Driven Architecture.

A developer opens the console, sees a red "blocked by CORS policy" error on a fetch call, and assumes the request never reached the server. It often already did — the like counter it was supposed to increment shows one higher than before, even though the browser never let the page read the response. CORS is enforced by the browser, on the response, and for a wide category of requests that check happens only after the server has already done the work. This guide separates the same-origin policy the browser enforces by default from the CORS headers a server uses to opt back into cross-origin reads, follows one dashboard widget calling a different API origin through both a simple request and a preflighted one, and traces a real failure where a blocked response didn't mean a blocked side effect. For the authentication headers involved when credentials cross an origin, see REST API Authentication Methods.

A mobile app adds "Sign in with Provider," gets back a token, and calls it a login. OAuth 2.0 was never built to answer "who is this user" — it was built to answer "can this app access that API on the user's behalf, without ever seeing the user's password." Treating an OAuth access token as proof of identity is the single most common OAuth mistake, and it has a name for the fix: OpenID Connect (OIDC), a thin identity layer built on top of OAuth 2.0. This guide separates what OAuth 2.0 actually delegates from what OIDC adds, follows one login through the Authorization Code flow with PKCE, and traces a real authorization-code interception to see exactly what PKCE was built to stop. For where the resulting tokens get validated on the API side, see JWT Deep Dive; for the broader session/token/OAuth model comparison, see Sessions, JWTs, and OAuth/OIDC.

Two support agents both open the same account balance, both see $100, both independently process a $50 withdrawal, and the balance ends up at $50 instead of $0 — one withdrawal simply vanished. The database never crashed, no constraint was violated, and every individual statement succeeded. The bug is a lost update, and it happens at the isolation level of ACID — the property responsible for what one transaction is allowed to see of another's concurrent work. This guide defines each ACID letter precisely (including the one most often confused with an unrelated CAP-theorem concept of the same name), maps the specific anomalies Read Committed, Repeatable Read, and Serializable each allow or prevent, and explains the MVCC mechanism that lets Postgres avoid blocking readers on writers at all. Then it traces the lost-update bug above to its actual fix. For how these guarantees change once data is sharded or replicated, see Strong vs Eventual Consistency.

A product page's cache key expires at 2:00:00pm. In the same instant, 5,000 concurrent requests check the cache, all get a miss, and all 5,000 independently query the database for the identical row — a cache meant to protect the database from load instead multiplies that load by 5,000x, in the same second the database is least prepared for it. This is a cache stampede (also called a thundering herd, or the dogpile effect), and it's one of the few caching bugs that actively gets worse the more effective your cache normally is, because a highly effective cache means the database has forgotten how to handle that query's real traffic. This guide names exactly what triggers a stampede, then covers the four real mitigations in order of how much they change your system's behavior: mutex-locked recomputation, probabilistic early expiration, and stale-while-revalidate — tracing one stampede that took down a database to see which combination actually would have stopped it. For cache layers and eviction policy generally, see Caching 101; for invalidation patterns, see Caching Strategies.