The WAT framework organizes any agentic automation into three layers. The diagram below shows how the agent reads the workflows, chooses the right tools, and runs the self-improvement loop that makes the system more reliable with every run.
Illustrative diagram — conceptual recreation of the WAT framework, not a real screenshot.
💻 On-Demand Assistant (Local)
Before thinking about putting anything on the internet, it's worth using the coding assistant as a on-demand personal assistant, triggered from your own machine. It researches, builds files, and gets smarter with each use — and it all happens locally: no hosting or deployment at this stage. Watching the agent work close to you first builds intuition before adding the complexity of production.
💡 The core idea
The agent is both a researcher and a builder: it reads sources, generates files, runs them, and improves them. In this track, two example projects recur—a research workflow and a slide generator—to reinforce the concepts without needing any server.
- •Local first: everything runs on your machine, with no deploy.
- •On demand: you trigger it when you need it; it does the work and comes back.
- •Gets better: each use refines the workflows and tools.
🎯 Practical tip
Start small and observe. Before automating end to end, run a simple task and watch the agent reason — that initial observation is what gives you the confidence to trust it with bigger tasks.
Reads and gathers information.
Generates files and code.
No hosting yet.
Smarter with every use.
🎯 What Agentic Workflows Are
In a traditional automation, you connect and configure each step; if something breaks, you fix it. In a agentic workflow, you tell the agent the outcome you want, not how to do it—and it reasons, adapts, asks clarifying questions, and self-corrects when something goes wrong. The analogy is simple: instead of cooking by following a recipe, you ask an experienced cook for the finished dish.
✓ Agentic mindset
- ✓“Turn these notes into a clean, structured document.”
- ✓Let the agent decide the sequence of steps.
- ✓Trust that it adapts the route when it encounters an obstacle.
✗ Recipe Mindset
- ✗“Open the file, read line 1, then line 2, format it like this…”
- ✗Prescribe every micro-step of the process.
- ✗Expect it to follow blindly without reasoning.
🍽️ The restaurant analogy
You don’t go into the kitchen to teach the chef how to chop an onion. You order “a medium-rare steak” and trust their expertise. With agentic workflows, the outcome is the order; the agent is the chef who knows the way.
You describe the end.
The agent decides the steps.
Changes course if needed.
Fixes what breaks.
🎲 Deterministic vs. Nondeterministic
Traditional automation is deterministic: the same input always produces the same output — "boring is beautiful," predictability is a virtue. Generative AI is non-deterministic by nature: the same input can produce different outputs because the agent reasons through alternatives midway through the process. That’s not a flaw to fix — it’s how the tool works.
| Aspect | Deterministic | Non-deterministic |
|---|---|---|
| Output | Always identical | Can vary |
| Example | Classic automation (n8n) | AI agent |
| Virtue | Predictability | Creative adaptation |
🎯 Practical tip
Don’t compare two runs side by side. If the structure or names change between runs, that’s expected. Evaluate the result — does it meet the goal? — instead of requiring an exact reproduction.
Traditional repeats the same way.
AI can change the output.
Chooses between alternatives.
Variation isn't an error.
📋 WAT — W = Workflows
The framework’s first layer is the W for Workflows: instruction files in markdown, written in natural language with headings, bullets, and bold text. They work as a job description or SOP (standard operating procedure) — they tell the agent what to do, what the input is, what output to expect, and which steps to follow. Since they are files, they persist and can be reused for similar future tasks.
# Workflow: resumir notas ## Objetivo Transformar notas brutas em um documento estruturado. ## Entrada Arquivo em temporary/resources/notas.txt ## Saída esperada Documento com: decisões · ações · próximos passos ## Passos 1. Ler o arquivo de notas. 2. Extrair e agrupar por seção. 3. Gerar o documento via a ferramenta de conversão.
📑 What a good workflow declares
- •Objective: the final result, in one sentence.
- •Input and output: where the data comes in and how the result should come out.
- •Steps: the sequence in natural language, without code.
Natural language.
Like a job description.
Saved in the project.
Works for future tasks.
🤖 WAT — A = Agent
The second layer is the The Agent one — the coding assistant itself. It is the brain and coordinator: reads the workflows, sees the available tools, and decides which one to use, when, and with which parameters. Think of a project manager who delegates: they don't do the hands-on work of each tool, but orchestrate everything so the goal is achieved.
🧭 What the agent does
- •Reads: opens the workflows and CLAUDE.md to understand what needs to be done.
- •See: notices the tools and MCPs available in the project.
- •Decide: chooses the sequence and tools to get the result.
The agent as project manager
Reads the "job description"
The agent opens workflow files to understand the task, like a manager reads the brief before delegating.
Inventories the tools
It checks which scripts and MCPs are available — the “team” it can call on.
Delegate and orchestrate
Chooses the right tool for each step and chains the work until delivering the result.
The system coordinator.
Understands the task.
Know what you can use.
Chooses the route.
🛠️ WAT — T = Tools
The third layer is the T for Tools: Python scripts that do the actual work. Ideally, each tool does just one job — scrape a website, generate a PDF, analyze data. The key point: the AI writes and fixes these tools, so you you don’t need to know how to code. You just need to know they exist and what each one does.
✓ Good tool
- ✓Do one well-defined job.
- ✓It has clear input and output.
- ✓It's reused by multiple workflows.
✗ Avoid
- ✗One giant tool that does everything.
- ✗Try reading or editing the code yourself.
- ✗Mixing several responsibilities into a single script.
🎯 Practical tip
You don’t need to understand the Python in the tools. Just check whether the workflow produces the right result; if a tool fails, ask the AI to fix it — it wrote it, it fixes it.
Scripts that execute.
Focus on one task.
Without you coding.
Automatic repair.
🔄 The self-improvement loop
What makes WAT powerful is the self-improvement loop: the agent runs a workflow, finds an error, diagnoses it, fixes the tool, and updates the workflow file so that error doesn’t happen again. Over time, runs get smoother and faster — the system learns from each failure instead of stumbling over it again.
The cycle, step by step
Run
The agent runs the workflow with the available tools.
Diagnose the error
When something breaks, it reads the error message and identifies the cause.
Fix the tool
Adjust the Python script responsible for the failure.
Update the workflow
Records the lesson in the workflow file so the error never happens again.
📈 Why this matters
The difference between fixing just today's output and updating the workflow is huge: the first solves it once; the second makes the system improve forever. Always ask for the fix in the workflow and the tool, not just the result.
Run the workflow.
Understands the error.
Adjust the tool.
Records the lesson.
📐 Professional CLAUDE.md
For fully automated workflows, the CLAUDE.md stops being a simple system prompt and becomes a onboarding document: describes the WAT framework and how each layer works, the operating rules, the folder structure, and the style preferences. The recommended structure separates workflows, tools, temporary files, and secrets.
meu-projeto/ ├── CLAUDE.md # onboarding WAT + regras ├── workflows/ # instruções em markdown ├── tools/ # scripts Python (um trabalho cada) ├── temporary/ # arquivos intermediários e saídas └── .env # chaves e segredos (nunca versionado)
⚠️ Attention: keep it lean
- ✗Don’t exceed ~500 lines—long files make rules easy to miss.
- ✗If the AI repeats an error even with the rule written down, the file may be too large.
- ✗Don’t put detailed instructions for each task here—that’s what skills are for.
🎯 Practical tip
Reserve CLAUDE.md for what applies to every session (purpose, framework, operating rules). Task-specific details live in skills, which are loaded on demand.
Explain WAT to the AI.
workflows/tools/temp/.env.
Lean and direct.
Only what always applies.
🚀 First agentic workflow
Time to put WAT into action: build a workflow that transforms a file from raw notes into a clean, structured document — with decisions, actions, and next steps. The key is to separate concerns: first, the agent generates the workflows and tools; only then do you run it to produce the final document, and iterate from there.
The build flow
Create the CLAUDE.md (Plan Mode)
In Plan Mode, ask for a CLAUDE.md at the root using the WAT framework and folder structure; review and approve the plan.
Add the input and clear the context
Save the notes in temporary/resources and clear the conversation to start with fresh context.
Generate workflows + tools (not the document yet)
Describe the desired document and instruct it to create the workflows and tools first—not the final output.
Run and iterate
Trigger the workflow to generate the document; then give specific feedback and ask it to update the workflow, tool, and output.
🎯 Practical tip
Edits can be partial (e.g., the text changed color, but the table rows didn’t). When requesting a change, ask for it to be applied to the workflow and tool, not just to the document—so the improvement persists for future runs.
🧷 Build reminders
- •Describe the result, not the steps.
- •Clear the conversation before a new task.
- •Never version the .env file containing secrets.
Plans before taking action.
Build before running.
Feedback that persists.
The workflow comes in handy again.
🧠 Quick check
In the WAT framework, which layer is the coordinator that reads the workflows, sees the tools, and decides which one to use?
📌 Module Summary
Next Module:
2.2 — Extending the Agent: MCP & Research