🪜 The five layers

The first layer is the one everyone knows: the prompt, the text you write asking the model for something. It’s also the layer where most people get stuck—when the agent does something wrong, the reflex is “let me rewrite the prompt.” Sometimes it works. Most of the time, it only puts off the problem.

Improving the prompt has diminishing returns quickly: the first improvements (be specific, give an example, ask for an output format) solve a lot. After a certain point, adding more instructions to the prompt stops changing the result. That’s a signal — not that you wrote poorly, but that the problem has moved elsewhere.

What to look at: the dashed line rises without breaking—each step sits on top of the previous one, not in its place. The glow appears only on the last step, "graph," which is the horizon of this module. Remember the order: it’s how you’ll diagnose where a broken agent is really stuck.

The second layer is the context: everything the agent “sees” when it acts—open files, conversation history, attached documentation, the output of a tool it just ran. The prompt is what you ask for; context is what it knows as it responds. They’re different things, and confusing them is the most common mistake after prompting.

Every model has a context window limited. When it fills up with irrelevant things — verbose logs, files nobody needs, repeated history — the model starts to "forget" what matters, even if the original instruction was perfect. The wrong context undermines a good prompt; no prompt is good enough to make up for a cluttered context window.

The third layer is the harness: the infrastructure around the model. Which tools it has (read a file, run a command, call an API), what permissions it has, how each tool’s output is captured and returned to the model, what happens when a tool fails (retry—automatically try again), and how much token budget the entire task has to spend.

Prompt says what; the harness says with what. An agent with a perfect prompt and a poor harness (no access to the right file, no permission to run the command that would solve the problem) gets stuck all the same—and no prompt rewrite will unblock it, because the problem was never in the text.

The fourth layer is the loop: how many times the agent tries and how it knows it’s done. That’s all of Track 2 condensed—discover, plan, act, verify, stop. This is the layer where you stop writing prompts and start design a cycle: it’s no longer about what to ask in a single call, but how the system behaves over several calls.

An agent can have a great prompt, clean context, and a well-built harness and still fail — because no one designed the stop condition, or because the verifier (the part that decides whether the result is good) is missing or weak. At that point, more prompting won’t help: what’s missing is loop design.

The fifth layer only makes sense after the other four: how many loops you have, and how they connect. A graph here is literally several loops (or nodes with no loops) connected by edges—the researcher sends work to the writer, the writer sends it to the reviewer, and the reviewer can send it back to the writer. Each of these is a node; the whole network is the graph.

Move up to this layer without mastering the four below it multiplies the problem instead of solving it. If an individual loop already has no clear stopping condition, putting three of those loops in a graph doesn't create three problems—it creates a combinatorial problem, because now each poorly designed loop can contaminate its neighbors.

The harness for ONE loop fits in a script: prompt input, context window, token budget, retry logic, output capture. You can write that in an afternoon. The harness for a GRAPH does all this is more: message routing between nodes, fault isolation for a node (one node going down must not take down the entire graph), state consistency between nodes (what one node knows must match what the next expects), dynamic node creation (the graph decides at runtime that it needs one more node), and observability of the entire graph.

Observability, here, means the ability to answer: which nodes ran, in what order, and with what latency (runtime). In a single-loop script, that question is trivial — it ran once, ran again, stopped. In a graph with parallel nodes and conditional routing, without instrumentation you simply don’t know what happened. That’s exactly why orchestration frameworks (tools that coordinate multiple agents/nodes) gain traction when the conversation shifts from loops to graphs: they solve this set of distributed runtime — a system where several parts run in a coordinated way, each able to fail independently of the others—instead of leaving each team to reinvent this by hand.

What to look at: compare the size of the two boxes. The box on the left has 4 responsibilities and fits into an afternoon’s work. The box on the right has 5 responsibilities — and each one of them, on its own, is an engineering project (fault isolation, for example, is the entire subject of classic distributed systems). That explains why “just adding one more agent” is never “just” that.

Meu agente faz <o que ele faz de errado> quando eu peco <a tarefa>.

Antes de sugerir qualquer mudanca, analise as cinco camadas NESTA ORDEM
e descarte cada uma explicitamente antes de passar pra proxima:

1. PROMPT — a instrucao em si tem ambiguidade real, ou ja e clara?
2. CONTEXTO — o que o agente "ve" no momento de agir esta limpo,
   ou tem coisa irrelevante competindo com o que importa?
3. HARNESS — ele tem a ferramenta certa, com a permissao certa,
   e a saida dela volta pra ele de um jeito util?
4. LOOP — existe condicao de parada e verificador? Ele sabe quando
   "terminou" de verdade, ou so para de tentar?
5. GRAFO — se ha mais de um agente/etapa, o problema esta na
   ligacao entre eles (roteamento, estado que vaza) e nao dentro
   de um unico no?

Para cada camada, diga "descartada" ou "e aqui" com uma frase de
justificativa. So recomende uma mudanca depois de passar pelas cinco.