78 Learnable Patterns from Claude Code

Use 'NEVER' and 'DO NOT' instead of vague guidance. Instead of 'be careful with git operations', write 'NEVER run force push to main/master'. Language models respond better to explicit prohibitions.

Write out every edge case directly in the prompt. 'If a pre-commit hook fails...' 'If the file is too large...' 'If there are no changes to commit...' Every branch is specified rather than relying on the model to infer the right behavior.

Split system prompts into static sections (never change between sessions) and dynamic sections (context-specific). Use SYSTEM_PROMPT_DYNAMIC_BOUNDARY marker. This enables prompt caching — static parts are cached, only dynamic parts change.

Explicitly instruct agents to batch independent tool calls: 'If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel.' This dramatically reduces latency.

Write code comments for AI agents working on the codebase rather than (just) human readers. Include context that helps the model make better decisions about the code.

Reload git branch state, recent commits, and CLAUDE.md files on every single turn. Context must be fresh, not cached from a previous state that may have changed.

Build always-on agents as periodic tick systems, not continuously running processes. Every N minutes, ask 'anything worth doing right now?' with a strict blocking budget (15 seconds). If an action exceeds budget, defer to next tick.

Build agents as a continuous loop: read input → decide tool → execute → observe output → decide next action → repeat until complete. This is fundamentally different from single-shot chat responses.

Agents that can sleep (pause execution) and self-resume without user prompts. Serialize agent state, set a wake condition, and restore when conditions are met.

Create, delete, and list scheduled agent jobs with cron expressions. Include external webhook triggers. Agents can be scheduled to run at specific times without user intervention.

Dedicated subagents with single-file scope restrictions automatically update documentation. Each doc has an assigned agent that keeps it current without touching other files.

Layer 1: Cheap index always loaded (~150 chars/pointer). Layer 2: Topic files fetched on demand. Layer 3: Transcripts searched but never loaded. Treat context window as scarce resource with tiered storage.

Treat all memory as a HINT, never as truth. Always verify against the actual codebase/state before acting on remembered facts. If a fact can be re-derived from code, don't store it.

Run a forked subagent with read-only access during idle time to merge observations, remove contradictions, and convert vague insights into absolute facts. Must be isolated to prevent corruption.

Summary (compress old messages), Truncate (drop oldest), Selective (keep only tool results), Dedup (remove repeated content), Tiered (memory index vs full content). Apply based on context usage patterns.

Always set MAX_CONSECUTIVE_FAILURES on retry loops. The autocompact bug wasted 250K API calls/day because there was no failure limit. A 3-line fix (max failures = 3) solved it. Never retry infinitely.

Modify prompt structure to prevent model-specific issues. Force safe boundary markers, relocate risky blocks, add non-empty markers for empty tool outputs. Fix prompt shape, not model behavior.

Provide dedicated Grep and Glob tools instead of letting agents use raw shell commands. Structured tools give better-formatted results that the model can parse more reliably.

Each tool has its own permission level, validation logic, and output formatting. 23 security checks on bash alone. Never give blanket permissions — gate each tool individually.

Use a separate LLM evaluation ('Is this command safe?') for permission decisions instead of brittle allowlists. Context-aware security replaces static rules.

Integrate Language Server Protocol for call hierarchies, symbol definitions, and references. Gives agents IDE-level code understanding instead of just text search.

Provide interception points across all execution stages: pre-edit, post-edit, pre-deploy, post-deploy, pre-commit, etc. Users can inject validation, transformation, and audit logic at any point.

Actual browser automation using Playwright for real DOM interaction, not just HTTP fetching. Enables testing, web scraping, and UI automation by agents.

Use native (non-JavaScript) code to compute request hashes (cch parameter) preventing third-party API wrapper spoofing. Bun's Zig HTTP stack handles this below the JS layer.

Fork (independent, no shared state), Teammate (shared context via AsyncLocalStorage), Worktree (git branch isolation). Choose based on task coupling: independent→fork, collaborative→teammate, code changes→worktree.

Workers communicate via structured <task-notification> XML messages through a mailbox system. Shared scratchpad directory for durable cross-worker knowledge. Explicit ban on lazy delegation.

Worker agent does the task, advisor agent evaluates quality independently. Iterate until quality threshold met. This is the same principle as code review applied to AI agent output.

Tier 1: In-process (shared memory, ~0ms). Tier 2: Cross-process via Unix domain sockets (~1ms). Tier 3: Remote via cloud containers (~100ms+). Choose tier based on latency needs and isolation requirements.

Offload complex planning to a remote Cloud Container Runtime with extended time (30 min). Poll for results. Require human review before applying. Scale by delegation, not by enlarging context.

Enable local Claude instances to discover each other on the same machine. Foundation for collaborative agent teams that self-organize without central coordination.

Inject decoy tool definitions into API responses to pollute training data of anyone recording API traffic. Gated behind feature flag, only active for first-party sessions.

Server-side buffering of assistant text between tool calls, summarization, and cryptographic signing. Limits reasoning chain visibility in API traffic.

Decision framework: always disclose AI involvement vs. configurable per-context. Includes forbidden string lists, automatic stripping of internal identifiers, and transparency policies.

The March 31 attack showed: always verify package integrity, use lockfiles, monitor for malicious packages during high-profile events. Prefer native installers over npm for critical tools.

WebFetchTool uses domain whitelisting and blacklisting with redirect sandboxing and copyright guardrails. Agents shouldn't fetch from arbitrary URLs.

44+ flags that compile to false in external builds. Each is a real implementation, not a stub. Enables internal testing, staged rollout, and instant rollback. Use prefix conventions (tengu_*) for bulk management.

Immutable daily logs of agent decisions and actions. Prevents history erasure. Enables audit trails and debugging. KAIROS daemon writes append-only logs throughout the day.

Track false claims rate across model versions. Capybara v8 regressed to 29-30% from 16.7% in v4. Quantify model quality and catch regressions before they reach production.

Focus on fixing the system rather than finding someone to fault. The leak was caused by a process gap, not an individual. Emphasis: process, culture, or infrastructure improvements.

Monitor behavioral patterns for frustration signals: regex matching, 'continue' button frequency, session length vs. completion rate. Use as product quality signal, not surveillance.

Two-layer architecture: Bones (deterministic PRNG for consistency — same user = same pet) and Soul (AI-generated personality for variety). Separate concerns of reproducibility and creativity.

Full voice command mode with its own CLI entrypoint. Voice is a separate access channel to the same agent capabilities, not a different product.

Control agents from phone or browser while they run on a dev machine. Review and approve decisions remotely. ULTRAPLAN uses this for approval flows.

Every check that depends on someone remembering should become an automated hook. The leak itself was caused by a missing .npmignore — a process gap that automation would have caught.

Map features to maturity stages (S0-S5 in V5.3, or flag states in Claude Code). Features progress through gates: internal dev → employees → beta → staged rollout → GA. Never skip stages.

Define what sources are admissible for learning: official docs, public reporting, clean-room projects, internal abstraction. Never: unauthorized code, leak mirrors, scrape pipelines.

The query engine automatically triggers context compression before hitting the ceiling, not after. Reserve a buffer (13,000 tokens) before the limit, generate structured 20,000-token summaries, and include a circuit breaker stopping after 3 consecutive failures.

MicroCompact: local content trimming, zero API calls. AutoCompact: triggers near ceiling with 13K buffer, generates 20K summaries, circuit breaker after 3 failures. FullCompact: complete conversation compression with selective file re-injection (5K tokens/file max), resets working budget to 50K tokens.

After N consecutive failures (3 for compaction, 5 for ULTRAPLAN polling), stop retrying and degrade gracefully. The autocompact bug (250K wasted calls/day) proved that unlimited retries are catastrophic. Always bound retry loops.

After 3+ consecutive 529 errors, automatically switch from Opus (powerful, expensive) to Sonnet (lighter, more available). Exponential backoff (2s, 4s, 8s) before fallback. Graceful degradation beats total failure.

Tools return structured, precise, narrow data — not large context blobs. Each tool provides a specific answer with pointers for deeper investigation. This keeps context windows lean for long-running agents.

Tool results undergo prompt-injection pattern filtering before returning to agents. Strip any instruction-like content from untrusted data sources to prevent agents from following embedded directives.

Claude Code doesn't run MCP on top of something else — the tool architecture IS MCP at every layer. Computer Use, file operations, bash execution all use identical discovery (tools/list) and invocation (tools/call) patterns.

~85 slash commands (/commit, /review, /compact, /mcp, /memory, /skills, /tasks, /vim, /diff, /cost) as user-facing shortcuts to complex workflows. Slash commands are skills with simpler invocation.

Use React with Ink for terminal rendering — same component model as web, but for CLI. Enables state management, component hierarchy, interactive REPLs with message history, keyboard navigation, and streaming text reveal.

OpenTelemetry and gRPC are lazy-loaded at runtime, not imported at startup. This keeps CLI startup fast (<500ms). Only load what you need, when you need it.

Bidirectional JWT-authenticated channels between CLI and IDE (VS Code/JetBrains). Each direction has its own authentication. Secure service-to-service communication pattern.

Use HMAC signatures (not just API key headers) for request authentication. Require client ID in every request. Per-client rate limiting (not global). Prevents replay attacks and unauthorized tool invocation.

MAX_SUBCOMMANDS_FOR_SECURITY_CHECK = 50 created a bypass: malicious CLAUDE.md could generate 50+ subcommand pipelines that skip security checks. Always design security checks to scale with input, not cap at a fixed number.

Use the 'files' field in package.json (explicit include) instead of .npmignore (explicit exclude). Allowlist is safer because only what you list gets published. Everything else is excluded by default. No way to accidentally include unintended files.

Return { code, message, retryable } from every tool/MCP operation. Agents can programmatically decide whether to retry or fail. Much better than unstructured error strings.

p95 response time targets: <300ms for reads, <1s for writes. No unbounded result sets. Pagination is mandatory on all list tools. Agents running continuously amplify any performance issue.

Log every tool call with: client ID, timestamp, parameters, result. Essential for debugging autonomous agent behavior and for compliance. Immutable audit trail.

The architecture assumes direct access to a single model provider and treats context management as foundational. Session longevity is engineered from initial design, not added later. Context window is THE scarce resource.

Multi-agent orchestration fits in a well-structured prompt rather than a framework. LangChain/LangGraph add unnecessary complexity. Claude Code proves you can coordinate agents with prompt engineering + a plugin tool system.

Verify written data against actual disk state rather than trusting memory. Update the memory index only AFTER successful writes. The agent never trusts what it remembers — it always checks reality.

Node.js reuses HTTP connections for performance, but if the server closes between requests, the next request fails silently. Claude Code disables connection reuse for critical paths — slower but reliable. Prefer reliability over marginal performance.

Not every decision needs frontier reasoning. Use Haiku for safety checks, regex for sentiment detection, zero API calls for local content trimming. Reserve Opus/Sonnet for actual reasoning and generation. This is how Claude Code keeps costs manageable despite 8-12 internal API calls per user command.

Sub-agents sharing parent context via KV cache makes parallelism economically viable. Fork byte-identical contexts so caching applies. Without this, spawning 3 sub-agents costs 3x the context tokens. With it, the cached prefix is free.

Embed safety constraints directly in tool descriptions where the model encounters them, not in a separate policy document. Layer defenses: inline rules + per-tool permission tiers + cheap model pre-screening. The 2,500-line bash validator is safety-at-point-of-use.

The core agent loop is a ~20-line while-loop over tool calls. The 512K lines are the HARNESS: context management, permissions, error recovery, compression, memory, security validation. Don't over-engineer the loop; invest in the infrastructure.

Success depends on WHERE content sits in context and WHAT breaks cache, not on wordsmithing prompts. Separate static from dynamic for cache hits. Implement three-tier compression. Instrument what correlates with success. Context engineering > prompt engineering.

Fail builds if source maps are included unintentionally. Define artifact allowlists (package.json 'files' field). Compare package contents against prior releases automatically before publishing. The entire Claude Code leak was a missing build check.

A single user command generates 8-12 internal API calls, each including full system prompt + conversation history + file contents + tool-use tokens. A 15-command session can reach 200K+ input tokens. Design for token cost from day one.

Build typed, purpose-built tools for frequent operations instead of one do-everything tool. Each tool gets its own validation, permission gate, and structured logging. Dedicated Read/Write/Grep tools outperform a single 'file operations' tool.

Spawn sub-agents as regular tool calls (AgentTool), keeping architecture flat. Sub-agents are first-class registry citizens, not special orchestration. This avoids complex coordination frameworks.

1,060+ community skills exist across Claude Code, Codex, Cursor, OpenCode, and more (VoltAgent/awesome-agent-skills). Skills from Vercel, Cloudflare, Stripe, Supabase, Google, HashiCorp are production-ready. Integrate external skill repos into your agent platform.

The leak exposed how AI agents handle permissions, data access, and attribution in production. Regulated industries need: per-tool audit trails, immutable logging, human-in-the-loop for high-risk operations, and clear AI contribution disclosure.