Claude Code — The Obsessive Reference

claude-code / obsessive-reference

KNOW IT
COLD.

Every system, every flag, every pattern. The reference built for engineers who want to use Claude Code the way Anthropic's own team does — not casually, but as infrastructure.

v2.1.131 · 18 sections · updated may 2026

The 5 Systems That Determine Your Effectiveness

System 01

Configuration Hierarchy

Global → user → shared project → local project → CLI flags. Each layer overrides the one below. Enterprise settings override everything. Know which file to edit.

System 02

Permission System

Fine-grained allow/deny/ask rules per tool, per path, per command prefix. Gates every operation. Misconfigure and you're constantly interrupted — or dangerously open.

System 03

Hook System

18+ lifecycle events. PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop. Hooks are deterministic. Prompts are advisory. Use hooks for anything that MUST happen.

System 04

MCP Protocol

Connect 3,000+ external services. GitHub, databases, Sentry, Slack, your internal APIs. MCP turns Claude Code from a file editor into a full environment hub.

System 05

Subagent System

Up to 10 parallel agents with isolated contexts. Return only summaries to the main thread. Prevents context bloat. Enables true parallel workstreams.

Foundation

CLAUDE.md

The agent's constitution. Read every session. Encodes your codebase's rules, patterns, and commands. Commit to git. Keep under 200 lines. This is where most users leave productivity on the table.

As of May 6, 2026: Anthropic doubled Claude Code five-hour rate limits across Pro, Max, Team, and Enterprise plans and removed peak-hours reduction. Best time to go deep.

Quick-Start Path

Install

→

/login

→

Write CLAUDE.md

→

Set permissions

→

Add 3 core hooks

→

Wire MCP

→

Build subagents

→

Create skills

→

Automate CI

01

INSTALL & AUTH

Setup, authentication, cloud providers, verification

Installation (pick one)

all platforms

# Native binary (recommended — no Node.js needed) curl -fsSL https://claude.ai/install.sh | bash # macOS via Homebrew brew install --cask claude-code # Windows PowerShell irm https://claude.ai/install.ps1 | iex # NPM (legacy, deprecated — migrate with `claude install`) npm install -g @anthropic-ai/claude-code

Authentication Options

Recommended

Claude Pro / Max subscription

Single monthly bill covers claude.ai + CLI. Run /login inside claude and authenticate via browser. Simplest for individuals.

API / Enterprise

API Key (console.anthropic.com)

Usage-based billing. Set ANTHROPIC_API_KEY env var. Good for CI/CD pipelines and teams with existing API billing.

Cloud

AWS Bedrock

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
Uses your AWS profile. Enterprise billing relationship.

Cloud

Google Vertex AI

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=...

Verify & Maintain

health check

claude doctor # full health report: version, auth, config claude --version # check installed version claude update # manual update (auto-updates on by default) claude auth status # check auth state claude auth login # re-authenticate or switch accounts # Disable auto-updater in settings.json "env": { "DISABLE_AUTOUPDATER": "1" }

02

MENTAL MODEL

The architecture that shapes everything you do

Claude Code is not a chat interface with programming knowledge. It's an agentic system that reads codebases, executes commands, modifies files, manages git, connects to external services, and delegates to parallel subagents. It operates in three distinct layers.

The Three Layers

3

Extension Layer

MCP · Hooks · Skills · Plugins

External tools (databases, GitHub, Sentry), deterministic automation that fires regardless of model behavior, domain expertise injected just-in-time, packaged extensions for sharing. Configure once, leveraged forever.

2

Delegation Layer

Subagents — up to 10 parallel

Spawn with clean isolated contexts, do focused work, return only summaries to the main thread. Exploration results don't bloat your conversation. Route to Haiku for cheap analysis, Opus for architecture reasoning.

1

Core Layer

Main Conversation Context

Your primary interaction. Every message, file read, and tool output consumes from a shared 200K token window (1M with Opus extended). When context fills, quality degrades. This layer costs money per token. Use it for orchestration and final decisions only.

The key insight: Most users work entirely in the Core Layer, watching context bloat and costs climb. Power users push exploration and specialized work to the Delegation Layer, keep the Extension Layer configured for their workflow, and use the Core Layer only for orchestration.

Core Interaction Modes

modes

# Interactive REPL (primary mode) cd ~/your-project && claude # Start with initial prompt to focus session claude "explain the auth flow in this codebase" # Non-interactive / print mode (scripting) claude -p "list all TODO comments" cat error.log | claude -p "identify root cause" # JSON output for pipelines claude -p "count lines by file type" --output-format json # Plan mode — shows plan before executing ANY changes claude --plan # or inside session: /plan "refactor the auth module" # Continue last session claude -c # Continue specific session claude -r "session-id"

03

CLAUDE.md

The agent's constitution — read every session, no prompting needed

CLAUDE.md is the single highest-leverage file in your entire Claude Code setup. Claude reads it at the start of every session. It's the difference between an agent that knows your project and one you have to re-explain everything to, every time.

Global

~/.claude/CLAUDE.md

Your personal constitution. Coding style, commit format, PR discipline, review priorities. Follows you to every project.

Project

./CLAUDE.md (root)

Team-shared project context. Commit to git. Build commands, architecture decisions, conventions. The whole team benefits.

Scoped

.claude/rules/*.md

Modular rules loaded only when paths match. Avoids token bloat. Use for module-specific conventions instead of dumping everything in root.

Limit

Keep under 200 lines

Every line in CLAUDE.md costs context on every session. Move details to Skills (loaded just-in-time). Import other files with @filename.

Production CLAUDE.md Template

CLAUDE.md

# Project: marketing-advisor ## Stack AWS Lambda + Strands framework + Python 3.12 MCP-connected marketing APIs. Observability: ADOT/OTEL + EMF + X-Ray. ## Build / Test / Lint build: make build test: pytest tests/ -v lint: ruff check . && mypy . deploy: make deploy ENV=$1 ## Conventions - All LLM calls carry correlation trace ID from API gateway - Lambda: flush OTEL spans before return (ADOT layer pattern) - EMF for business metrics, X-Ray for distributed traces - Plan graph nodes must be idempotent - Never use env vars directly — always SSM parameter store - Conventional commits: feat/fix/chore/refactor(scope): msg ## Architecture rules - No synchronous calls for plan generation (Lambda timeout risk) - Strands agents are stateless; state lives in DynamoDB - Always include correlation_id in error logs ## What NOT to do - Don't commit until I approve - Don't write tests that mock the thing being tested - Don't add dependencies without asking first

Memory Shortcut

Inside a session, prefix your message with # to write directly to CLAUDE.md without generating a response:

in-session memory write

# This writes to CLAUDE.md silently, no response generated: # never use print() for debugging — always use structlog with correlation_id # Run /init in a new project to let Claude generate a CLAUDE.md /init

Common mistake: Dumping every project quirk into a single CLAUDE.md. Fix: split into .claude/rules/*.md with paths: globs so each rule loads only when relevant. Aim for ~60 lines in the root file.

04

CONFIG SYSTEM

Five-level hierarchy, complete settings reference

Configuration Hierarchy (top overrides bottom)

Level	File	Scope	Notes
Enterprise	/etc/claude-code/managed-settings.json	All users	Cannot be overridden by anyone
CLI flags	--flag value	Current session	Highest user-level override
Local project	.claude/settings.local.json	Personal, per-project	Gitignore this. Personal prefs.
Shared project	.claude/settings.json	Team via git	Commit this. Team standards.
User global	~/.claude/settings.json	All your projects	Personal defaults everywhere.

Key settings.json Fields

.claude/settings.json

{ "$schema": "https://json.schemastore.org/claude-code-settings.json", "model": "claude-sonnet-4-6", "permissions": { "allow": ["Read", "Glob", "Grep", "Bash(npm run:*)", "Edit(src/**)"], "deny": ["Read(.env*)", "Bash(rm -rf:*)", "Bash(sudo:*)"], "ask": ["WebFetch", "Bash(docker:*)"], "additionalDirectories": ["../shared-lib"], "defaultMode": "acceptEdits" }, "env": { "NODE_ENV": "development", "DEBUG": "app:*" }, "includeCoAuthoredBy": true, "cleanupPeriodDays": 30 }

05

PERMISSIONS

Fine-grained allow/deny/ask rules that gate every operation

The permission system is what separates an agent you trust to run autonomously from one you have to babysit. Configure it right and you get maximum autonomy with real guardrails.

Permission Rule Syntax

permission patterns

# Tool-level "Read" # allow all reads "Edit(src/**)" # allow edits only in src/ "Read(.env*)" # in deny: block reading .env files # Bash with command prefix matching "Bash(npm run:*)" # allow any npm run ... command "Bash(git:*)" # allow any git command "Bash(rm -rf:*)" # in deny: block rm -rf # MCP tool access "mcp__github" # allow all github MCP tools "mcp__github__create_pr" # allow specific MCP tool only # defaultMode options "acceptEdits" # auto-approve file edits, ask for bash "bypassPermissions" # fully autonomous (use carefully) "default" # ask for everything not in allow list

Never use "defaultMode": "bypassPermissions" in shared project settings. It disables all permission checks for everyone who pulls the repo. Reserve for personal local settings only.

Recommended Starter Permission Set

safe + productive defaults

"permissions": { "allow": [ "Read", "Glob", "Grep", "Edit(src/**)", "Write(src/**)", "Bash(npm run:*)", "Bash(git:*)", "Bash(pytest:*)", "Bash(make:*)" ], "deny": [ "Read(.env*)", "Read(secrets/**)", "Bash(rm -rf:*)", "Bash(sudo:*)", "Edit(.git/**)" ], "ask": ["WebFetch", "Bash(curl:*)", "Bash(docker:*)"] }

06

SLASH COMMANDS

Full in-session command vocabulary

Command	What it does	Power tip
/init	Generate CLAUDE.md for current project	Run on every new project. Review and refine before committing.
/plan [task]	Show implementation plan before any changes	Always plan first on large tasks. Review, then approve to execute.
/compact	Summarize conversation to reclaim context	Run proactively when you notice slowdowns, not after quality degrades.
/clear	Full context reset, fresh session	Between unrelated tasks. Don't carry old context into new work.
/cost	Show token usage and cost breakdown	Run periodically. Subscription users see per-model breakdown.
/effort [low\|med\|high]	Set reasoning effort level for current task	Use /effort low for simple lookups, high for architectural decisions.
/model [name]	Switch model mid-session	Start on Sonnet, switch to Opus for specific hard reasoning steps.
/resume	Interactive session picker	Navigate and resume any past session by ID or description.
/batch [cmd]	Apply a change across many files in parallel	Migrate all components, update imports — massive scale at once.
/loop [interval] [cmd]	Run a command on a timer within the session	/loop 5m /health-check — in-session polling for monitoring.
/team-onboarding	Generate ramp-up doc from your CLAUDE.md + skills	Run when onboarding new team members. Auto-produces the guide.
/login	Authenticate or switch accounts	Needed once per machine or when token expires.
/status	Show current session state	Context size, model, active permissions, connected MCP servers.

The most important pair: Run /plan before large implementation tasks, and /compact before context fills. These two habits alone will noticeably improve quality and reduce cost.

07

KEYBOARD SHORTCUTS

Every hotkey in the REPL

Navigation & Control

Interrupt / cancel

Ctrl+C

Exit Claude Code

Ctrl+D

Previous command

↑

Next command

↓

Clear current input

Ctrl+U

Jump to start of line

Ctrl+A

Jump to end of line

Ctrl+E

Delete word back

Ctrl+W

Input & Files

Multiline input

Shift+Enter

Paste an image into prompt

Ctrl+V

Reference file / expand @path

@path

Open $EDITOR for long prompt

EscEsc

Trigger slash command menu

/

Search command history

Ctrl+R

Esc Esc opens your $EDITOR for the current prompt — use this for writing complex spec-style prompts, multi-step instructions, or any input over ~3 lines. Way better than inline multiline.

08

HOOKS — DETERMINISTIC

18+ lifecycle events. Use hooks for anything that MUST happen. Prompts are advisory. Hooks are law.

Core principle: CLAUDE.md rules can be ignored by a fast-moving agent. Hooks cannot. They run before or after every tool call regardless of model behavior. If something must always happen — formatting, linting, auditing, blocking — put it in a hook, not a prompt.

Hook Lifecycle

UserPromptSubmit

Fires on every prompt. Inject dynamic context: current git branch, open tickets, recent errors, env state.

INJECT CONTEXT

PreToolUse

Fires before any tool call. Validate, audit-log, or block the operation entirely.

EXIT 2 = BLOCK OPERATION

PostToolUse

Fires after each tool execution. Auto-format written files, run linters, sync state to external systems.

Stop

Fires when the agent finishes responding. Run tests, compile, post notifications, update tickets in Jira.

SubagentStop

Fires when a subagent completes. Aggregate results, trigger next step in a pipeline.

Notification

Fires when Claude wants your attention. Route to Slack, desktop notif, sound alert — never miss a long task completing.

Production Hook Examples

hooks in settings.json

"hooks": { // Auto-format Python files on every write "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "ruff format \"$FILE_PATH\" && ruff check --fix \"$FILE_PATH\"" }] }], // Run tests when agent finishes "Stop": [{ "type": "command", "command": "pytest tests/ -x -q 2>&1 | tail -20" }], // Block rm -rf (exit 2 = block) "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo \"$TOOL_INPUT\" | python3 -c \"import sys,json; d=json.load(sys.stdin); sys.exit(2 if 'rm -rf' in d.get('command','') else 0)\"" }] }], // Audit log every bash command "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "{ echo \"$(date) CMD:\"; cat; } >> ~/.claude/audit.log" }] }], // Desktop notification when done (macOS) "Notification": [{ "type": "command", "command": "osascript -e 'display notification \"Task complete\" with title \"Claude Code\"'" }] }

09

MCP SERVERS

3,000+ integrations. Extend Claude beyond files and bash.

MCP (Model Context Protocol) turns Claude Code from a file-editing tool into a genuine environment hub. Connect GitHub, databases, Sentry, Slack, your internal APIs — Claude calls them as native tools.

Configuring MCP Servers

.mcp.json (project root) or ~/.claude/settings.json

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." } }, "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"] }, "your-internal-api": { "command": "python3", "args": ["/path/to/your/mcp-server.py"], "env": { "API_KEY": "..." } } } }

High-Value MCP Servers for Your Stack

@modelcontextprotocol/server-github

GitHub

Create PRs, comment on issues, review code, list open tickets — all from the CLI without switching context.

AWS MCP servers

AWS / CloudWatch

Query CloudWatch logs, describe Lambda functions, check CloudFormation stacks. Your debugger agent's best friend.

Sentry / Datadog MCPs

Observability

Fetch recent errors, traces, and alerts. Claude can correlate your code changes with production errors automatically.

@modelcontextprotocol/server-postgres

Database

Query your DB directly. Schema introspection, data debugging, migration verification — without writing a single SQL client.

Disable unused servers: Every connected MCP server adds startup time and potential tool noise. Only enable the servers relevant to the current project via project-level .mcp.json.

10

SUBAGENTS

Up to 10 parallel agents. Isolated contexts. Context bloat killer.

Subagents are the single biggest productivity multiplier most Claude Code users never configure. They spawn with clean contexts, do focused work, and return only summaries — keeping the main conversation lean and your costs down.

Creating a Custom Subagent

.claude/agents/code-reviewer/AGENT.md

--- name: code-reviewer description: Expert code reviewer. Use PROACTIVELY after code changes. tools: Read, Grep, Glob, Bash model: opus permissionMode: plan --- You are a senior engineer performing code review. Focus on: - Correctness and edge cases - Security (OWASP Top 10, secrets in code) - Missing error handling and N+1 queries - Adherence to conventions in CLAUDE.md - Performance anti-patterns Report findings with severity: CRITICAL / HIGH / MEDIUM / LOW

Subagent Roster

Planner

.claude/agents/planner/AGENT.md

Read-only tools. Analyzes codebase and produces sequenced implementation plans. No write access. Use before any major change.

Security Reviewer

.claude/agents/security/AGENT.md

model: opus. Proactively triggered on auth/data-handling changes. OWASP Top 10, secrets detection, SQL injection.

AWS Debugger

.claude/agents/aws-debug/AGENT.md

Read + AWS MCP tools. Loads runbooks knowledge. Fetches CloudWatch logs, correlates errors with code. Triggered on incident-style prompts.

Test Generator

.claude/agents/test-gen/AGENT.md

Read + Write(tests/**). Runs in parallel while you implement. Generates unit + integration tests. Triggered after Stop hook.

Parallel Execution Pattern

parallel workstreams prompt

Implement the following in parallel using subagents: Subagent 1: Implement the budget_optimizer Strands node Subagent 2: Write integration tests for the conversational layer Subagent 3: Update the OpenAPI spec for the new endpoints Each subagent should work in isolation. Summarize results when done.

11

SKILLS & COMMANDS

Reusable prompt templates loaded just-in-time as /slash-commands

Skills are folders with a SKILL.md file in .claude/skills/ (project) or ~/.claude/skills/ (personal). Each skill becomes a /skill-name slash command automatically. They load just-in-time, keeping CLAUDE.md lean.

Skill Frontmatter Options

.claude/skills/deploy/SKILL.md

--- name: deploy description: Deploy the application to an environment argument-hint: "[environment]" user-invocable: true # shows in / menu auto-invocable: false # don't auto-trigger run-in-subagent: true # isolated context disable-model-invocation: false # false = Claude reasons about it --- Deploy the application to the $1 environment (default: staging). Steps: 1. Run the full test suite and abort if any fail 2. Build the production bundle 3. Deploy using ./scripts/deploy.sh $1 4. Verify the health check endpoint returns 200 5. Report deployment status and any anomalies

Powerful Skill Patterns

auto-invocable: true

Auto-triggered skills

Set auto-invocable: true so Claude triggers the skill without being asked. Great for documentation update skills that fire after implementation.

disable-model-invocation: true

Context initializers

Load project state at session start without AI processing. Use for a /load-context skill that injects current sprint tickets, env status, recent deploys.

run-in-subagent: true

Isolated execution

Long-running skills (test suites, deployments, log analysis) run in their own context. Output doesn't bloat your main session.

$ARGUMENTS / $1 $2

Parameterized skills

Pass arguments: /deploy production where $1 = "production". Or use $ARGUMENTS for the full argument string.

Skills vs CLAUDE.md: CLAUDE.md is for always-on context (~60 lines max). Skills are for domain expertise loaded only when needed. Move detailed instructions from CLAUDE.md into skills to slash your per-session context cost.

12

MODEL STRATEGY

Route work to the right tier. Quality × cost × speed tradeoffs.

Haiku

claude-haiku-4-5 · Fast · Cheap

Subagent exploration tasks
File/symbol search sweeps
Log analysis, grepping
Simple code generation
Formatting, trivial edits

Sonnet

claude-sonnet-4-6 · Balanced · Default

Most implementation work
Code review subagents
Feature development
Documentation writing
Debugging (non-critical)

Opus

claude-opus-4-6/4-7 · Powerful · Expensive

Architecture decisions
Complex multi-file refactors
Security reviews (critical)
Debugging subtle/systemic bugs
Extended thinking tasks

Switching Models

model control

# In session /model claude-opus-4-6 /model claude-haiku-4-5 # CLI flag for full session claude --model claude-opus-4-6 # Subagent model env var export CLAUDE_CODE_SUBAGENT_MODEL=haiku # Set effort level (reduces tokens used for reasoning) /effort low # simple tasks /effort medium # default /effort high # complex architecture

Default as of April 2026: Pro and Max subscribers default to high effort on Opus 4.6 and Sonnet 4.6. Opus 4.7 stays at xhigh. This was restored after a March/April effort downgrade. Standardize on Opus if quality is your only variable — cost difference is worth it at your usage level.

13

MEMORY & CONTEXT

@file injection, /compact, session resumption, @-mentions

@file / @path Injection

context injection patterns

# Inject single file into prompt Review @src/handlers/checkout.py for security issues # Inject a directory What patterns does @src/graph/nodes/ use for input validation? # Compare files Compare @src/old-node.py and @src/new-node.py — what changed? # Reference CLAUDE.md imports (reduces token duplication) # In CLAUDE.md: See @.claude/rules/api-patterns.md for REST conventions See @.claude/rules/testing.md for testing standards

Context Management

/compact

Summarize conversation

Run proactively when you notice slowdowns. You can provide custom instructions for what to preserve: /compact keep all file paths and decisions made

/clear

Full reset

Between completely unrelated tasks. Don't carry old context into new work — it costs tokens and degrades focus.

Session resume

-c and -r flags

claude -c continues last session. claude -r session-id resumes specific session. Full context restored from JSONL transcripts.

Context window

200K / 1M tokens

Standard models: 200K. Opus 4.6 / extended context: 1M. Monitor with /cost. Use subagents to offload exploration and prevent bloat.

14

GIT & WORKTREES

Parallel feature work without branch conflicts

Git worktrees are the secret weapon for parallel Claude Code work. Each Claude session gets its own isolated worktree — multiple features in parallel, zero context switching, no stash games.

Worktree Workflow

parallel feature development

# Start Claude in a dedicated worktree for a feature claude -w feature-auth # Opens new worktree at ../project-feature-auth # Independent branch, independent Claude session # Meanwhile, work on another feature in your main directory # Or manually: git worktree add ../project-feature-payment feature/payment-v2 cd ../project-feature-payment && claude

Git Integration Patterns

common git workflows

# Auto-checkpoint: every change creates a checkpoint # Undo Claude's last change: git diff HEAD # see what changed git checkout . # revert everything git stash # stash and reconsider # Trigger the GitHub MCP to create a PR when done: Create a PR for this branch with a summary of the changes and link it to ticket MKTG-247. # Batch apply across many files: /batch update all Python files to use structlog instead of print()

Claude Code GitHub Action: Mention @claude in any PR or issue and Claude can analyze code, implement fixes, and create pull requests directly. Set up .github/workflows/claude.yml for repo-wide automation.

15

HEADLESS & CI

Non-interactive automation, pipelines, background agents

Headless Mode

CI/CD integration

# Non-interactive single query claude -p "review the last commit for security issues" # JSON output for parsing claude -p "analyze test coverage" --output-format json | jq .result # Stream JSON for long tasks claude -p "generate tests for src/handlers/" --output-format stream-json # Pipe input cat diff.patch | claude -p "summarize this PR for review" # Set ANTHROPIC_API_KEY for keyless CI auth export ANTHROPIC_API_KEY="sk-ant-..."

CI/CD Use Cases

PR Review Bot

@claude on every PR

GitHub Action triggers your code-review subagent. Posts structured review comments via GitHub MCP. Zero manual review queue.

Test Generation

Coverage on merge

On merge to main, run test-gen subagent for new functions without coverage. Tests committed as follow-up PR automatically.

Background Agents

Long-running tasks

Remote agents (research preview) run in the cloud for hours. Hand off a task, come back to results. No local session needed.

Incident Response

CloudWatch → Slack

CloudWatch alarm triggers headless Claude with your debugger agent. Fetches recent logs, posts structured incident summary to Slack.

16

COST CONTROL

Monitor, optimize, and stay within your rate limits

Typical Session Cost

Haiku

$0.10–0.45

Sonnet

$0.20–1.50

Opus

$0.50–2.25

Cost Reduction Tactics

reduce spend without sacrificing quality

# 1. Monitor with /cost (shows per-model breakdown) /cost # 2. Use @file mentions instead of letting Claude search # Searching wastes tokens; injecting is precise Review @src/billing/checkout.py # ✓ precise Review the checkout code # ✗ Claude searches, costs more # 3. /compact proactively (before quality degrades, not after) /compact keep all decisions and file paths # 4. /clear between unrelated tasks # 5. Route subagent exploration to Haiku export CLAUDE_CODE_SUBAGENT_MODEL=haiku # 6. /effort low for simple tasks /effort low Find all TODOs in src/handlers/ # 7. Disable unused MCP servers in project config # 8. Keep CLAUDE.md under 200 lines — every line = cost per session

Rate limits (May 2026): Anthropic doubled five-hour rate limits and removed peak-hours reduction on Pro/Max. If you still hit limits, Max subscribers can purchase additional usage at standard API rates.

17

NICK'S PLAYBOOK

Recipes for your stack: Strands, Lambda, marketing advisor, MCP

Recipe 1: Full Ticket → PR Pipeline

/load-context skill

→

Fetch JIRA ticket (MCP)

→

/plan

→

Implement (subagent)

→

code-reviewer agent

→

Create PR (GitHub MCP)

single prompt to kick off

Fetch ticket MKTG-247, show me the requirements, create an implementation plan, implement it, then create a PR with a summary linking back to the ticket. Don't commit until I approve the plan.

Recipe 2: Debug a Strands Graph Node

debug session prompt

The budget_optimizer node in our plan graph is producing wrong recommendations for campaigns with ROAS > 4. Failing test: @tests/test_budget_optimizer.py Node code: @src/graph/nodes/budget_optimizer.py Input schema: @src/graph/schemas/optimizer_input.py Use CloudWatch Logs to fetch the last 5 Lambda invocations that triggered this node. Cross-reference actual inputs/outputs with expected behavior. Report root cause and fix.

Recipe 3: Observability Gap Audit

observability audit

Audit @src/handlers/ for observability gaps: 1. Missing OTEL span creation 2. Business events not emitting EMF metrics 3. Errors caught but not logged with structured context 4. Missing correlation_id in log statements Create a prioritized list and open a Jira ticket for each via MCP.

Recipe 4: ADR Generation

architecture decision record

We're moving plan generation from Lambda to Step Functions due to Lambda's hard-kill timeout behavior on long-running Strands graphs. Write an ADR in @docs/adr/ (YYYYMMDD-title.md format). Include: - Context: Lambda hard-kill, cold start, graph timeout pattern - Decision and rationale - Trade-offs (use our architecture principles from CLAUDE.md) - Alternatives considered: Lambda with SQS, ECS Fargate - Consequences: cost, operational complexity, observability changes

Your CLAUDE.md Starting Point

CLAUDE.md — marketing advisor

# Project: marketing-advisor ## Stack AWS Lambda + Strands framework, Python 3.12, MCP-connected marketing APIs. Observability: ADOT/OTEL + CloudWatch EMF + X-Ray sampling. ## Commands build: make build | test: pytest | lint: ruff check . && mypy . | deploy: make deploy ## Critical Rules - All LLM calls carry correlation_id from API gateway - Lambda: flush OTEL spans before return (ADOT layer hard requirement) - EMF for business metrics, X-Ray for distributed traces - Strands graph nodes must be idempotent - Never env vars directly — always SSM parameter store - Never synchronous calls in plan generation (timeout risk) - Don't commit until I approve ## Conventions Conventional commits: feat/fix/chore/refactor(scope): msg Error logs must include: correlation_id, trace_id, input summary ## See also @.claude/rules/api-patterns.md @.claude/rules/testing.md @.claude/rules/strands-patterns.md

The compounding flywheel: Every correction you make mid-conversation — ask yourself: should this be in CLAUDE.md, a Skill, or a Hook? A few weeks of encoding your domain knowledge into the extension layer means every subsequent task runs faster with less prompting. The system pays back every hour you invest in it.