Long-form guides for Claude Code
Practitioner deep-dives on setup, discipline, investigation, workflow, and cost. 4,000–5,000 words each; written by engineers doing the work; updated as tools evolve. Discipline pieces, not tutorials.
Latest
Most recently published guide.
The Secrets Management Guide
Secrets management that keeps you boring + auditable + not-in-the-headlines. Vault selection framework; secret typology; injection patterns; rotation discipline per secret class; automated rotation; overlap windows; dev vs. prod separation; break-glass procedures; secret scanning; log redaction; K8s-native patterns; incident response; offboarding; shared credential migration; audit + observability; compliance.
All guides
Filter by category or author. Search across titles and summaries.
The Redis + Distributed Caching Guide
Redis discipline that survives topology changes, migrations, and scale. When Redis vs. Memcached; topology selection (standalone/Sentinel/Cluster/managed); persistence (RDB/AOF); memory + eviction; keyspace design + TTL discipline; data structure selection; Cluster mode + hash tags; multi-key operations + Lua constraints; latency debugging; failure patterns; use-case separation (cache/session/queue/pub-sub); K8s patterns; cost calculus; upgrades; client libraries; migration; observability.
The Payment Integration Guide
Payment infrastructure that survives edge cases + processor changes + growth. Platform selection (Stripe/Adyen/Braintree/Square/orchestrators); PCI compliance scope; minimizing scope via hosted forms; webhook signature + idempotency; subscription state machine; trial + dunning + cancellation + proration; refunds; disputes + chargebacks; multi-currency; tax; invoicing; fraud; reconciliation; observability; marketplace patterns; migration.
The Real-Time Messaging Discipline Guide
Real-time architecture that survives storms + scale + change. Protocol selection (WebSocket/SSE/long-polling/WebTransport/MQTT); platform/library (Socket.IO, Phoenix Channels, managed Pusher/Ably); connection scaling (sticky vs pub-sub broker); presence; message ordering; reconnection strategy + budget; back-pressure; auth check caching; cross-region; fallback; observability; load testing; migration.
The Feature Flag Discipline Guide
Feature flags as liability, not asset. Flag typology (release, experiment, ops, permission, circuit breaker); platform selection (LaunchDarkly, Statsig, PostHog, Unleash, Flagsmith); naming + ownership + TTL; automated stale detection; removal PR pattern; experimentation design (MDE, sample size, SRM, guardrails, sequential vs fixed-horizon); rollout patterns; client vs server; fail-safe defaults; sunset in definition of done; migration; metrics.
The API Gateway + Rate Limiting Guide
API gateway as policy plane, not proxy. Platform selection (Kong, Envoy Gateway, AWS API Gateway, Cloudflare Workers, Apigee, Tyk, Krakend); rate limiting algorithms with math; scope + layered defense; capacity-based limit derivation; shadow-mode rollout; auth boundary; fail-open vs fail-closed; response headers; partner tier design; observability; failure patterns; migration; GraphQL differences; metrics.
The Authentication + Authorization Guide
Auth systems that evolve from 100 to 1M users. Authentication flows (session vs. JWT, OAuth2/OIDC, SAML, MFA, passkeys); authorization models (RBAC, ABAC, ReBAC, policy engines); multi-tenancy design; token lifecycle; vendor comparison (Auth0, Clerk, WorkOS, Ory, Keycloak, Cognito); failure patterns (IDOR, tenant confusion, stale permissions); recovery flows; session security; audit + logging; metrics.
The Background Jobs Discipline Guide
Background job systems that survive from 1k/hr to 1M/hr without rewrite. Platform selection (Sidekiq, Celery, BullMQ, Faktory, SQS+Lambda, Cloud Tasks, Temporal); at-least-once + idempotent as practical exactly-once; retry design that survives downstream outages; per-partner concurrency limits; DB-aware worker cooperation; DLQ discipline; observability; testing; migration patterns; metrics.
The Incident Response Discipline Guide
Incident response as three-part discipline: response (getting through it), learning (what changes after), prevention (compounding fewer future incidents). Severity classification; on-call model; incident commander role; response playbook; communication discipline; mitigation before diagnosis; runbook culture; blameless post-mortem practice; designated author; cross-team publishing; quarterly meta-review; action item tracking; game days + chaos engineering; on-call sustainability; metrics.
The Caching Discipline Guide
Caching as discipline: invalidation-first design (not tool-first). When to cache; cache-tier framework (browser through DB); invalidation strategy selection (write-through, cache-aside, TTL, event-driven, versioned); TTL policy per data class; stampede + thundering herd prevention; cache warming vs. lazy fill; cross-tier coherence; observability (hit rates, freshness, cost); failure patterns; migration from uncached; metrics.
The Observability Discipline Guide
Observability as discipline: unified traces + metrics + logs. OpenTelemetry as strategic choice; instrumentation coverage strategy; sampling strategies (head, tail, adaptive); semantic conventions + cardinality budget; backend selection (LGTM, Honeycomb, Datadog, New Relic); retention tiers + cost management; SLO-based alerting philosophy; runbook integration; trace context propagation; cost management levers; migration patterns; log-trace correlation; RUM as complement.
The Event-Driven Architecture Guide
Event-driven as discipline, not just pattern. When to use (and when not); platform selection framework (Kafka, EventBridge, RabbitMQ, NATS, SNS+SQS, Redis Streams); event schema design; ordering guarantees; delivery semantics + idempotency; saga patterns (orchestration vs. choreography); outbox pattern for transactional consistency; DLQ design + monitoring; replay strategies; correlation + causation IDs; failure patterns to prevent; testing; migration from request-response; metrics that matter.
The Design System Guide
Design system as team contract, not library. Token architecture (semantic on primitives); canonical component library; API stability discipline for shared components; governance structure; structured consumer feedback process; automated enforcement layers (ESLint + guardian + visual regression); explicit opt-out mechanism; cross-brand strategy; accessibility handoff (highest-leverage a11y decision); Figma-code token sync; design review triggers; migration patterns; metrics that matter.
The Monorepo Discipline Guide
Monorepo as discipline, not just setup. When to use (and when not); tool selection framework (Turborepo, Nx, Rush, Bazel); package structure; task graph design; cache tuning (the biggest lever, 85%+ target); affected detection; dependency hygiene; CI integration patterns; versioning + releases; governance and package boundaries; metrics that matter. Turns monorepo from tax into accelerator.
The Internationalization Guide
i18n as engineering discipline. Message key conventions, ICU MessageFormat deep dive, CLDR plural rules across language families, Intl APIs (never hardcode), RTL support (logical properties + bidi), translator workflow, extraction pipeline, orphaned message cleanup, text expansion tolerance, pseudo-locale testing, SEO for i18n, MT vs human. Architecture that scales to 8+ locales.
The Accessibility Discipline Guide
Accessibility as engineering discipline, not compliance sprint. WCAG in practice (the 15 things you actually check); four testing layers (audit, review, keyboard + screen reader, users); component library as accessibility contract; framework-specific patterns; custom widget discipline (WAI-ARIA); baseline + regression model. From 20 months of shifted practice.
The Log Investigation Guide
Log investigation as discipline. Structured logs as foundation; sharp-question habit; the filter-group-correlate flow; error grouping patterns; temporal + user + request + trace correlation; volume anomalies as signal; retry patterns as diagnostic; when logs aren't enough; log hygiene; common traps.
The Release Engineering Guide
Release engineering as discipline. Six artifacts per release; conventional commits as foundation; changelog vs. release notes (they differ); SemVer + auto-bumps; release trains vs. on-demand; canary + rollback; hotfix protocol; DB migration sequencing. Boring-on-purpose practice from 18 months of iteration.
The Migration Discipline Guide
Database migrations are production interventions. Four migration types; plan-then-generate discipline; safety patterns (NOT NULL, CONCURRENTLY, expand-migrate-contract); framework specifics; rollback discipline; production apply flow; common failure modes. From 4 years of Postgres schema evolution.
The Performance Investigation Guide
Performance work is a discipline. Four types of perf work; the investigation flow; systematic scan vs. hypothesis hunt; measurement discipline; six categories; when to optimize vs. scale; common traps. From 3 years of growth-driven perf work.
The Fixture Discipline Guide
Test fixtures are code you touch often. Four strategies, factory pattern deep dive, composition over inheritance, deterministic vs. random, sprawl prevention. From refactoring a 1,800-test 5-year-old codebase.
The On-Call Investigation Guide
On-call is investigation under time pressure. Four page classes, the first-five-minutes flow, correlation across signals, metrics + log investigation flows, when to escalate, and how to make runbooks stay useful.
The Code Review Discipline Guide
Reviewing PRs when Claude wrote half the code. What changes about the reviewer's job; what doesn't. Reviewing for intent vs. mechanics; when to trust the diff; how AI-generated code fails differently.
The Multi-Agent Workflow Guide
When multi-agent works and when it collapses. Router design, handoff patterns, context budgeting across agents, avoiding the coordination overhead trap. Multi-agent as engineering discipline, not novelty.
The Security Discipline Guide
Layered defense for AI-assisted development. Six pieces (diff review, weekly scans, quarterly deep audit, yearly pen test, incident-driven audit, onboarding audit). Boring and sustainable — that's the point. What we do; what we explicitly don't.
The Planning Discipline Guide
ADR, design docs, specs, RFCs with Claude Code. When to write each; how they differ; who reviews them. The planning artifacts that keep teams aligned; the ones that become ceremony without substance.
The Debug Loop Discipline
Reproduce, isolate, hypothesize, verify, fix. The five-step loop that turns debugging from wandering into targeted investigation. What Claude Code helps with; what it makes worse if you skip steps.
The Refactoring Discipline Guide
When, why, and how with Claude Code. Refactor scope discipline (25-step cap), test-first refactoring, plan-then-execute pattern, behavior preservation. The refactoring practice that prevents scope creep to rewrites.
The Documentation Discipline Guide
Diátaxis + Claude Code. Four documentation types (tutorial, how-to, reference, explanation); when each matters; how to keep them fresh with Claude Code doing the drafting. Documentation as a systems practice, not a one-off.
The CLAUDE.md Deep Dive
Every section, every choice. What belongs in CLAUDE.md vs. slash commands vs. subagents. The examples that scale to team use vs. the ones that create noise. Section-by-section teardown of a production CLAUDE.md.
The Onboarding Playbook
The specific 4-hour playbook we run for every new hire. Hour by hour: setup, repo tour with Claude, first task, first PR merged. Traditional onboarding compressed 5x with Claude Code assistance; the concrete script.
The Testing Discipline Guide
The Claude Code testing pyramid. Where unit, integration, E2E fit; how much coverage matters; when tests hurt more than help; how to make tests fast, deterministic, meaningful. What Claude Code changes about test writing.
Cost Optimization for Claude Code at Scale
Six levers ranked by impact. Prompt caching, model routing, context trimming, batch API, subagent scoping, per-repo budgets. Real receipts from production usage; nothing theoretical. What actually moves the number.
Designing Your Subagent Router
Making multi-agent work without chaos. When to route to which subagent, how to phrase invocation, avoiding the "everything is a subagent" trap. The routing patterns that separate coherent teams from fragmented ones.
Configuring MCP Servers for a Team
Team-shared .mcp.json, personal credentials via env, read-only-by-default discipline, scoped auth tokens, upgrade paths. Everything that makes MCP work for 10 engineers without becoming a security incident.
Building Your Hook Layer
Security + safety-gates in Claude Code. Which hooks fire when, what they can block, and how to layer PreToolUse, PostToolUse, and UserPromptSubmit into a coherent quality gate that doesn't nag.
The Complete Claude Code Setup Guide (2026 Edition)
From npm install to a production-ready Claude Code environment: MCP servers, hooks, subagents, cost caps, and team sync — everything wired correctly. The one guide new engineers should read on day one.
How to Design Slash Commands That Scale
Every pattern for writing, sharing, and versioning slash commands. Naming conventions, argument shape, tool scoping, model selection, discoverability. What separates a command that lasts from one that gets rewritten.
The Commit → Review → PR → Deploy Workflow with Claude Code
The full engineering loop with Claude Code in each seat. When to invoke, when to review, when to override. Practitioner walkthrough of an actual production workflow, four hooks deep.