concept
Two-way door
A decision you can walk back through. Amazon's Type 1 / Type 2 split, applied to agent delegation: reversible and contained goes to the agent now, near-irreversible stops for a human.
decision-makingagentsplanningrisk
Notes
Short, self-contained notes - one idea each: rules, snippets, and concepts from working with LLMs and agents. Cross-linked and kept current. Long-form pieces live in Articles.
[NOTES: 31]Showing 1-12 of 31
concept
Auto memory
Auto memory is a per-repository directory Claude Code writes for itself, outside your repo and outside version control. Only the first 200 lines or 25KB of MEMORY.md load per session; topic files load on demand.
claude-codeauto-memorycontextsettings
rule
Knowledge vs rule
Before choosing a layer, ask whether a fact needs to be known or followed. Knowledge tolerates a probabilistic layer; a rule that has to hold every time belongs in a check the model does not get a vote on.
claude-codeclaude-mdauto-memoryhookscontext-engineering
concept
Agentic loop
Claude Code runs a gather → act → verify loop: startup load fills context before you type, then file reads and tool output pile up as the loop runs - compaction, /clear, and subagents are the levers for what sticks.
claude-codeagentic-loopcontext
snippet
Batch submit pattern
Batch processing cuts every token 50% with a 24h SLA and stacks with prompt caching to ~95% off cached async work - same model quality, asynchronous delivery.
costbatchingcachingapi
snippet
Cache-read verifier
Fire the same request twice; if cache_read_input_tokens is zero on call 2, the prefix is changing or under the model minimum. Verify before celebrating cache savings.
cachingcostprompt-cachingdebugging
rule
Effort vs fast mode
Fast mode buys up to 2.5x speed on Opus for a flat $10/$50-per-million-token premium with zero quality change; a lower effort level cuts tokens - and sometimes quality. They stack, they do not substitute.
claudeeffortfast-modecost
rule
Hook over prose
CLAUDE.md is advisory text the model re-weighs every turn; a PreToolUse hook that exits 2 is deterministic code the harness enforces. Every rule you can express as a check should stop being a sentence.
claude-mdhooksharnessagents
snippet
Observation masking
Observation masking replaces older tool outputs with a placeholder so the record of what the agent tried survives but the raw bytes do not - JetBrains Research cut agent cost over 50% vs unmanaged context with no solve-rate drop.
contextcostagentstokens
rule
Output tokens never cache
Output tokens cost ~5x input and never cache - cut free-form prose first. Rewriting inside a cached prefix mid-session can raise the bill, not lower it.
costtokensoutputcaching
snippet
Permission rules block
Permission rules use ToolName(specifier) in allow and deny arrays - a bare tool name in deny disables it entirely. Pair with OS sandboxing; Read/Edit deny alone does not stop arbitrary subprocesses.
claude-codepermissionssecuritysettings
rule
Plan mode decision tree
Use plan mode when the approach is uncertain, the change spans multiple files, or the code is unfamiliar. Skip it for one-sentence diffs - typos, renames, single log lines.
claude-codeplan-modeworkflow
snippet
PreToolUse read-only hook
Plan mode's read-only promise is prompt reinforcement, not a hard tool lockdown. A PreToolUse hook that blocks Write and Edit when permission_mode is plan makes it actually read-only.
claude-codeplan-modehookssecurity
concept
Read-mutate permission split
Claude Code ships 42 built-in tools; only 13 ask for permission. Reads (Read, Grep, Glob, LSP, Agent) run freely; mutations and external calls (Bash, Edit, Write, WebFetch, WebSearch, …) ask.
claude-codetoolspermissions
concept
Refusal as API contract
Fable 5 safety classifiers return refusals as HTTP 200 with stop_reason refusal - every integration needs refusal handling and a fallback path, not only error handling.
claudefablerefusalsapi
concept
Sandbox ladder
OS-level Bash sandboxing cut Anthropic's permission prompts ~84%, but /sandbox only wraps Bash. Climb the ladder - sandbox-runtime, container, VM - when file tools, MCP, or unattended runs need a real boundary.
claude-codesecuritysandboxingpermissions
concept
Startup tax
Startup tax is the tokens loaded before your first prompt - system prompt, CLAUDE.md, MCP tool names, skill descriptions, and auto memory - paid on every new session and competing with the task on every turn.
claude-codecontextclaude-mdtokens
snippet
Stop hook verify-done
A Stop hook that demands proof of completion - named check, exit code, real output - blocks the agent from ending the turn without verification. Mechanism, not a request.
hooksharnessclaude-code
rule
Verify before done
Done means a named check passed with a real exit code - not the model saying it is done. Enforcement is a Stop hook, so it holds when session discipline decays.
harnesshooksevalsclaude-code
concept
Vibe coding vs agentic engineering
Google's 2026 SDLC whitepaper draws the line at verification, not AI use - vibe coding is casual prompts with does-it-seem-to-work checks; agentic engineering wraps the same agent in specs, evals, and CI gates.
vibe-codingagentic-engineeringharnesssdlc
concept
Worker-tier routing
Route the architectural decision to a frontier planner and the implementation to a cheap executor - DeepSeek V4 Flash at 1/89th of Opus 5 output cost only works when the plan is complete.
model-selectioncostagentsrouting
concept
Last-mile deployment
Last-mile deployment is adapting a working product to a customer's real systems until the outcome they paid for lands - the gap Forward Deployed Engineers close.
fdeagentsdeploymententerprise
rule
Cache-stable prefix
Put only byte-stable content before the prompt-cache marker - system prompt and tool schemas first, timestamps and per-request context after - or every later call pays full input price.
cachingcostprompt-cachingtokens
concept
LLM-as-a-judge
LLM-as-a-judge scores another model's output with a fixed rubric - use DAG for clear pass/fail, G-Eval for subjective quality, QAG for fact checks; cap an agent pipeline at ~5 metrics.
evalsllm-as-judgeagentsquality
concept
Claude Code skill composition
Claude Code skills compose through explicit Skill-tool calls between separate files, not a dedicated sub-skill primitive - disable-model-invocation blocks that call path too, not just autonomous triggering.
skillsclaude-codeagentic-engineeringsubagents
concept
Context engineering
Context engineering is curating what enters the model's context window each turn, rather than relying on a bigger window to absorb the clutter.
contextclaude-codetokens
rule
The /goal evaluator only reads the transcript
Claude Code's /goal evaluator is a prompt-based Stop hook that doesn't call tools, so any proof of completion - test output, an exit code, git status - must be surfaced in the conversation or it can't be judged.
claude-codegoalhooks
concept
Verifiable completion condition
A verifiable completion condition is an autonomous-loop stop rule with a single measurable end state the model can prove from its own output - the difference between a loop that terminates and one that spins.
claude-codegoalagentsautonomy
rule
Keep CLAUDE.md to universal instructions
Put only universally applicable instructions in CLAUDE.md; task-specific content raises the odds an agent treats the whole file as noise and ignores it.
claude-mdclaude-codecontext-engineering
concept
Lost in the middle
Language models use information at the start and end of a long context far more reliably than the middle - recall drops well before the token limit.
contextretrievaltokens
concept
Subagent context isolation
A subagent runs in its own context window and returns only a summary, keeping heavy intermediate tokens out of the parent conversation.
subagentsclaude-codecontextmcp