| Multi-agent as the first architecture | Every handoff loses context, and coordination bugs read as model stupidity | One agent with the tools; split on tool set or trust level (Rule 1) |
| Tool that returns a stack trace, or nothing, on failure | The loop cannot distinguish "bad argument" from "service down" and retries identically until the cap | Failures as instructions: what broke, which argument, what to try (Rule 4) |
| Adding tools to fix a wrong-tool problem | Each tool added enlarges the schema block and the choice space; accuracy falls while cost rises | Merge overlapping tools, sharpen descriptions, or gate tools by phase (tools.md) |
| Dumping full tool output into the transcript | One large result poisons the window for the rest of the run and is re-sent every turn afterwards | Truncate at the tool boundary, return a handle (context.md) |
| Vector memory for everything | Recall returns similar, not true — stale facts resurface with high similarity and outrank the current one | Facts that must be right live in explicit state; recall is for the long tail (memory-design.md) |
| Testing an agent with one run per case | Nondeterminism means one green run and one red run are the same evidence | n runs per case, report the pass rate and its confidence (Rule 7) |
| Evaluating the final answer only | Passing with a lucky guess and passing by doing the work look identical | Score the trajectory too: tools chosen, order, retries (evaluation.md) |
| Chat transcript as the audit log | Reasoning text is not evidence — the model narrates actions it never took | Log tool calls and observed side effects; gate completion on the side effect |
| Unpinned model alias in production | The model changes under a fixed prompt and every metric moves at once with no deploy to blame | Pin the dated snapshot; treat a model bump as a release with an eval run (Rule 8) |
| Prompt improvements applied straight to production | The change that fixed one complaint regresses three unmeasured behaviors | Eval set first, then the change, then the diff in pass rate (eval_gate) |
| Retry loop with no jitter or budget | Synchronized retries hit the rate limit that caused them, and the cost cap arrives before the answer | Exponential backoff with jitter, a retry budget per task, and the failure surfaced (production.md) |
| Approval prompt that shows only the tool name | Humans approve send_email and learn later what it said | Approval shows the rendered arguments and the reversibility, or it is theatre (human-in-the-loop.md) |
| Secrets passed through the context window so the agent "has access" | Anything in the window can be echoed, logged, traced, or exfiltrated by injected content | Tools hold credentials server-side and take a reference, never a value (security.md) |
| An architecture or framework decision that lives only in the chat | Re-litigated every quarter by whoever is on call | artifacts/ with the date, the alternatives and what was rejected (memory-template.md) |
