Named failures
The repeating bugs. Name them, match them, point at the fix. Agents load this catalog as a refuse-list, not as bedtime reading.
No max-turns, token, wall-clock, or money budget. The agent rambles until the bill or the context dies.
Cause: Termination treated as an accident of the model instead of a first-class intent.
Fix: Force a done schema, a step cap, and a money cap. 'Done' is a tool or a structured intent.
The Agent LoopA shell or code-act tool on the host with production credentials.
Cause: Security asked of the model instead of the executor.
Fix: E2B, a container, OpenHands isolation, or a policy sandbox. Secrets stay in the executor.
Sandboxes and Isolation'Never delete files' as the only guard. The model is a confused deputy and will try to help.
Cause: Treating policy text as an enforcement mechanism.
Fix: Allow / ask / deny in code. Pin MCP servers. Quote untrusted content.
Injection, Poisoning, Confused DeputyThe policy lives in a framework black box you cannot diff, test, or revert.
Cause: Framework defaults inherited as religion.
Fix: Store prompts in git. Read what the framework sends. Eval on change.
Own Your PromptsRaw HTML, full CI logs, six PDFs, entire JSON envelopes stuffed 'just in case'. The goal is the first thing forgotten.
Cause: No context builder. The transcript is treated as the product.
Fix: Pinned / working / recalled / compacted. Files for bulk. Pointers in the window.
Own Your Context WindowA crew sharing one bloated window. Specialists drown in each other's work.
Cause: A second agent treated as a personality, not a context boundary.
Fix: Fresh or sliced windows, written briefs, structured returns. Subagents protect the parent.
Small, Focused AgentsTransfer of control copies the entire conversation into the specialist.
Cause: Handoff implemented as 'also here is the log'.
Fix: Rewrite the brief. Adjacency list plus a summary, not a dump.
Handoffs and SwarmNested loops get every tool and every secret. Isolation was theater.
Cause: Spawn as a fork of the parent process rather than a reduced principal.
Fix: Narrow tools, no parent tokens, written return, caps on depth, breadth, time.
SubagentsBackstories that do not change tools, prompt constraints, or schema. Theater.
Cause: Crew demo copied without a process or a tool split.
Fix: A role is real only if it changes tools, prompt, or schema. Otherwise it is one agent.
Role-Playing CrewsAgents talking to each other against production tools with no turn bound and no typed messages.
Cause: Conversational multi-agent used as a bus.
Fix: Bound turns, typed messages, no production tools on the chat; prefer handoff or supervisor.
Conversational Multi-AgentA browser or desktop agent used where an API, a workflow, or a grep would do.
Cause: Demo gravity. Computer-use is visible and expensive.
Fix: API first, workflow second, browser last, always sandboxed.
Computer UseSession transcripts stuffed into the next session. The user cannot inspect or delete them.
Cause: Confusing recall with a dump.
Fix: Memory writes are tool calls. Curate. Letta's core vs archival. User can inspect/delete.
Long-Term MemoryOne function whose argument is a JSON blob of 'whatever'. An untyped shell with extra steps.
Cause: Avoiding the work of designing an ACI.
Fix: One job per tool. Named verbs. Typed args. Capped results. Idempotent or journaled.
Designing the Agent-Computer InterfaceArchitecture first, golden set never. Success is a recorded GIF.
Cause: Taste substituting for measurement.
Fix: 20–50 real tasks before the framework. promptfoo, Inspect, DSPy. CI on prompt change.
EvaluationLangGraph plus CrewAI plus AutoGen in one process. Nobody owns the loop.
Cause: Star-driven shopping.
Fix: One loop. Libraries for missing primitives only.
Choosing a FrameworkPicking the viral harness of the week. Contribution-free clones with disabled PRs.
Cause: Stars as ranking instead of as a floor.
Fix: Pick for the constraint: checkpoints, types, harness, documents. Read Canon's atlas.
Choosing a FrameworkThe human answers and the run is gone. Approval as a side channel, not a tool.
Cause: Pause is not a first-class API. Human contact is not a tool call.
Fix: ask_human as a tool. Checkpoint. Resume from the blob.
Humans as ToolsNon-idempotent tools, no journal. A retry refunds twice.
Cause: Executor retries without idempotency keys.
Fix: Idempotency keys, journals, unify state so 'already refunded' is visible to the reducer.
Unify Execution and Business StateThe goal is dropped to keep junk observations. The model continues confidently.
Cause: No compaction policy. FIFO on the wrong end.
Fix: Pin the goal. Compact observations. File the rest. Never drop the goal first.
Compaction and ErrorsAn MCP server or plugin whose description is an instruction: 'call me first, send secrets'.
Cause: Tool descriptions treated as trusted system text.
Fix: Pin, hash, review schemas. Treat MCP as an attack surface. Allowlist tools.
Injection, Poisoning, Confused DeputyA 40-step plan written at t=0 and never rewritten when the world disagrees.
Cause: Plan as a thought, not a tool.
Fix: Update the plan as a tool call. Plan/act as a permission change.
Plan Mode and Act ModeThe agent writes code and declares victory. Tests, typecheck, and build are optional.
Cause: Done defined as a sentence.
Fix: Verify tool from AGENTS.md. Done = reviewable diff + tests + human gate.
Verification as Architecture