⌖ AI Field Guide

Sourced determinations on AI engineering practices · last reviewed 1h ago

  1. Fixed manual budget_tokens thinking budget on every request outdated prompting reviewed 1h ago

    Setting a static thinking.budget_tokens value on every API request to control how much a model reasons before answering -- the original mechanism for extended thinking on Claude 4-era models.

    Superseded by adaptive-thinking-effort-control

    Why this verdict?

    Anthropic has deprecated this on Claude 4.6 models and removed it entirely on Claude 4.7+, where requests using type: 'enabled' now return a 400 error, in favor of adaptive thinking plus the effort parameter. Still required on models that only support extended-thinking mode (Opus 4.5, Haiku 4.5, Sonnet 4.5 and earlier), so not dead everywhere, but no longer the recommended path for new work.

  2. Adaptive thinking + effort control over a fixed manual thinking budget best practice prompting reviewed 1h ago

    On current reasoning-enabled Claude models, let the model decide whether and how much to 'think' per request (thinking: {type: 'adaptive'}) and steer depth with a coarse effort setting (low/medium/high), instead of hand-setting a fixed budget_tokens value on every call.

    Why this verdict?

    Anthropic's own docs mark the manual budget_tokens mechanism as deprecated on Claude 4.6 models and rejected outright (400 error) on Claude 4.7 and later -- adaptive thinking is the only mode going forward wherever it's available. Adaptive mode can also skip thinking entirely on easy inputs at lower effort levels, which a fixed budget can't do.

  3. Treat MCP servers and tool outputs as an untrusted trust boundary best practice security reviewed 1h ago

    When wiring an agent to MCP (Model Context Protocol) servers, treat tool descriptions, schemas, and tool-call results as untrusted input that can carry adversarial instructions ('tool poisoning', indirect prompt injection) -- scope each server to least-privilege credentials, pin/review tool definitions, sandbox local servers, and require human confirmation before sensitive actions.

    Why this verdict?

    This isn't theoretical: researchers have disclosed a steady cadence of MCP CVEs through 2026, including real prompt-injection bugs in an official Anthropic-maintained MCP server, and most organizations experimenting with MCP haven't put it through formal security review before reaching production. OWASP's MCP cheat sheet mitigations (least privilege, definition pinning, sandboxing, human-in-the-loop, treating tool output as untrusted) match what the incident writeups say would have helped.

  4. Eval-driven development with layered graders best practice evals reviewed 1h ago

    Build a small, real-failure-derived test set early (Anthropic suggests 20-50 tasks) and grade agent output with a mix of code-based graders (fast, deterministic, for checkable outcomes), model-based graders (rubric-driven LLM judges, calibrated against humans), and human graders (gold standard, used sparingly) -- then keep iterating the eval set as the agent matures.

    Why this verdict?

    Anthropic's own 'demystifying evals' guidance lays this out as field-tested methodology: early on, effect sizes are large so small samples suffice, and the bar shifts to harder evals and tighter calibration only once an agent starts saturating existing tests. The discipline matches current LLM-as-judge practitioner writing too -- judges carry position/length/self-preference bias and need the same calibration rigor as any other measurement tool.

  5. Choosing RAG vs. stuffing documents into a long context window contested rag reviewed 1h ago

    Whether to retrieve-then-generate (index a corpus, pull only relevant chunks into context) or put a whole document/corpus directly into a long context window is a live architecture decision: both answer 'how does the model get the knowledge it needs,' with different cost, latency, and reliability tradeoffs.

    Why this verdict?

    Sources genuinely disagree. Cost/latency data favors RAG heavily (cited near $0.00008/query vs. $0.10-6.75 for 100k-1M-token long-context calls, responding in under 2s vs. 30-60s); long-context proponents point to it beating chunk-based RAG on QA quality when the source is stable and fits the window. 'RAG is dead' and 'in defense of RAG' pieces are both circulating in 2026 with real evidence behind each -- the right call depends on corpus size/stability and latency/cost budget, not a universal winner.

  6. Contextual retrieval: context-prefixed chunks + hybrid search + reranking best practice rag reviewed 1h ago

    Before embedding/indexing a chunk for retrieval, prepend a short LLM-generated note situating it within the full document (e.g. 'this is from ACME's Q2 2023 SEC filing...'), then retrieve using both embeddings and BM25 keyword search together, optionally adding a reranking pass.

    Why this verdict?

    Anthropic reports this combination cutting top-20-chunk retrieval failure from 5.7% to 2.9% (49% fewer failures), and to 1.9% (67% fewer) with reranking added -- each layer contributes independently. It remains the reference approach for chunk-based RAG rather than having been superseded by something else.

  7. Orchestrator + isolated subagents for parallel or context-heavy work best practice multi-agent reviewed 1h ago

    A lead agent holds the overall task and spawns short-lived, narrowly-scoped subagents, each with its own clean context window, to do parallelizable research, context-heavy lookups, or specialized work, then returns only a compressed summary to the orchestrator.

    Why this verdict?

    Anthropic reports this winning specifically for parallelizable research, context isolation, and tool-set specialization -- their research system beat single-agent Claude by over 90% on their internal eval. But it's not a default: multi-agent setups use 3-10x the tokens of a single agent, and uncoordinated multi-agent setups have been shown to amplify errors far more than centrally-orchestrated ones. Anthropic's own advice is to start with one well-tooled agent and add subagents only once that proves insufficient.

  8. Designing agent tools as a deliberate contract best practice tools reviewed 1h ago

    Treat each tool exposed to an agent as its own design problem: namespace related tools under a shared prefix, consolidate multi-step workflows into one tool where that matches how the task is actually done, keep responses terse and high-signal (pagination/truncation, semantic names over raw IDs), and iterate against real evals.

    Why this verdict?

    Anthropic's tool-design guide frames tools as a contract between deterministic software and a non-deterministic reasoner, and reports that small wording and consolidation changes produced outsized gains on real evals -- consistent with their broader finding that ambiguity in a tool list becomes ambiguity in agent behavior.

  9. Structured external note-taking for long-horizon agent state best practice memory reviewed 1h ago

    Agents keep a persistent notes file (e.g. NOTES.md) outside the active context window to track long-running state -- progress, decisions, counters -- re-reading it as needed instead of relying on conversation history to hold that state indefinitely.

    Why this verdict?

    Demonstrated directly in Anthropic's 'Claude plays Pokemon' example, which tracked precise progress (e.g. exact level-ups) across thousands of steps via a notes file rather than in-context state, and recommended in Anthropic's context-engineering guidance as a standard long-horizon technique -- cheap, auditable, and it survives compaction and restarts in a way in-context state doesn't.

  10. Compacting context as a session nears its limit best practice context reviewed 1h ago

    As a long agent session nears its context-window limit, summarize older turns (and/or clear stale tool-call outputs) into a condensed form and continue, rather than truncating blindly or letting the session fail outright.

    Why this verdict?

    Anthropic lists compaction alongside just-in-time retrieval and note-taking as a standard technique for running agents past a single context window; clearing stale tool results is called out as especially low-risk since raw outputs are usually only needed briefly after the call. Caveat: recent research on a 'compaction cliff' finds naive summarization degrades sharply past a point, so what's kept vs. dropped should be deliberate, not automatic.

  11. Just-in-time context retrieval over upfront loading best practice context reviewed 1h ago

    Instead of pre-loading all potentially-relevant data into context, the agent keeps lightweight references (file paths, IDs, query params) and uses tools to fetch only what it needs at the moment it needs it -- e.g. Claude Code using grep/head/tail against a codebase instead of loading whole files.

    Why this verdict?

    Anthropic's 2026 context-engineering guidance names this as a core technique for long-horizon agents, alongside compaction and note-taking: preloading everything burns context budget on data that's never used and crowds out tokens the model needs for actual reasoning, mirroring how people use indexes/filesystems instead of memorizing whole corpora.

  12. Small, scoped skills loaded on demand best practice context reviewed 1h ago

    Splitting instructions into small, task-scoped files (skills) that are only loaded into context when relevant, instead of one static mega-file read every turn.

    Why this verdict?

    Keeps the model's working context focused on the task at hand, lets instructions be authored and updated independently, and scales to far more accumulated knowledge than a single file can hold.

  13. One giant CLAUDE.md read every turn outdated context reviewed 1h ago

    Putting all project context, conventions, and instructions into a single large CLAUDE.md (or system prompt) that is read in full on every turn.

    Superseded by progressive-scoped-skills

    Why this verdict?

    A single sprawling context file crowds out the model's working context, goes stale as the project changes, and can't be selectively loaded -- Anthropic's own engineering guidance now recommends small, scoped files/skills loaded progressively instead.