🧭 How to read this module
WAT is less a piece of software and more a way to organize any agentic project. You'll see the three layers separately (W, A, T), then the loop that makes everything improve on its own, the recommended folder structure, and—importantly—the cases where building WAT is overkill. You don't need to know how to program: the agent writes and fixes the scripts; you just need to understand the map.
Before opening each layer, see how they fit together. The markdown instructions say what to do; the agent reads these instructions, looks at the available tools, and decides which one to use; the tools in Python do the actual work. And there’s one detail that changes everything: when something goes wrong, the agent fixes the tool e updates the workflow — so the system gets better with every run.
Illustrative diagram — the manual (W) guides the brain (A), which uses the hands (T); what the agent learns from fixing an error goes back into the manual, so the system improves on its own.
🗺️ WAT overview
What it is
WAT is a simple acronym for three layers that together give your agentic project a a manual, a brain, and hands: Workflows (instructions), Agent (the coordinator) and Tools (the scripts). The idea isn’t a new technology—it’s a way to organize parts you already know so they work together predictably.
What is it?Agentic flow — a process in which an AI doesn’t just respond, but acts: decides on steps, calls tools, and corrects itself. Framework — here, a mental/organizational framework, not a program you install.
The analogy that sticks: imagine hiring a new assistant. You hand them a procedures manual (the workflows), it uses its own reasoning to decide what to do in each case (the agent), and has a set of physical tools on the workbench (the tools). Most agentic projects you’ll build fit this pattern — which is why it’s worth learning the vocabulary once and reusing it forever.
Why learn
Having a repeatable template means you don’t reinvent the wheel with every project. When WAT becomes your standard, anyone (including you three months from now) can open the folder and immediately understand what’s what.
- •Common vocabulary: you and the AI speak the same language about the project.
- •Repeatable structure: the same skeleton works for everything from a simple bot to a production agent.
- •Separation of roles: instructions, decisions, and execution happen in separate layers.
Key concepts
What to do, in markdown.
Decides which tool to use.
Scripts that execute.
Almost everything fits in it.
📄 W = Workflows (Markdown instructions)
What it is
The layer W are files of markdown instruction — plain text with headings, lists, and bold — which work as a job description or a SOP (standard operating procedure). Each workflow tells the agent what to do for a specific task: the objective, the input, the expected output, and the steps.
What is it?Markdown — a way to format text with simple symbols (`#` becomes a heading, `-` becomes a list, `**` becomes bold). SOP (Standard Operating Procedure) — a document that describes, step by step, how to perform a task consistently.
This is the layer that you also edits. Changing the agent’s behavior almost never means changing code—it means rewriting the workflow in clear Portuguese. A good workflow documents four things: the goal (the final result), the input (what it receives), expected output (format, name, where to save) and the steps in order. The more explicit you are, the less the agent has to guess.
📄 Skeleton: workflows/relatorio-semanal.md
# Relatório semanal de vendas ## Objetivo Gerar um PDF com o resumo das vendas da semana. ## Entrada A planilha vendas.csv na pasta temporary/. ## Saída relatorio-AAAA-SS.pdf salvo em temporary/, com total, top 5 produtos e variação vs. semana anterior. ## Passos 1. Ler vendas.csv com a tool ler_csv.py 2. Calcular totais e top 5 3. Gerar o PDF com a tool gerar_pdf.py
✅ Note: no code here — just structured natural language. The agent reads this and chooses the tools.
Why learn
Since the workflow is the layer that changes the most, mastering it gives you the greatest return. A well-written workflow helps the agent get it right on the first try; a vague one makes it ask questions (or worse, make the wrong assumption). Think of it as the briefing you’d give a competent person: clear enough to avoid confusion, concise enough not to be tiring.
Key concepts
Agent job description.
Simple text, no code.
Goal · input · output · steps.
Change behavior = make changes here.
🧠 A = Agent (the coordinator who makes decisions)
What it is
The layer A is the AI assistant itself — the coordinator, the system’s brain. It reads the workflows, sees which tools are available, and decides, at each moment, which tool to call and when. It's not a fixed script: the agent chooses the path, like a project manager who delegates each part to the right person.
What is it?Coordinator (orchestrator) — the component that doesn’t do the hands-on work but decides the order of things and who handles each part. Delegate — to hand off a subtask to the most suitable tool (or subagent).
Illustrative diagram — the agent doesn’t run a fixed script; it reads the manual and decides which hands to use for what’s in front of it.
Why learn
Confusing an agent with a script is the most common mistake newcomers make. A script always does the same thing in the same order; the agent reasons and adapts. That's why it can handle situations you didn't anticipate—and why you also need to give it good workflows (the manual) and good tools (the hands): it's only as good as what it has available to coordinate.
🎯 Practical tip
When the agent chooses the "wrong" tool, the problem is almost always in the workflow (ambiguous description) or in the tool name/description (doesn’t clearly say what it does). Fix the manual, don’t fight the brain.
Key concepts
The AI itself coordinates.
Not a fixed script.
Delegate to the right tool.
Handles the unexpected.
🔧 T = Tools (Python scripts, one task each)
What it is
The layer T are Python scripts that do the actual work. The golden rule: ideally, one tool does one job — scrape a website, generate a PDF, analyze a spreadsheet. These are the system's “hands,” which interact with the world (files, APIs, data).
What is it?Script — a code file that performs a task when run. Python — the most common language for these tools; you don’t need to know how to write it, because the agent writes and fixes it for you.
The point that takes away the fear: the agent writes and fixes the tools. You don’t need to know how to code—describe what the tool should do (in the workflow), and the agent produces the Python. Small, focused tools are easy to test (only one thing can go wrong), reuse (the same gerar_pdf.py serves multiple workflows) and fix (the fix stays isolated). A tool that “does everything” becomes a black box that no one—not even the agent—can really understand.
✓ Good tool (one job)
- ✓
raspar_precos.py— only reads the prices on a page. - ✓Clear input and output (takes a URL, returns a CSV).
- ✓Easy to test in isolation and reuse in another workflow.
✗ Bloated tool (does everything)
- ✗
fazer_relatorio.pythat scrapes, calculates, generates PDFs, and sends email. - ✗When it breaks, it's hard to tell which part failed.
- ✗You can't reuse pieces; it becomes a black box.
Key concepts
Each tool does one thing.
The agent writes for you.
Small = easy to check.
Serves multiple workflows.
🔄 The self-improvement loop
What it is
O self-improvement loop is WAT’s superpower. The agent runs a workflow, hits an error, diagnoses the cause, fixes the tool — and, most importantly, updates the workflow file so that error never again happen. With each run, the system gets smoother and faster.
What is it?Diagnose — find out why something failed, not just that it failed. Self-correction — have the agent apply the fix on its own (in the tool and the workflow), without you having to explain the solution.
Illustrative diagram — an error isn’t waste: it becomes a permanent improvement to the manual. That’s why WAT improves on its own with use.
Why learn
Without the loop, you fix the same error every week. With it, each failure is “paid for once”: the agent records the lesson in the workflow, and the system stops stumbling there. That’s what turns a fragile prototype into a reliable assistant—and the key is to insist that it update the workflow, don't just patch the tool on the fly.
The full loop, step by step
- 1Runs — the agent runs the workflow with the current tool.
- 2Error — something fails (unexpected format, empty field, API is down).
- 3Diagnoses — reads the error message and identifies the root cause.
- 4Fix the tool — adjust the Python to handle that case.
- 5Updates the workflow — records the lesson so the error doesn't happen again. Then it returns to step 1, more robust.
Key concepts
Finds the cause of the error.
Adjust the script.
Lesson becomes a fixed rule.
Smoother with every run.
📁 Folder structure (workflows/tools/temporary/.env)
What it is
WAT has a recommended folder layout that gives everything its place: a folder workflows/ (the Markdown manuals), a tools/ (the Python scripts), a temporary/ (intermediate and output files), an environment file .env (API keys and secrets, never shared) and the CLAUDE.md at the root, which guides the agent through the entire project.
What is it?.env — a file for storing secrets (API keys, passwords) separately from the code, so they never end up on GitHub. CLAUDE.md — the context file the agent reads first; it explains the project, its rules, and how the WAT layers are organized.
Illustrative diagram — each WAT layer gets its own folder; secrets stay isolated in .env, and temporary/ holds what's disposable.
🎯 Goal: build the project's WAT structure
no Plan Mode, crie um CLAUDE.md na raiz usando o framework WAT, com as pastas workflows/ tools/ temporary/ e um arquivo .env. Descreva cada camada (W, A, T) e as regras de operação.
✅ How to verify: check that the workflows/ tools/ temporary/ folders and the .env file were created, and that CLAUDE.md mentions the 3 layers.
📁 Expected result: project folder tree
projeto/ ├─ CLAUDE.md <- contexto: explica o projeto e o WAT ├─ workflows/ <- W: os manuais em markdown (.md) ├─ tools/ <- T: os scripts Python (.py) ├─ temporary/ <- arquivos intermediários e de saída └─ .env <- segredos (NUNCA versionar/compartilhar)
✅ Layer A (the agent) isn't a folder: it's the assistant itself, which reads all of this and coordinates.
Key concepts
The .md manuals.
The .py scripts.
Intermediaries and output.
Secrets isolated.
🚦 When NOT to use WAT
What it is
As important as knowing how to use WAT is knowing when not to use it. For a one-off task, an initial experiment, or a request simple enough to fit in one sentence, building the whole WAT structure is overkill—bureaucracy that costs time and context without delivering value. In these cases, just type the request.
What is it?One-sentence task — something you can describe completely in a single instruction ("convert this CSV to JSON"). Context — the conversation’s “memory space”; unnecessary structures fill it up for no reason.
✓ Use WAT
- ✓Task repeatable that you'll run many times.
- ✓Process complex, with multiple steps and tools.
- ✓Something that needs improve over time (self-improvement loop).
✗ Don’t use WAT
- ✗Request of a sentence ("summarize this text").
- ✗Task one-off, which runs once and is done.
- ✗Experimentation initial, still exploring the idea.
Why learn
People who learn WAT sometimes want to structure everything—and end up creating folders and workflows for things that could be handled with a direct command. Knowing when no using it avoids bureaucracy, saves context, and keeps you moving fast. The rule is simple: if it fits in one sentence, make it one sentence; if it will be repeated and scaled, it becomes WAT.
🎯 Practical tip
Always start with a direct request. When you notice you’re repeating the same request (or adjusting it every time), there it’s time to promote it to a workflow. Let the structure emerge from real needs, not enthusiasm.
Key concepts
Simple request, no structure.
Runs once, without WAT.
Promote it when you repeat it.
Just the right structure.
In the WAT framework, which layer decides which tool to use at each point?
📌 Module Summary
Next Module:
2.3 — MCP Under the Hood