The Claude Bible
The complete program: from your first prompt to multi-agent orchestration
Mastering Claude (The Claude Bible) is a free, complete and interactive course to master Claude, Claude Code, Claude Cowork and the Claude API, from your first prompt to multi-agent orchestration. 20 modules, 237 lessons, beginner to expert, no signup, with a final exam and a verifiable diploma. This text is the static outline for search engines and AI assistants; enable JavaScript for the interactive course.
Also on this site: The Claude Code Skills Library, a curated directory of 490+ skills (official Anthropic, community collections, marketplaces).
Course outline as simple pages: in English · plan du cours en français · temario del curso en español.
How to read this Bible and what you will be able to do by the end.
How to use this program
A progressive course, not a reference doc. Tick 'Read': progress is saved locally. The goal: think with a model, not memorize buttons.
The Claude landscape on one map
3 surfaces, 1 model: Claude.ai (chat), Cowork (desktop agent), Claude Code (CLI agent). Under everything: the Claude API + the Opus/Sonnet/Haiku family. What differs between surfaces: the tools and the context, not the brain.
Your learning path through this Bible
Modules group related lessons by topic. Three levels: Intro, Intermediate, Expert. Read-Demo-Exercise-Quiz loop every lesson. Progress saved locally in the browser.
How each lesson is built
Each lesson has five fixed parts: explanation, key takeaways, demo, exercise, quiz.. The demo always contains something real and copyable, not a made-up placeholder.. The exercise includes a hidden worked answer you can reveal after trying.. You can enter any part directly if you already know the earlier sections..
Set up your practice space
Claude.ai is the browser chat interface, no install needed. A scratch notes file captures what works and what puzzles you. Claude Code is the optional CLI agent installed via npm. Verify any install by running a version check command.
Tokens, context, temperature, the Claude family. The bedrock.
What an LLM really is
An LLM predicts the next token, nothing else. Hallucinating = producing plausible-but-false output, a structural risk. No memory between sessions: everything lives in the context. Knowledge frozen at a cutoff date.
Tokens and the context window
Token = fragment of text, ~4 characters. Context window = input + history + files + output, capped (200K, sometimes 1M). Everything is billed in tokens, input and output. Too much noisy context degrades quality, not just cost.
Temperature, and the myth of the magic setting
Low temperature = stable/factual; high = creative/diverse. max_tokens caps the output (watch for cut-offs). A bad result almost always comes from the prompt, not the temperature.
The Claude family: Opus, Sonnet, Haiku
Opus = power, Sonnet = balance, Haiku = speed/volume. Same ids everywhere: claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5-.... Pierre: Opus for architecture/debug, Sonnet/Haiku for delegated repetitive work.
Meaning without a dictionary: embeddings
Embeddings convert text into lists of numbers. Similar meanings sit close in embedding space. Semantic search uses vector distance, not keywords. Models learn these positions from data, not rules.
Sampling: why the same prompt varies
Greedy decoding always picks the highest-probability word, giving deterministic output.. Top-k limits candidates to the k most likely words at each step.. Top-p (nucleus sampling) keeps the smallest set of words covering p of the total probability.. Sampled decoding introduces useful variety; temperature 0 removes it..
Three voices: system, user, assistant
The system prompt is invisible to the user but controls Claude's behavior.. User and assistant turns alternate to form the conversation history.. Claude reads the full history on every reply, not just the last message.. Knowing which role holds which text helps you debug unexpected behavior..
How Claude was trained
Pretraining: learning language from raw text at scale. RLHF: shaping behavior with human preference ratings. Constitutional AI: self-critique against written principles. Training phases determine knowledge, helpfulness, and safety limits.
Attention and why position matters
Attention weights every token against every other token to decide relevance. Lost-in-the-middle: information buried in a long prompt is recalled least reliably. Place tasks early, critical constraints late, and use structure to signal importance. Restating a question before and after a long document improves recall.
The knowledge cutoff and grounding
Knowledge cutoff: the date beyond which a model has no training data. Grounding: supplying current sources so the model reasons over fresh facts. Web search integration injects live results into the model context. Pasting or attaching text is the simplest form of manual grounding.
The Claude 5 era: Fable and Mythos
Fable 5 (claude-fable-5) and Mythos 5 (claude-mythos-5) are the same underlying Mythos-class model; Fable 5 is GA, Mythos 5 is invite-only via Project Glasswing.. Fable 5's three safety classifiers (cyber, bio/chem, distillation) fire in under 5% of sessions and fall back to Opus 4.8 instead of a flat refusal.. US export controls forced a global suspension of both models on June 12, 2026; Fable 5 returned worldwide July 1, 2026 with a stronger anti-jailbreak classifier.. Fable 5 pricing: $10/$50 per million input/output tokens, 1M context window, 128K max output, adaptive thinking always on..
The heart of prompt engineering: the 9 chapters of Anthropic's tutorial, the practical version.
Basic prompt structure
3 blocks: system (optional), User/Assistant messages, answer. Recent models execute the explicit, they do not guess. State the format, length, tone, language: always.
Being clear and direct
Claude = a brilliant hire with zero implicit context. Give the why, the reader, the setting. The colleague test: if they would ask a question, your prompt has a gap.
Assigning a role (system prompt)
A role steers tone, vocabulary and priorities. Role in the system prompt, specific, combined with mission and constraints. A good role replaces paragraphs of instructions.
Separating data from instructions (XML)
Mixing instructions and data = model confusion. XML tags (Claude is trained on them): clean boundaries. Reflex whenever there is a big block of data to process.
Formatting output and speaking for Claude (prefill)
Specify the output format (JSON, table, tags) explicitly. Prefill: seed the Assistant message to force the shape. Prefilling { or [ kills 'Sure, here is...' preambles.
Precognition: thinking step by step
Reasoning before concluding improves accuracy (chain-of-thought). Written reasoning acts as scaffolding for the model. Isolate the reasoning in a tag if you must parse the conclusion.
Using examples (few-shot)
2 to 5 input->output examples lock format and tone. The model imitates the pattern: terse examples => terse answers. Absolute consistency between examples; an edge case if useful.
Avoiding hallucinations
You don't remove hallucination, you constrain it. Always offer an 'Unknown' exit to avoid invention. Ground in sources + quote + search the web for facts.
Composing complex prompts (real cases)
Stable order: role, context, data, instructions, examples, thinking, format, guardrails. Add a technique only when it repairs a concrete failure. The best prompt = the clearest, not the longest.
Extended thinking vs chain of thought
Chain of thought: prompt Claude to reason step by step in its reply.. Extended thinking: internal scratchpad activated at the model level, not just by prompt.. Extended thinking costs more tokens; use it for genuinely complex problems.. Both modes improve accuracy, but extended thinking runs deeper exploration before answering..
Getting clean JSON out
Give Claude the exact field names and types in the prompt. Use prefill in the API to force JSON continuation. Instruct: raw JSON only, no prose, no code fences. Always validate with JSON.parse or a schema library before using the output.
Delimiters beyond XML
Delimiters signal where each prompt section starts and ends. Markdown headings label named sections cleanly. Fenced code blocks protect literal content from being read as instructions. Explicit marker lines wrap long pasted documents.
Say what to do, not only what to avoid
Positive instructions give Claude a clear target. Negative-only prompts leave too much room for guessing. Replace 'don't X' with the behavior you actually want. Use exclusions sparingly, after stating the main goal.
The refinement loop
Refinement loop: iterate with small follow-ups, do not restart every time. Context window carries all prior turns so you only describe what changes. Pinpoint one problem per correction for the most reliable result. Start fresh only when the whole direction has changed.
Reusable prompt templates
A template fixes the instructions and marks the variable parts as placeholders.. Use consistent placeholder notation such as [BRACKETS] or {{BRACES}} so slots are easy to spot.. Templates lock in prompt quality and cut repetition for recurring tasks.. Always specify the output format inside the template to get predictable results..
Question answering over a long document
Document first, question second. Precise questions get precise answers. Quote before answering reduces hallucination. Always verify the quoted passage in the source.
Prompting across languages
Claude mirrors the language of your prompt by default. Terminology consistency matters more than grammar. A glossary block anchors vocabulary across the whole conversation. In Claude Code, use --system to set a language rule for the session.
Summaries that keep what matters
Extractive: copies exact text; abstractive: rephrases in new words. State length explicitly (word count, sentence count, bullet count). State focus explicitly (audience, angle, format). Use extractive anchors for numbers and dates to prevent paraphrase errors.
Advanced chat (Projects, artifacts) and Cowork, the agentic coworker on your machine.
Mastering Claude.ai: Projects and artifacts
Projects = persistent context (instructions + docs) reused everywhere. Artifacts = editable, versioned deliverables in a dedicated panel. Put the recurring stuff in the Project, not in each message.
Claude Cowork: the digital coworker
Cowork = desktop agent that acts on your files (read/edit/create/organize). Same foundations as Claude Code, non-technical audience. You describe the goal; it plans and executes the steps alone.
Connectors, Scheduled Tasks, Computer Use, RBAC
Connectors = MCP bridges to your external services. Scheduled Tasks = fixed-time automation (watch, reports, consolidation). Computer Use = drive a GUI without an API; RBAC = who can do what in enterprise.
Projects in depth
Project knowledge is a persistent file library Claude reads in every conversation inside the Project. Custom instructions act as a standing system prompt, set once, applied automatically. New chats inside a Project inherit all knowledge and instructions without any copy-paste. Projects suit recurring workflows where the same context is needed repeatedly.
Custom instructions and styles
Custom instructions apply to every new conversation automatically.. Cover role, tone, format, and hard constraints.. Claude.ai uses profile-level instructions; Cowork uses project-level instructions.. You can override instructions for one session without losing the saved version..
Artifacts you can share
Artifact: output panel beside the chat for documents, code, or live apps.. Mini-app artifacts run HTML and JavaScript live in the browser.. The Share button creates a public link that works without a Claude account.. Remix loads a shared artifact into a new chat so anyone can modify it..
Cowork: acting on your files
Cowork is the desktop file agent, not the browser chat. It reads and edits local files you explicitly share with it. Actions are previewed before being applied. Best for writing, editing, summarizing, and organizing documents.
Cowork: planning multi-step tasks
Cowork shows you its plan before acting. Each step is a single discrete action in an agentic sequence. Confirmation gates pause execution before irreversible changes. A failed step surfaces an error rather than being skipped silently.
Connectors: Gmail, Drive, Calendar
Connector: an authorized link between Claude and an external service. OAuth grants access without sharing your password. Connectors are read-on-demand, not background surveillance. Revoke access instantly from Claude.ai Settings.
Computer Use, done safely
Computer Use lets Claude control a real computer as an agent. Prompt injection is the main attack vector: hidden instructions in external content. Always run Computer Use inside a sandbox (Docker, VM, or cloud desktop). Access is via the API using the computer, text_editor, and bash tools.
Claude on mobile and by voice
Claude mobile app supports voice dictation, images, and documents. Voice input is speech-to-text only: Claude replies in writing. Mobile is ideal for short tasks; coding workflows stay on desktop. Projects you create on Claude.ai are accessible on mobile.
Cowork everywhere: web, mobile, remote
Cowork expanded from desktop-only to web and mobile (iOS, Android) on July 7, 2026, in beta, starting with Max plan subscribers, rolling out over several weeks. Remote sessions run on Anthropic's servers and save to your Claude account, so scheduled tasks can run with no device online, and a task can start on one device and be picked up on another. Chat and Cowork share one unified home on web and desktop, with projects and artifacts living together across both. Over 90% of Cowork usage is not software development, and doubled usage limits run as a promotion through August 5, 2026.
The growing Claude app family
Claude Tag (June 23, 2026, beta, Team/Enterprise) brings Claude into Slack as a taggable teammate for multi-stage tasks.. Claude Science and Claude Desktop for Linux both launched June 30, 2026, expanding Claude to researchers and Linux users.. Claude Code integration in Chrome went GA in v2.1.198 on July 1, 2026; Claude Code Artifacts (beta since June 18, 2026) publish live HTML to a private URL.. The Microsoft 365 connector moved from read-only to full write access (email, calendar, OneDrive, SharePoint) on July 7, 2026..
The agent in the terminal. The loop, slash commands, CLAUDE.md, permissions.
What Claude Code is and the agent loop
Claude Code = code agent with tools (files, shell, git, web). Loop: goal -> think -> call a tool -> observe -> repeat. It acts and corrects autonomously, you give a goal not commands.
CLAUDE.md: the project memory
CLAUDE.md = project memory read automatically on startup. Commands, conventions, absolute rules, routing. These instructions override default behavior. /init generates a first draft to refine; short and sharp > sprawling.
The essential slash commands
/init generates CLAUDE.md, /clear resets, /compact summarizes. /agents, /mcp, /hooks, /review for advanced functions. Context reflex: /clear if you change subject, /compact mid big task. Custom slash commands in .claude/commands/.
Permissions and plan mode
Permissions: ask / accept-edits / plan / bypass. Plan mode: proposes an approvable plan before any action (big changes). settings.json + precise per-command allowlist. More autonomy => the CLAUDE.md written rules become the real guardrail.
Install Claude Code and first run
npm install -g @anthropic-ai/claude-code to install globally. Run claude with no arguments to authenticate on first use. Always launch from the project directory, not your home folder. Node.js 18 or higher is required before installing.
The prompt box: modes and steering
Escape interrupts a running task without losing context. Shift+Enter inserts a newline; Enter sends the prompt. --plan flag makes Claude Code show a plan before acting. Mid-task redirection: interrupt, then type a correction.
Pointing at files with @
@ reference reads a file directly from disk. Tab completion helps you find files quickly. Folder references let Claude scan a whole directory. No pasting means no copy-paste errors.
Running shell commands
Bash tool executes real shell commands. Permission prompt shown before every new command. Claude reads stdout and stderr to continue reasoning. Allowed list skips prompts for trusted commands.
Reading and approving edits
A diff marks removed lines with - and added lines with +. Surgical edits change only what is necessary. y accepts, n rejects, e opens the change for manual adjustment. --dangerously-skip-permissions bypasses all approval prompts.
Git from inside Claude Code
Ask Claude Code to summarise git status in plain English. Let Claude Code write commit messages following conventional style. Use natural language to create branches and pull requests. Claude Code will not force-push or delete branches without explicit instruction.
The task list
Task list: the live checklist Claude Code builds for multi-step jobs. Items cycle through pending, in progress, and completed states. You can add, skip, or reprioritize tasks mid-session with plain English. Blocked tasks surface immediately instead of being silently skipped.
Plan mode in depth
Plan mode is read-only: no files change until you approve.. Trigger with the <code>--plan</code> flag or the <code>/plan</code> command.. You can approve, edit, or abort before any write happens.. Best for multi-file tasks, risky refactors, or unfamiliar codebases..
Permission modes and bypass
Four modes: default, acceptEdits, plan, bypassPermissions. Set per-session with --permission-mode or per-project in settings.json. bypassPermissions removes all approval prompts. More speed always means less safety net.
The status line
Status line shows context usage, cost, and active model after every turn.. Context window fills up as the session grows; use /clear to reset.. Rate-limits fields are optional: the bar disappears when they are absent.. Customize the status line by editing statusline.cjs with plain Node.js..
/init and onboarding a repo
/init generates CLAUDE.md from a real scan of the repo. CLAUDE.md is read automatically at every session start. Review and edit CLAUDE.md: remove errors, add team rules. Re-run /init whenever the project structure changes significantly.
Keyboard shortcuts and vim mode
Ctrl+C cancels the running task without quitting. Ctrl+R searches prompt history by keyword fragment. /vim toggles modal vim editing for the input line. Escape + dd in vim Normal mode deletes the current input line.
Skills, MCP, sub-agents, hooks, plugins, agent teams. Where Claude Code becomes a platform.
Skills: teaching Claude a workflow
Skill = repeatable workflow in a SKILL.md, invoked by a slash command. The description drives automatic triggering. Packaged procedural knowledge, reusable. skill-builder: a skill to build skills.
MCP: wiring external tools
MCP = standard to wire external tools/data into Claude. MCP tools called like native tools; same tech as Connectors. Format /mcp__[server]__[prompt]. Pitfall: a project-scoped MCP only appears from the right folder.
Sub-agents: delegating in isolated context
Sub-agent = task delegated in isolated context, returns only its conclusion. Keeps the main context clean + enables parallelism. Types: Explore (read), Plan, specialized (review, audit). Basic block of workflows and agent teams.
Hooks: automating the lifecycle
Hook = automatic action on a lifecycle event. Executed by the harness, not the model: 'every time X' = a hook, not a preference. Format/lint, tests, secret blocking, CI webhook. Pierre: post-commit hooks to refresh Graphify.
Plugins and Agent Teams
Plugin = versioned bundle (skills + agents + commands + hooks + MCP), shareable. Pierre: superpowers, frontend-design, code-review, security-guidance, personal SEO. Agent Teams (Feb 2026) = several agents collaborating on sub-tasks. Scale: skill -> plugin -> agent team.
Author your own skill
SKILL.md lives in ~/.claude/skills/<name>/ (global) or .claude/skills/<name>/ (project). Frontmatter requires name and description between --- lines. Trigger: explicit slash command /name or automatic match on description. Skill body is plain Markdown: steps, rules, constraints, templates.
Discovering and installing skills
Skills live in ~/.claude/skills/ as SKILL.md files. Invoke with a slash command or a natural-language trigger. ECC (affaan-m/ECC) is the main community skill library. find-skills discovers and suggests new skills on request.
The MCP ecosystem
MCP is the open protocol for connecting Claude to external capabilities. Three primitives: tools (callable), resources (readable), prompts (reusable templates). Servers are registered in .claude/settings.json under mcpServers. Run /mcp inside Claude Code to list all active servers and their tools.
Connecting an MCP server
MCP servers add tools and resources to Claude Code without changing the model. Project scope keeps credentials and tools isolated to one repo. OAuth lets you authenticate with your real account instead of pasting a secret key. Use 'claude mcp list' to verify a server is connected and healthy.
Build your own MCP server
MCP (Model Context Protocol): open standard for custom Claude tools. stdio transport: Claude launches your server as a child process. Input schema: JSON Schema that validates tool arguments. Tool description: the text Claude reads to decide when to call your tool.
Sub-agent patterns
Sub-agents run in isolated context windows, blind to the parent session. Delegate when a task is independent, expensive, or parallelisable. Orchestrator plans and assembles; workers execute; reviewer validates. Every delegation prompt must be self-contained with all needed context.
Hook events: the lifecycle
PreToolUse runs before every tool call and can cancel it. PostToolUse runs after the result is returned. Stop fires once when Claude finishes its final reply. SessionStart fires once at the beginning of each session.
Writing a hook script
Hook scripts run at defined moments and receive a JSON payload on stdin.. Match tool_name to decide whether your hook applies to the current call.. Exit 0 allows, exit 2 blocks and surfaces your message to the user.. Print JSON with continue:true and stopReason to feed guidance back to Claude..
Plugins: bundling everything
A skill bundles commands, hooks, MCP servers, and agents in one directory. SKILL.md is the entry point Claude reads when the skill is invoked. User-wide skills go in ~/.claude/skills/, project skills in .claude/skills/. Installing a skill activates all its extension points without extra configuration.
settings.json in depth
Project settings.json overrides user settings.json for shared keys.. The allow/deny lists in permissions control which tools Claude can use without prompting.. The env block injects variables into every Claude Code session and subprocess.. Hooks (PreToolUse, PostToolUse, Stop) run shell commands at lifecycle events..
Output styles
--output-format json for machine-readable output. --verbose to expose tool calls and reasoning. Prompt directives override the default chatty style. Match output style to the consumer (human vs script).
Background tasks and web tools
run_in_background lets long shell commands run without blocking the chat. WebSearch finds sources when you do not know the URL yet. WebFetch reads a full page when you already have the URL. Combine them: search first, then fetch the most relevant result.
MCP grows up: the 2026-07-28 revision
The MCP core is now stateless: no initialize handshake, no Mcp-Session-Id header, client metadata travels in _meta on every request, enabling round-robin load balancing.. MCP Apps (sandboxed iframe UI) and the Tasks extension (long-running work) are now official parts of the protocol, not workarounds.. A formal deprecation policy (Active, Deprecated, Removed, 12-month minimum runway) and a mandatory conformance test suite under AAIF governance make MCP changes predictable.. Registry trust and registry size are different things: the official registry has about 2,000 vetted servers versus tens of thousands on third-party registries like Glama..
The skills library: a curated map
Skills stack since Claude Code v2.1.199 (July 2, 2026): /skill-a /skill-b task loads several at once.. /dataviz ships bundled since v2.1.198; everything else installs via git plugin marketplaces or huge third-party directories like SkillsMP.. Load process skills (brainstorming, debugging, verification) before implementation skills (design, coding).. Distribution is decentralized and unpoliced: audit third-party skills before installing them..
Chaining, tool use, multi-vendor composition (Frankenstein), citation, anti-hedging.
Chaining prompts
Split a complex task into a chain of simple prompts. Output of one link = input of the next; each link verifiable. Basis of workflows: a pipeline of specialized agents. Assign the right model to each link.
Tool use: giving the model hands
Tool use = Claude calls functions you define (the engine of agents). Clear description + strict parameter schema. Don't name the tool to the user; parallelize if independent. Schema-validated structured output > parsing free text.
Composing a system prompt: the Frankenstein case
Composing a system prompt = assembling the best rules from several sources. Pure prompt engineering, no fine-tuning. Priority rules at the top, declared as priority. Forbid by explicit list > ask vaguely; encode each incident into a rule.
Citation and anti-hedging in daily use
Citation: inline brackets, one source per bracket, max 3, no References section. Anti-hedging: no empty opening or opt-in closer. At most one clarification question, at the start, never at the end. If the next step is obvious, execute it.
Prompt chaining patterns
Prompt chain: a sequence of prompts where each output feeds the next step. Result passing: injecting a previous answer as context into the following prompt. Atomic prompt: a prompt with exactly one clearly bounded task. Draft-critique pattern: generate first, then review in a separate call.
The tool use loop in depth
Tool use loop: call, execute, read result, repeat or finish. Tool definition quality controls argument accuracy. Tool result clarity prevents hallucinated follow-up steps. The host environment runs the tool, not the model itself.
Structured outputs with a schema
A schema defines the exact shape (fields, types, required status) of the JSON you want back.. Tool use (function calling) enforces schema compliance at the API level.. Always validate the output programmatically and retry with the error message if it fails.. Flat schemas with explicit enum values produce the fewest errors..
Writing evals
Eval: a repeatable test set that scores prompt quality. Test set: fixed inputs paired with expected outputs or scoring rules. Pass rate: fraction of cases where the output meets the criteria. Regression: a behavior that worked before and silently breaks after a prompt change.
Meta-prompting
Meta-prompting: a prompt whose job is to improve another prompt.. Include context, the draft, and a specific instruction.. Chain critique then rewrite for sharper results.. Treat the output as a draft, not a final answer, and test it..
Guardrails and validation
Guardrails check model output before it is acted on. Format checks and schema assertions are the first line of defense. LLM-as-judge uses a second model call to validate the first. Apply stricter guardrails to irreversible or high-stakes actions.
Self-consistency and voting
Self-consistency: sample the same prompt N times, take the majority answer. Temperature above 0 is required so each run produces a different reasoning path. Voting filters noise without changing the model or the prompt. Cost scales linearly with sample count, so reserve this for hard or high-stakes questions.
Adversarial self-check
Adversarial self-check catches errors that a single response misses. Use an inline devil's advocate section or a separate critic message. Reset confirmation bias by treating the critic as a fresh perspective. Always run a synthesis pass to filter valid objections from noise.
Doubling effective capacity: KV-cache, masking, compaction, partitioning, quota.
The four context levers
1. KV-cache: stable prefix at the top, don't reorder the fixed part. 2. Observation masking: compact large tool outputs. 3. Compaction: summarize beyond ~70% usage. 4. Partitioning: push the bulky into isolated sub-agents.
Quota, throughput and model alternation
Two ceilings: cost in money AND throughput (tokens/minute). Quotas expire: the 4000 tok/min cap of this case study was lifted in July 2026. Countermeasures: less parallelism, low max_tokens/effort, retries, model alternation. Claude calls cheap; mostly watch throughput and external costs.
Audit your context budget
Context window: the total tokens Claude can hold in one session.. /compact summarizes history to free up space without losing the thread.. Limit reads to relevant lines only, not whole files.. Prompt caching (API) cuts repeated input cost to 10 percent on cache hits..
/compact and /clear
Context window fills as the session grows. /compact summarises and continues; /clear resets completely. Use /compact to stay on task, /clear to switch tasks. Files on disk are never touched by either command.
Prompt caching and the KV cache
KV cache stores intermediate token computations for 5 minutes. Cache-read tokens cost roughly 10 percent of normal input price. Cache-write surcharge applies on the first call that fills the cache. The cached prefix must be byte-identical to get a cache hit.
The Batch API for bulk work
50 percent token cost discount versus synchronous API. Independent rate limit: batch quota does not drain real-time quota. Asynchronous: submit now, retrieve results later. Best for hundreds of identical-shaped requests run offline.
Routing work to the cheapest model
Opus for hard reasoning, Haiku or Sonnet for repetitive tasks. Model routing cuts cost without sacrificing quality where it matters. Claude Code: /model to switch; API: set model per request. Sub-agents in a pipeline are ideal Haiku or Sonnet targets.
Counting tokens before you spend
Token-counting endpoint returns input_tokens without charging you. Output tokens can only be capped, not counted in advance. Prompt caching and the Batch API are the two main cost levers. Claude Code shows live cost per turn in the status line.
Rate limits and surviving a 429
429 = rate limit hit, not a billing error. Exponential backoff: retry after progressively longer waits. Lower max_tokens or effort to reduce per-call token spend. Batch API runs on a separate quota at 50 percent discount.
Observation masking
Observation masking removes stale tool output from the active context window.. The model still knows a tool ran and its exit status; only the raw text is hidden.. Mask large, one-time outputs (installs, past grep results) you have already acted on.. Over-masking reduces grounding and can cause the model to repeat or guess..
Rate limits 2026: new tiers, new tokenizer
Sonnet and Haiku rate limits matched Opus at every tier on June 26, 2026, and tiers consolidated from four to three: Start, Build, Scale.. Models since Opus 4.7 use a new tokenizer producing about 30% more tokens per text; re-benchmark max_tokens, cost estimates, and cache thresholds instead of assuming old numbers still hold.. Quotas expire: a real organization's 4,000-output-tokens-per-minute cap was lifted July 4, 2026, and measured limits jumped to millions per minute per model family.. Verify limits with a cheap 1-token API call reading the anthropic-ratelimit-* headers, and design workflows to degrade gracefully rather than break when a ceiling is hit..
Persistent memory, Obsidian, Graphify, Dream. Building a system that remembers and learns.
File memory: never lose anything again
Memory = folder of markdown files, one fact per file, typed frontmatter. MEMORY.md = one-line-per-memory index, loaded each session. Categories: feedback (how to work), project (state), reference (pointers). Update after each batch; store only the non-obvious, not what the code already says.
Obsidian: the navigable second brain
Wikilinks [[note]]: a network of notes, not a pile of files. MOC = thematic hub notes (feedbacks, projects, rules). Atomic, densely linked notes + graph view to see clusters and gaps. sync memory: create/update + weave links + add to MOC and index.
Graphify: querying a codebase instead of rereading it
Graphify: any folder -> persistent queryable knowledge graph. Query the graph (query/path/explain) instead of rereading 30 files. Up to ~71x fewer tokens than a reread. Index once, query often > reread on every question.
Dream: automatic nightly consolidation
Dream = automatic nightly memory consolidation (scheduled task). 4 phases: orient, gather, consolidate (merge + archive), verify. Respects the rules: archive never delete, clean index, prior backup. Practice feeds, Dream digests: a memory that stays alive.
Continuous learning: learning from your own practice
continuous-learning scans git, spots repeated patterns, proposes skills/rules. Your automations are already in your repetitions: extract them from data. Loop: work -> consolidate -> index (Graphify) -> extract (learning). Expert level: build a learning machine around Claude.
Atomic notes
One idea per file keeps retrieval fast and precise. Links between atomic notes replace duplication. Descriptive titles make notes findable without opening them. No orphans: every note connects to at least one other.
Wikilinks and maps of content
Wikilink: [[double-bracket]] link between notes. MOC (map of content): a curated hub note that indexes a topic. Backlinks: reverse index showing which notes reference a given note. Graph coherence: every new note linked to at least one MOC and MEMORY.md.
Types of memory
User memory is global, project memory is repo-scoped. Feedback notes capture corrected behaviour. Reference notes are lookup tables, not rules. Keep notes atomic and link them from MEMORY.md.
Recall instead of rereading
Query notes before opening source files to save tokens. Graphify maps a repo into a queryable node graph. Tier 1 recall, Tier 2 targeted slice, Tier 3 full read. Stale notes are the only valid reason to drop to Tier 3.
Piping conversations into the brain
claude-extract exports session JSONL files into the vault. Graphify builds a node graph linking sessions to projects and memory notes. PYTHONUTF8=1 prevents encoding errors on Windows during export. Graph queries replace full transcript reads, cutting token cost dramatically.
Nightly refresh
Schedule graph refresh before the dream pass, not after.. Use --print for headless (non-interactive) Claude Code runs.. Opus for reasoning-heavy consolidation, Sonnet for summaries.. Log every run so you can spot silent failures in the morning..
A pocket brain: Claude Code on Android, git-synced
Termux from F-Droid (never Play Store) + community installer fetching the official arm64 binary with SHA256 check; audit the script first. Auth via claude setup-token from the desktop into CLAUDE_CODE_OAUTH_TOKEN: subscription-covered; never a pay-per-token API key in your pocket. Vault cloned in Termux + symlinked as session memory; SessionStart pulls, SessionEnd pushes: desktop and phone share one brain. Survival kit: proot alias for the login EACCES bug, wake-lock against the phantom process killer, system ripgrep, commands on separate lines.
The one-hour assembly guide: engine, CLAUDE.md, Obsidian memory, git transport, hooks, curated skills and a self-maintaining heartbeat.
The map: what a structured Claude looks like
A structured Claude has seven components: engine, constitution (CLAUDE.md), memory (notes + Obsidian), git transport, hooks, skills, and scheduled heartbeat. Knowledge compounds only if it is written to files: chat context dies with the session. This module is the ordered copy-paste path; the extending and second-brain modules hold the theory. Everything lives in plain text (Markdown, JSON, scripts): versionable, inspectable, portable.
Install Claude Code and log in
Native installer: curl install.sh on macOS/Linux, irm install.ps1 on Windows; it auto-updates, brew/winget/npm variants do not. Log in with a subscription (flat fee) rather than a Console API account (per-token billing) for personal use; a stray ANTHROPIC_API_KEY can silently override the subscription. /doctor (alias /checkup) diagnoses install, settings, hooks and context-wasting extras; run it after every big setup change. ~/.claude/ is the home of everything: CLAUDE.md, settings.json, skills/, projects/.
Your global CLAUDE.md: a constitution, not a novel
~/.claude/CLAUDE.md loads into every session with top instruction priority: highest-leverage file of the setup. Structure: absolute rules first, then session-start routine, then one-line pointers to skills and notes. CLAUDE.md is a router: protocols live in exactly one owning file, never duplicated, or the copies drift. Keep it small (about 5 KB), archive before rewrites, and remember changes only apply to the next session.
Plug Obsidian into Claude's memory
Open Claude's memory folder ITSELF as the Obsidian vault: single source of truth, nothing to sync. Atomic notes with frontmatter (name, description, type), one fact per note. Wikilinks liberally plus MOC hub notes and the MEMORY.md index: no orphan notes, or they are never recalled. Multiple project memory stores unify into one vault via filesystem junctions/symlinks, no copies.
Version your brain with git
The vault becomes a git repo with a private remote: history, backup, multi-device sync. Before the first push: grep the vault for secrets (tokens, passwords, long hex) and redact; assume there is at least one. Exclude conversation exports, regenerable graphs and archives via .gitignore; the atomic notes and index travel. Protocol: pull at session start, commit+push after each memory update; conflicts merge by keeping both, never force.
Hooks that keep the structure alive
Hooks in settings.json run shell commands on lifecycle events (~30 events by mid-2026); SessionStart pull + SessionEnd push automate the vault protocol. No native idle event: emulate with a Stop hook that registers activity plus a 15-minute scheduled task that syncs sessions idle 30+ minutes via headless claude -p --resume. Self-triggering automation needs anti-loop guards: marker env var, already-synced stamps, a lock, and hard caps. Hooks load at session start (relaunch to apply), must stay fast and non-blocking, and deserve versioning like code.
Skills: install ECC and superpowers, curate hard
ECC (github.com/affaan-m/ECC, renamed from everything-claude-code): 278 skills, install via /plugin marketplace add + /plugin install ecc@ecc. superpowers (official marketplace): process discipline skills; its meta-rule: if a skill might apply, invoke it before acting. Curate hard: install the subset matching your real stack (the author kept 67 of 271), because every skill's description participates in matching and costs context. Third-party skills run with full agent permissions: quarantine-clone, read, grep for dangerous patterns, install only the audited folder.
The heartbeat: scheduled tasks, nightly dreaming, statusline
Scheduled tasks make the structure self-maintaining: daily conversation export (with secret redaction) and graph refresh, nightly headless dream consolidation, 15-minute idle-sync, weekly vault lint. The dream consolidates with two built-in safeties: dated backup before each run, and archive-never-delete for contradicted notes. All automation reports to one alerts note at the vault root: visible in Obsidian, unlike logs and unlike email. statusLine turns session JSON into a live dashboard; refreshInterval is in MILLISECONDS, and a too-small value can freeze the terminal.
The one-hour checklist
Seven phases, each ending with a PROOF: rules recited, note recalled, hook fired, skill triggered, dream ran overnight. Order matters: engine, constitution, memory, git, hooks, skills, heartbeat; each phase assumes the previous. If you cannot demonstrate the proof, the phase is not done, whatever the config says. The habit that outranks every tool: write durable lessons into the brain before closing the session.
Fan-out, pipelines, adversarial verification, judge panels. Putting fleets of agents to work.
Parallel fan-out vs pipeline
Parallel/fan-out: N agents at once + barrier, when you want everything together. Pipeline: each item travels the stages with no barrier (default for multi-stage). Barrier justified only if stage N needs the complete result of N-1. Mass agents in Haiku/Sonnet, synthesis in Opus.
Adversarial verification and judge panels
Verify each finding with other agents before keeping it. Adversarial: N skeptics refute; keep if the majority fails to refute. Multi-perspective: different lenses; judge panel: N scored solutions. Loop-until-dry for unknown-size searches; verify before believing.
Workflows: deterministic orchestration
Workflow = script that orchestrates sub-agents deterministically. Blocks: agent(schema), pipeline, parallel, until-count/dry/budget loops. For: structure, confidence (verify), scale (massive migrations/audits). Token-heavy: reserve for tasks that justify it.
Barriers vs no barrier
A barrier holds all downstream agents until every upstream agent finishes.. Skip the barrier when each result is independently actionable.. Unnecessary barriers serialize parallel work and waste time.. Quorum barriers (wait for N of M) are a valid middle ground..
Loop until dry
Dry-run loop: repeat until a round returns nothing new. Seen set: deduplicated record of already-processed items. Orchestrator dispatches; workers are idempotent. Always cap max rounds to prevent infinite loops.
Worktrees for parallel agents
git worktree add creates an isolated working directory on a separate branch. each parallel agent is pointed at one worktree so files never collide. the orchestrator merges branches after all agents finish. git worktree remove cleans up when done.
Dispatching parallel agents
Fan-out: launching independent sub-tasks simultaneously instead of sequentially.. Orchestrator: the parent agent that dispatches and later collects child agents.. Independence check: fan-out only works when sub-tasks share no dependencies.. Collect phase: merging or summarising all agent outputs after they complete..
Scaling fan-out to a budget
Assign models by task complexity, not by habit. Trim each agent's context to only what it needs. Cap max_tokens and agent count before launching. Use prompt caching for shared prefixes across agents.
Schemas for clean agent data
Structured output removes ambiguity between agents. JSON Schema defines the exact fields and types Claude must return. tool_choice forces a specific tool call on every request. Validate the schema immediately to catch errors before they propagate.
Resuming and caching a workflow
Prompt caching cuts cost by reusing stable context across API calls. Checkpoints save each step output so only changed steps rerun. Hash or timestamp the inputs to decide whether a checkpoint is still valid. Use --print for non-interactive claude calls inside orchestration scripts.
The completeness critic
Completeness critic: agent that finds missing content, not errors. Scope diff: comparing what the brief requested vs. what was delivered. Narrow role keeps the critic fast and testable. Output is a structured list fed back to the orchestrator.
Subagents now run in the background
Since Claude Code v2.1.198 (July 1, 2026), subagents run in the background by default and notify you on completion in the claude agents view.. The /agents wizard was removed in the same release; create subagents by asking Claude or by editing files in .claude/agents/.. Agent teams (v2.1.178, June 15, 2026) dropped TeamCreate/TeamDelete for one implicit team per session, with plan approval and lifecycle hooks.. Dynamic workflow size (v2.1.202, July 6, 2026) plus OpenTelemetry attributes workflow.run_id and workflow.name make orchestration runs configurable and traceable..
Mass fan-out that actually finishes
Never make one agent write an entire large deliverable in one response; fractionate by axis and have each agent write its own file to disk.. Orchestrators cap concurrency (about 16 agents at once, 1,000 lifetime per workflow as of July 2026); chunk bursts past roughly 80 agents into waves.. Verify by diffing expected files against what's actually on disk, not by trusting agent status claims; patch the 1-2 gaps by hand instead of relaunching everything.. Past about 50 independent API calls, consider the Batch API: separate rate-limit pool, 50 percent discount, asynchronous results..
Re-audit persisted workflows before relaunch
agent() without an explicit model inherits the RUNNING session's model, not the authoring session's: a persisted script relaunched under a bigger model silently upgrades every unrouted stage. Re-audit every persisted workflow before relaunch, even if it already ran: explicit model + effort on mechanical stages, chosen strong model on judge stages. A persisted automation is a snapshot of assumptions (model, quotas, paths, caps): pin what must not drift, re-verify what cannot be pinned. Keep a routing-table header comment with a last-audited date in every persisted workflow: turns the audit into a 30-second diff.
The model landscape, the refusal map, picking the right tool for each task.
The landscape: Claude, GPT, Gemini, and the rest
Families: Claude (code/reasoning/safety), GPT (ecosystem), Gemini (giant context), open-weights (local), Grok (permissive). Prompting techniques transfer: same next-token-prediction nature. CL4R1T4S: a collection of real system prompts + a Pattern Bank of 75+ patterns. Learning Claude = learning to talk to all LLMs.
Refusal map and tactical routing
Refusal Map = matrix of vendors x refusal categories (strict/soft/open). Tactical routing: for a legitimate task, pick the model with the right latitude. Declarative map, not behavioral: test for real; hard lines uncrossable everywhere. Legitimate, honest framing unblocks more than the choice of model.
GPT-5 and the OpenAI family
GPT-5 is OpenAI's flagship, competitive with Claude Opus on reasoning and multimodal tasks.. The OpenAI tier ladder: GPT-5, GPT-4o, o3/o4-mini (reasoning), GPT-4o mini.. Claude supports up to 200k token context; GPT-5 API caps at 128k in most configurations.. Route by task fit and cost, not by a single 'best model' verdict..
Gemini and very long context
Gemini Pro and Flash: up to 1 million token context window. Context window size matters most when input cannot be chunked. Claude tops out near 200 000 tokens, strong reasoning quality. Choose the model by task shape, not brand loyalty.
Open models: Llama, Mistral
Open-weights: parameters are public, self-hostable. Best for: privacy, high volume, fine-tuning, offline. Ollama serves Llama/Mistral locally via REST API. Trade-off: control and cost vs. frontier capability.
Running a model locally with Ollama
Local inference: model runs on your hardware, no data sent out. Ollama manages open-weight models and serves a local API. Tradeoff: privacy and zero cost per call vs. lower capability. Best for sensitive data, offline use, or very high call volumes.
Composing a multi-vendor system prompt
Extract the strongest rule from each vendor prompt. Merge rules into one system prompt without contradiction. Test the composed prompt against a real task before deploying. Owner rules always override vendor defaults.
Tactical routing per task
Tactical routing: matching model tier to task requirements. Opus for judgment, Sonnet for breadth, Haiku for speed. Four routing signals: stakes, novelty, output length, latency. Claude Code --model flag lets you switch per session or per call.
Refusal differences across vendors
Hard vs. soft refusals depend on vendor policy and operator context. System-prompt context is the legitimate unlock mechanism. Open-weight models have no enforced refusal policy. Route by task type: choose the vendor whose policy fits the use case.
Fine-tuning vs prompting
Prompting is fast and reversible; prefer it by default. Fine-tune only for scale, strict output format, domain vocabulary, or data privacy. Few-shot examples and RAG can replace fine-tuning in many cases. Fine-tuned small models cut cost at high request volume.
Concrete end-to-end recipes for everyday coding tasks.
Recipe: debug a failing test
Paste the full stack trace, not just the error message. Fix only the code that caused the failure. Confirm green before closing the task. One failing test at a time keeps the loop short.
Recipe: refactor safely
Write tests before restructuring, not after. Keep the test runner live so failures appear instantly. Refactor one concern at a time to isolate breakage. Paste test output into Claude Code so it can self-correct.
Recipe: build a feature test first
Write the test before the implementation. Confirm red before asking for green. Refactor only when tests are passing. One behaviour per test cycle.
Recipe: review a pull request
A diff shows added and removed lines across files in a PR. /code-review runs structured analysis on the current diff. --effort controls how deep and broad the review goes. --comment posts findings as inline GitHub PR comments.
Recipe: build a feature end to end
Scope the feature in one sentence before coding starts. Use /stop to interrupt without losing context. Verify with real test runs, not visual checks. Review the diff before every commit.
Recipe: fix a bug systematically
Diagnose root cause before writing a fix. Reproduce the bug in isolation first. Demand a 'why' explanation, not just a code change. Run a regression check after every patch.
Recipe: migrate or upgrade a dependency
Commit before you upgrade, so rollback is one command away.. Ask for breaking changes first, before touching any file.. Run tests automatically after the install, not as an afterthought.. Review the final diff yourself before merging..
Recipe: onboard an unknown codebase
Map structure and entry points before editing anything. CLAUDE.md is auto-loaded every session as a project briefing. Cover build, test, architecture, and off-limits rules in CLAUDE.md. Use /init to generate a starter CLAUDE.md automatically.
Recipe: generate and maintain docs
docs-as-code: treat documentation like source, keep it in the repo. --print flag runs Claude Code non-interactively and pipes output. git hooks and CI steps enforce sync automatically. scope prompts to specific files to keep cost and latency low.
Recipe: automate a repetitive chore
spot the repeating pattern before writing anything. separate fixed logic from variable inputs (parameters). save the result as a script or a ~/.claude/skills/ slash-command. review the execution log before confirming destructive steps.
Recipe: write and run a one-off script
Describe input, output, and runtime clearly. Claude Code writes, runs, and can delete the script. No editor or terminal knowledge required. Ask for a dry-run first on large or destructive jobs.
Recipe: explain confusing code
Use @filename to attach context without copy-pasting. Narrow the request to the specific function or block that confuses you. Ask for a glossary of jargon inside the same prompt. Request a real-world analogy for abstract or recursive logic.
The small high-leverage tricks that make a power user.
Resume and continue a session
--continue reopens the last session with no ID needed. --resume lists recent sessions so you can pick one. Reloaded context counts against the context window. Works across CLI, VS Code, and JetBrains.
Rewind: roll back safely
Use /rewind to open the checkpoint picker. Checkpoints capture both conversation context and file state. Rewind enables A/B experimentation without backup files. Git history is unaffected by a rewind.
Paste images and screenshots
Paste or drag an image directly into the Claude Code input. Use screenshots to describe bugs without copying error text. Vision works on Opus and Sonnet for best results. Design mockups can be turned into code from a single image.
Reference files fast
Drag a file onto the prompt to insert its path instantly. @ mention opens an inline picker and attaches file content. Tab completes partial paths in prompts and slash commands. Combining these three removes most typing when referencing files.
Run a command inline with !
! prefix runs a shell command from inside Claude Code's REPL. Output lands in conversation context so Claude can use it. Replaces manual copy-paste of terminal output. Large outputs consume context window tokens.
Save a memory with #
# prefix triggers memory save. CLAUDE.md stores persistent rules. Memories survive across sessions. Plain text, fully editable.
Interrupt and redirect
Esc = soft interrupt, keeps context. Ctrl+C = hard kill, session lost. /undo rolls back file edits after an interrupt. Redirect by typing your correction right after the interrupt.
Thinking keywords
think / think hard / ultrathink scale reasoning depth. more thinking costs more tokens and more time. use ultrathink only for genuinely hard problems. keywords work in terminal, editor chat, and web UI.
Make your own slash commands
Store commands as .md files in .claude/commands/. File name = command name. $ARGUMENTS receives what you type after the command. Project commands are git-tracked; home-dir commands are personal.
Manage extensions
/agents lists global and project sub-agents. /mcp shows live MCP server status and lets you restart servers. /hooks audits every event hook in the current session. Managers merge global and project settings in real time.
Headless mode and piping
-p / --print flag runs Claude non-interactively. Output goes to stdout, ready for piping. --output-format json for machine-readable results. Combine with shell loops to batch-process files.
Parallel sessions with worktrees
git worktree add <path> <branch> creates an isolated checkout. each worktree folder hosts one independent Claude Code session. name folders after tasks, not generic identifiers. --resume <id> reattaches Claude Code to a saved session.
Model selection and fast mode
/model to switch the AI engine mid-session. Opus: max capability, Sonnet: balanced, Haiku: fastest and cheapest. /fast toggles speed-first mode for the session. Match the model to the task, not the other way around.
/fast mode: paying for speed
/fast switches you to Opus and runs the same weights up to 2.5x faster, at double the per-token price. Requires Claude Code v2.1.36+; Opus 4.8 has been the fast-mode default since v2.1.154. Enabling fast mode mid-session re-bills your entire existing context at the uncached fast rate: decide before you start. Opus 4.7 fast mode is being removed July 24, 2026; Opus 4.6 fast mode is already gone and silently bills at standard speed.
Code review at three depths
/code-review reviews the current diff; effort low/medium gives fewer high-confidence findings, high and above widens coverage and may include uncertain ones. --comment posts inline PR comments, --fix applies findings straight to the working tree. /code-review ultra (ultrareview alias deprecated) runs a multi-agent cloud review with adversarial verification, on a branch or a given PR number; 3 free runs on Pro/Max then about $5-$20 per run as of July 2026. A finding is a hypothesis: reproduce it before refactoring, and match effort level to how risky the change is.
From the Agent SDK to scheduled cloud agents and CI.
The Claude Agent SDK
The SDK lets code control Claude as an autonomous agent, not just a chatbot.. query() streams assistant turns and tool-use blocks your program can intercept.. Headless mode runs Claude Code without a terminal UI, ideal for CI pipelines.. Permission declarations keep the agent inside a safe, declared scope..
Anatomy of an agent loop
Agent loop: perceive, decide, act, observe, repeat. Each iteration is called a turn. The loop ends on a final text reply or a stop condition. Bugs trace to one broken phase in the loop.
Defining tools an agent can trust
Tool name must be unique and self-explanatory. The description tells the agent when to call and when to skip. JSON Schema parameters need their own descriptions, not just types. Ambiguous definitions cause the agent to hallucinate parameter values.
Headless automation in scripts
--print flag exits after one response. --output-format json for machine-readable output. Pin model with --model to avoid silent upgrades. Exit code signals success or failure to the shell.
Claude in GitHub Actions
claude-code-action runs Claude Code headless inside a GitHub Actions container. Pass ANTHROPIC_API_KEY as an encrypted repository secret, never hardcode it. Match model to task: Haiku for labelling, Sonnet for reviews, Opus for deep audits. Claude posts results as PR comments or sets a check status to block merges.
Scheduled cloud agents
/schedule skill creates recurring cloud agent runs. Cron syntax defines the timing (e.g. daily, weekly, hourly). Agents run headlessly: no human in the loop during execution. Use list, update, and delete to manage existing routines.
The /loop pattern
/loop runs a prompt or slash command repeatedly inside a Claude Code session. Specify an interval (e.g. 5m) or omit it for self-paced execution. Each iteration is a full agent turn with access to all tools. Use /stop or Ctrl+C to cancel the loop.
Agents in isolated worktrees
One worktree per agent, one branch per worktree. /worktree create launches an isolated agent environment. Agents share the git object store but not the working tree. Merge branches sequentially after agents finish.
Production MCP and remote tools
MCP server exposes tools; MCP client (Claude Code) calls them. Use SSE transport for remote servers, stdio for local processes. Declare strict JSON Schema per tool to prevent malformed calls. Return structured errors so the agent can handle failures correctly.
The parallel execution mindset
Decompose into dependency-free sub-tasks before assigning work. Fan out: launch all independent sub-tasks simultaneously. Verify each branch output before merging. Synthesize: combine verified results into one coherent deliverable.
Adversarial verification at scale
Judge panels run the same task on multiple agents to catch errors. Majority voting picks the most common verdict across judges. Prompt diversity prevents all judges from sharing the same blind spot. Structured output labels make the reducer reliable and fast.
When not to use agents
Agents add cost and latency; one-shot calls are often enough.. Use an agent only when the number or identity of steps is unknown upfront.. Self-contained text tasks (summarize, translate, classify) are one-shot by nature.. Simpler pipelines are easier to debug and cheaper to run..
Secrets, permissions, injection, and verifying AI work.
Never paste a secret
Secrets (API keys, tokens) must never appear in any chat window. Store secrets in OS environment variables, not in code or chat. If a secret leaks, revoke and rotate it within minutes. Reference secrets by variable name so the value never leaves your machine.
Permission hygiene
Least privilege: grant only what the current task requires.. Project-level settings.json overrides global; use it first.. Broad Bash wildcards are the most common and most dangerous permission mistake.. Review /permissions at the start of every inherited project..
Prompt injection
Prompt injection hides instructions inside content the agent reads. Indirect injection comes from fetched external sources, not the user. Minimal tool permissions are the strongest single defense. Always confirm irreversible actions before the agent executes them.
Reviewing AI-written code
Read the diff before accepting any AI change. Watch for silent deletions, invented APIs, and scope creep. Never let --yes bypass review on security-sensitive files. Run git diff HEAD after every Claude Code session.
What leaves your machine
Requests send prompt text, attached files, and session history only. Claude Code reads local files on demand via tool calls, not silently. Secrets belong in environment variables, never in prompt text. API tier does not use your prompts for model training by default.
Archive, never delete
Move files to an archive folder instead of deleting them. Deletion is irreversible; archiving is always reversible. Tell Claude Code explicitly to archive, not remove. Keep archive folder structure mirroring the original paths.
Verify before you claim done
Always run the code before saying it works. Show the actual terminal output, not your reasoning. Use /verify in Claude Code to automate this check. Treat untested claims as unfinished work.
Avoiding hallucinated APIs
Hallucinated API: a made-up function the model presents as real. Always verify the package in its registry (npm, PyPI, crates.io). Always verify the method in official docs or source code. Runtime errors, not compile errors, are the usual symptom.
Responsible automation
Irreversible actions need a human checkpoint before execution. Dry-run or describe-first before any destructive command. Limit permissions to the minimum required for the task. Prefer reversible steps: archive, stage, stage-then-deploy.
Audit a skill before you install it
Snyk's ToxicSkills study (Feb 5, 2026) found 36.82% of 3,984 ClawHub skills had a security issue, 534 were critical, 76 were confirmed malicious, and 91% of those used prompt injection.. Two real Claude Code CVEs (Feb 25, 2026) let a malicious repo run commands via hooks before the trust dialog, or steal the API key by overriding ANTHROPIC_BASE_URL.. Since Claude Code v2.1.196 (June 29, 2026), claude mcp list and claude mcp get no longer auto-launch a project's MCP servers just to list them.. Protocol: quarantine and read before enabling, scan with uvx mcp-scan@latest --skills, check for network/env/credential access, rotate any secret a removed skill could have touched..
Calling Claude directly: messages, tools, streaming, batch.
The Messages API
Messages API: the HTTP endpoint your code calls to reach Claude. max_tokens controls the maximum length of Claude's reply. messages array holds the conversation as role/content pairs. ANTHROPIC_API_KEY must be set before any call will succeed.
System, user, assistant over the API
system parameter sets persistent rules for the whole request. messages array must alternate user and assistant roles. prefilling the assistant turn constrains Claude's first token. system outranks user when instructions conflict.
Tool use over the API
Declare tools as JSON Schema objects in the <code>tools</code> array. Claude returns a <code>tool_use</code> block; your code runs the action. Send the result back as a <code>tool_result</code> block to continue. Use <code>tool_choice</code> to control whether Claude must call a tool.
Streaming responses
Streaming sends tokens as they are generated, not after completion.. Server-Sent Events (SSE) keep one HTTP connection open for all chunks.. Each chunk carries a delta: the new text fragment to append.. Final token usage counts arrive only in the last event..
Prompt caching API
Add cache_control breakpoint to stable content blocks. Prefix must be 1024+ tokens to qualify. Cache hit costs ~10% of normal input price. Check usage.cache_read_input_tokens to confirm hits.
The Batch API
Batch API cuts token costs by 50% for asynchronous workloads. Each request in a batch carries a custom_id for result matching. Batch rate limits are independent from real-time rate limits. Results arrive as a JSONL file, not a streaming response.
Counting tokens
Token counting endpoint: POST /v1/messages/count_tokens. Context window: 200,000 tokens for Opus, Sonnet, and Haiku (as of mid-2026). Count before sending to catch overflows and forecast cost. Use max_tokens to cap output and control spend.
Model ids, pricing and migration
Use full versioned model ids, never bare aliases, in production.. Opus for quality, Sonnet for balance, Haiku for speed and volume.. Always run an eval comparison before migrating to a new model id.. Prompt caching and the Batch API are the two main cost levers..
Vision and PDF inputs
Pass images via base64 or URL in a content block with type:image. PDFs use type:document and media_type:application/pdf. Limits: 20 images per request, PDFs up to 100 pages and 32 MB. Vision works on all three current Claude model tiers.
Sonnet 5 on the API: what breaks, what wins
Sonnet 5 launched June 30, 2026: 1M context, 128K max output, Jan 2026 knowledge cutoff, intro pricing $2/$10 per MTok through August 31, 2026, then $3/$15.. Three breaking API changes: adaptive thinking defaults on, manual budget_tokens thinking is removed (400 error), and non-default temperature/top_p/top_k are rejected (400 error).. The new tokenizer produces roughly 30% more tokens for the same text than Sonnet 4.6, so re-run cost and context-budget estimates rather than reusing old numbers.. Opus 4.1 retires August 5, 2026; Opus 4.7/4.6/4.5 and Sonnet 4.6/4.5 are now legacy; dateless model ids are pinned snapshots since the 4.6 generation, not evergreen pointers..
Refusals, fallbacks and the Fable 5 contract
Refusals return HTTP 200 with stop_reason "refusal" and a named classifier, not an error code; unbilled if no output was produced. Prefer the server-side fallbacks parameter first, then SDK middleware, then manual handling; a fallback credit refunds the prompt-cache cost of switching models. Fable 5 always thinks (adaptive only, cannot disable) and never returns raw chain of thought; thinking.display defaults to "omitted". Fable 5 and Mythos 5 require 30-day data retention with no zero-data-retention option, a hard constraint for regulated builders.
Multi-step project patterns that combine everything.
Playbook: SEO and GEO automation
SEO audit then inject, never guess-and-patch blind. IndexNow pushes URLs to Bing instantly after a deploy. llms.txt and speakable JSON-LD are the GEO entry points. Batch API for bulk meta generation at half the cost.
Playbook: a content pipeline
Split the pipeline into five named stages so each prompt has one job. Always get an outline approved before asking Claude to draft. Use voice-matching as a dedicated step, not an afterthought. The review stage is a separate editor role, not a rewrite request.
Playbook: synthetic datasets
Batch API: bulk async endpoint, 50% cheaper, independent rate limit. custom_id ties each request to its source row. Validate JSONL output before using it for fine-tuning. Model choice (Opus/Sonnet/Haiku) trades quality against cost and speed.
Playbook: research with web tools
Fan out: run multiple searches in parallel rather than sequentially. Adversarial verification: actively try to disprove each claim before accepting it. Primary vs secondary sources: prefer original studies and official docs. Bracketed citations: link every factual claim to a numbered source.
Playbook: build a knowledge base
Ingest, dedupe, link, recall are the four KB operations. A shared schema (id, source, summary, tags, links) makes every step reliable. A lightweight INDEX.md keeps recall fast and token-cheap. Semantic deduplication flags near-duplicate content even when wording differs.
Playbook: mobile app dev
Expo Go for instant phone preview via QR code. EAS Build produces real binaries in the cloud. restart Metro with --clear after native installs. Claude Code handles scaffold, nav, API, and TS fixes in one session.
Playbook: multi-language deliverables
Single-source: one locked source drives all translations. Batch API cuts cost 50% and parallelizes all language calls. Consistency check: compare numbers and key terms across outputs. Versioned output files prevent silent drift over time.
Playbook: a shareable HTML deliverable
Single file, no external dependencies. Inline CSS, JS, and images as Base64. Validate offline before sharing. Avoid CDN links and runtime imports.
Playbook: a personal automation stack
Use --print and -p for headless, scriptable Claude Code calls. Hooks in settings.json automate actions at session lifecycle points. A second brain vault cuts context-reload cost by storing distilled memory. Combine all three layers for a stack that works while you sleep.
Playbook: turn a chore into a skill
Repetition is a signal: the third time is skill time. Skill files live in ~/.claude/skills/<name>/SKILL.md. Separate invariant steps from per-run variables. Call skills with a slash command, e.g. /my-skill.
Playbook: getting cited by LLMs (GEO)
Allow the named AI crawlers in robots.txt and declare your sitemap; block them and you are invisible to LLMs. Ship pre-rendered or noscript content: most LLM crawlers do not execute JavaScript. In llms.txt, link every entry to its actual deep URL, never the homepage, or nothing specific can be cited. JSON-LD helps indirectly at best (July 2026 verdict); the real lever is trusted off-site mentions, tracked monthly.
When things go wrong and how to recover.
When Claude goes in circles
Detect a loop by counting repeated identical attempts. Use /clear to reset context without losing files. Narrow scope to one file or one function. Explicitly forbid failed strategies before retrying.
Recovering from a bad edit
git checkout -- file to restore it to the last commit. git reset --hard HEAD~1 to wipe the last commit entirely. Ask Claude Code in plain English to undo or revert. Back up critical files manually before a big session.
Context got polluted
Context window fills up and degrades answer quality. /compact summarises, /clear wipes, fresh start resets everything. Re-explaining yourself is the first warning sign. Hallucinated file contents require a full fresh start.
A wrong or outdated API
Stale API call: code generated from an outdated spec. Ground Claude in the current official docs before writing calls. Use raw HTTP status codes to diagnose the failure category. Fetch the live OpenAPI spec with /fetch, then ask for a targeted patch.
You hit a 429
429 = rate limit hit, wait for the window to reset. Retry-After header tells you the exact wait time. Prompt caching and incremental reads reduce token spend. Batch API has a separate limit and costs 50% less.
A command hung
Ctrl+C cancels the active tool call and returns control. Wrap risky shell commands with the timeout prefix. Use run_in_background for long or blocking processes. /stop halts an agent loop without ending the session.
Undoing changes safely
git restore discards uncommitted working-directory changes. --staged un-stages without erasing edits. git reflog lists every HEAD position, including lost commits. always branch from a reflog hash instead of resetting hard.
When to start fresh
Repetitive loops signal context rot, not a code problem.. Use /compact to compress history before quitting.. A handoff prompt carries decisions without noise.. Three cascading tool failures is a reset trigger..
The interactive playground, the synthesis projects, and the practitioner's checklist.
The Playground: build your prompt
The Playground assembles a prompt by ticking the module 2 blocks. Exercise: rebuild 3 prompts from memory. Being able to write a good prompt from memory = module 2 learned.
Capstones: from beginner to expert
Beginner: a Claude.ai Project with instructions + a reference doc. Intermediate: Claude Code + CLAUDE.md + a task in plan mode. Advanced: a homemade skill with a good description; bonus MCP. Expert: a memory/ with an index, 3 woven notes, a consolidation rule.
The practitioner's checklist
Before prompting: real context + explicit about format/language/length. Data in tags, facts sourced, reason before hard tasks. Claude Code: CLAUDE.md, plan mode, /clear and /compact at the right time. Pipeline by default, verify before concluding, consolidate after each batch.
Capstone: ship a small feature
Use /init at the start of every new project session to orient Claude Code. Always review the plan before Claude writes any code. One feature per session keeps scope clean and commits reviewable. Verify in the running app, not just by reading the diff.
Capstone: build your second brain
Atomic notes: one idea per file, linked with wikilinks. CLAUDE.md loads project context automatically at session start. Sync after every session, not at the end of the week. MOC files give you a single entry point per topic cluster.
Capstone: a multi-agent review
Orchestrator fans out to specialist subagents in parallel. Each reviewer gets a narrow, role-specific prompt to avoid anchoring. Verification gates bad or incomplete outputs before synthesis. Synthesis deduplicates, ranks, and surfaces conflicts for human review.
Capstone: a content pipeline
Content pipeline: brief to publish in automated steps. Prompt chaining: feed one output as the next input. Claude Code CLI (<code>claude</code>) for file-based automation. Human review gate before final publish.
The graduation checklist
Self-assessment reveals gaps that reading alone cannot expose. Foundations must be automatic before practitioner skills are reliable. Model choice (Opus / Sonnet / Haiku) is a practitioner decision, not a beginner one. Agentic loops with checkpoints are the Advanced frontier for non-developers.
See sept-tools.com (industry)
See totemsauvage.com (art gallery)
InstallClaw