Pitfalls, Anti-Patterns
& How to Avoid Them

Symptom: model keeps missing your intent. Fix: use the CRISP checklist (Context, Role, Intent, Structure, Proof).

Symptom: model invents APIs or file names. Fix: paste the actual file, or open it via a tool call.

Symptom: shipped code has silent bugs. Fix: always run tests and diffs before merging.

Symptom: bill spikes overnight. Fix: max_steps, max_tokens, and daily spend alerts.

Symptom: agent forgets what it just did. Fix: persist state to a file or DB every step.

Symptom: 4 agents when 1 would do. Fix: start with a single loop, split roles only when needed.

Symptom: bill spikes from unknown IPs. Fix: rotate keys, use secret managers, add .env to .gitignore.

Symptom: unit economics break. Fix: track cost per request, cache aggressively, route by task difficulty.

Symptom: confident but wrong. Fix: RAG with citations, temperature=0, verifier pass.

Symptom: agent follows instructions found in fetched web pages. Fix: label untrusted text, refuse contradictory system-level instructions.

Symptom: workflow breaks weekly. Fix: use Firecrawl or a hosted API, add tests, alert on empty results.

Symptom: regressions after every change. Fix: 20-task dataset + nightly run + pass rate dashboard.

Symptom: cannot debug production incidents. Fix: log prompt/response/tokens/latency for every AI call.

Symptom: one 5,000-word system prompt no one understands. Fix: split into role, rules, tools, examples — each in its own file.

Symptom: user sees stack traces. Fix: friendly retries, human handoff button, offline fallbacks.

Symptom: PII in third-party logs. Fix: redact, audit, sign DPAs, add opt-outs.

Symptom: nobody watches the dashboards. Fix: assign one person, weekly review, rotate every quarter.