---

date: 2026-06-23 tags: [harness, north-star, context-engineering, debugging] status: graduated graduated_to: docs/agents/glossary.md # north star → "Debug the harness first"

Most agent failures are configuration failures — debug the harness first

Symptom — the agent misbehaves (wrong output, missed step, loops) and the instinct is to blame the model, swap models, or pile on prompt pressure.

Root cause — the model is ~10% of the agent; the harness (instructions, rules, tools, memory, guardrails, context budget) is ~90%. So the usual cause is a configuration failure — a missing tool, a loose rule, a forgotten guardrail, context bloat — not a model defect. "AI amplifies whatever engineering culture it lands in"; a weak harness amplifies into weak behaviour.

Fix — when the agent misbehaves, suspect the harness before the model: walk the five pillars (context / tools / memory / guardrails / specialists) and find the missing or loose piece. qa-harness and find-harness-improvements are the tools.

Guard — pinned as the Debug the harness first corollary in the glossary north star (docs/agents/glossary.md), and in the always-on term index. Source: Addy Osmani, The New SDLC for vibe/agentic coding (see docs/agents/sources.md).