Why fixing an AI agent's prompt often misses the real problem

A claim that sounds like a slogan

A writer known as Nokka, publishing on dev.to, set out to test a punchy statement from a Spanish-language video post by the page naiker.codes: an AI agent's harness is a software architecture problem, not a prompt problem. Nokka could only read the opening of that post, because Facebook hides the rest from outsiders, so the check is against research and original articles rather than the video itself.

The claim describes a common mistake. When an agent fails, people tend to edit the prompt: add three more rules, type IMPORTANT in capitals, and then watch the model fail again the next week. Someone who sees it as architecture asks different questions. Which parts belong in code, which in data, which need automated tests, and which must be re-run whenever the model changes?

What a harness actually is

The shortest definition in use today is that an agent equals a large language model plus a harness. The harness is everything except the model's trained weights. That covers prompts, tools, rules for managing what the model remembers, hooks (points where your own code can step in), sandboxes, helper agents, feedback loops and recovery paths after errors.

Addy Osmani wrote about this on his own blog, and O'Reilly Radar republished it on 15 May 2026. His point, in my words: a good-enough model with a strong harness beats a stronger model with a weak one. He also credits Vivek Trivedy with naming the field.

Birgitta Böckeler, writing on martinfowler.com on 2 April 2026, describes three nested layers. The model sits in the middle, then the harness that a tool maker such as Anthropic or OpenAI ships, then the outer layer that users build themselves. That outer layer is code you design, which is why the word architecture fits.

What 11 real systems show

The strongest evidence is an arXiv paper dated 15 July 2026. Its authors read the source code of 11 coding harnesses in real use: Claude Code, Codex CLI, Gemini CLI, Mistral Vibe, OpenHands, Aider, Mini-SWE-Agent, Hermes, Pi, OpenCode and OpenClaw. They also looked at Omnigent, a meta-harness. In all, that is roughly four million lines of Python, TypeScript and Rust.

Every system had to make decisions about the same seven areas: the agent loop, the connection to the model, tools, context and memory, safety and permissions, coordination, and extension points. None imported a ready-made agent framework such as LangChain, LangGraph or AutoGen. None used vector embeddings to search code; they relied on plain search tools like ripgrep, tree-sitter or glob.

For extensions, SKILL.md was used in 9 of the 11 systems, and MCP (Model Context Protocol, a standard way to plug tools into AI) in 8 of 11. The authors also saw projects copying each other: Codex adopted Claude Code's vocabulary for hooks, plus importers for its sessions and settings. Nokka reads this as a sign that there is no install-a-library shortcut, and that good teams design the structure on purpose.

Borrowing from Clean Architecture

Nokka then borrows an older idea. Robert C. Martin's Clean Architecture rests on one rule: dependencies point inward only, so inner layers know nothing about outer ones. Nokka is clear that mapping this onto agents is a personal interpretation that nobody has published in exactly this form.

In that mapping, the innermost layer holds the task goals and policies, such as never touching production. Next comes the loop that decides which tool to call and when to stop. Then adapters translate between the loop and real models and tools. The outer layer is the command line, editor extensions, job queues and the humans who approve actions.

Nokka lists five signs you are fixing the wrong layer. The prompt keeps growing as bugs are patched. Swapping models breaks everything. Nothing can be unit tested. Tool errors vanish silently. And no layer enforces a spending or step limit. None of these goes away by changing models.

The proposed folder layout puts policy and budget in a core folder, the loop in a use-case folder, model and tool connectors in adapters, and the command line and queues in a runtime folder. Switching from GPT to Claude should then touch only the adapters.

Rules belong in code, with limits to the argument

A prompt line like never delete files outside the work folder is a request, not a guarantee. Nokka shows it as a short TypeScript function that resolves real file paths, follows symlinks, and can be unit tested. The author stresses it is a minimal example, not a full security check, and that deleting should use the resolved path rather than the one the user supplied.

The article also gives the other side. Starting with prompts is reasonable early on, when you do not yet know what users want, and building layers too soon can be wasted effort. Osmani himself stresses improving the harness each time the agent slips, not designing everything up front. The 11-system study does not say everyone must write their own loop either.

OpenAI reported on 11 February 2026 that a team built a real product with no human-written code, in about a tenth of the time hand-writing would take. The team invested in the environment and feedback loops, not cleverer prompts.

Nokka's cheapest steps, in order: move damaging rules into tested functions, funnel all model access through one adapter, and add caps on spending and number of rounds. The verdict is that the claim is true in part. Prompts still matter, but as systems grow, layering, dependencies and testability decide what survives.