🤖 Prototyping and AI agents
The commands in family 09: reduce the idea to the minimum testable version, specify before building, design the complete agent — prompt, tools, memory — and evaluate before scaling.
🧪 /prototype + /MVP — the minimum testable version
/prototype reduces the idea to the smallest artifact capable of validating the critical hypothesis. /MVP chooses the minimum set of capabilities that delivers real value and generates learning. Both start with the same question: what's the hypothesis that, if it's wrong, brings everything down?
✓ Validating prototype
- ✓Hypothesis: "consultants would pay for automated proposals." Prototype: you manually generate 5 proposals and charge R$ 50 for each—in 3 days.
- ✓MVP: generator with 1 template, payment by link, support via WhatsApp. Nothing else.
✗ Decorative prototype
- ✗A beautiful landing page with "coming soon"—tests design, not willingness to pay.
- ✗MVP with login, dashboard, 4 plans, and integration with 3 tools—before the first customer.
New here? Critical hypothesis is the assumption that, if false, makes everything else irrelevant. It’s usually about human behavior ("they’ll pay," "they’ll come back"), not technology ("it can be built"). Test it first with the roughest artifact that works.
🎯 Copy and run
/prototype /MVP para <ideia>; declare a hipótese crítica, o menor artefato que a testa em até 1 semana, o que conta como validação (número), e depois o MVP com no máximo 3 capacidades e o que fica explicitamente fora
How to verify: the prototype fits in one week, and validation is a number ("5 paying customers"). The "out" list is longer than the "in" list.
📄 /spec — specify requirements and limits
Define requirements, interfaces, behavior, limits, exceptions, and acceptance criteria. It’s the contract between the person requesting the work and the person building it—and when the builder is an AI agent, it’s literally the build prompt.
📐 The six parts of a spec
- •Requirements: what the system does, in sentences with "must."
- •Interfaces: what goes in, what comes out, and in what format.
- •Behavior: what happens on the happy path — step by step.
- •Limits and exceptions: what happens with invalid input, a timeout, or missing data.
- •Acceptance criteria: tests that, if passed, settle the question "is it ready?".
- •Out of scope: what this cycle does NOT do — written down, so no one can "take the opportunity to add" something.
🎯 Copy and run
/spec para <funcionalidade ou sistema>; requisitos com "deve", interfaces de entrada/saída, comportamento no caminho feliz, 5 exceções com resposta esperada, critérios de aceitação testáveis e lista de fora-de-escopo
How to verify: each acceptance criterion can become an automated test or a 30-second check — none begins with "should be intuitive."
💡 Practical tip
Write the acceptance criteria BEFORE the behavior. Anyone who knows how they’ll verify it describes what they want better—and uncovers missing requirements.
🤖 /agent — design the complete agent
Define objective, tools, memory, rules, inputs, outputs, limits, and evaluation. Eight decisions that, made together, create a trustworthy agent—and that, made one at a time as bugs appear, create an unpredictable agent.
Illustrative: the core is goal + prompt; the four modules around it are their own commands; the foundation is /eval.
New here? Agent is an AI system that receives a goal, decides which tools to use, performs actions in sequence, and checks the result — instead of only generating text responses. What sets it apart from a chatbot is its ability to act and iterate without human instructions at every step.
🎯 Copy and run
/agent para <tarefa que o agente vai cumprir>; objetivo em uma frase, entradas e saídas, ferramentas com quando usar cada uma, o que memoriza e o que esquece, regras invioláveis, limites de ação e como será avaliado
How to verify: the goal fits in one sentence without "and." An agent with two goals is two agents — or one that does both badly.
⚠️ The agent that does everything
The temptation is to give the agent access to every tool and “let it decide.” The result is a system no one can evaluate because there’s no expected behavior. Start with a narrow scope; expand when /eval passes.
📝 /prompt + /tools — robust prompts and tools
/prompt specifies role, objective, context, rules, tools, format, and quality criteria. /tools maps each task to a tool and — the part everyone skips — defines when no use and when to escalate to a human.
| Prompt block | What prevents | Example |
|---|---|---|
| Role | Random tone and depth | "You are the proposal assistant for |
| Rules | Behavior made up for edge cases | "Never quote a price without confirming the client’s plan" |
| Format | Output no one can process | "Respond in JSON with the fields: titulo, itens[], total" |
| Quality criterion | Agent satisfied with a bad answer | "The proposal is ready when every item has a price and a timeline" |
Teaching example: each block exists to close a door the agent would open on its own.
🎯 Copy and run
/prompt /tools para <agente>; prompt completo com papel, objetivo, contexto, regras invioláveis, formato de saída e critério de qualidade; tabela de ferramentas com tarefa, quando usar, quando NÃO usar e quando escalar
How to verify: the “when NOT to use” column has content in every row. A tool without restrictions is a tool that will be used incorrectly.
💡 Practical tip
Test the prompt with the worst input you can imagine before trying the best. If the agent behaves well with "just do whatever," it will behave well with a clear request.
🧠 /memory — system memory
Separate session memory, profile, persistent facts, history, and update policy. The question isn't "does the agent remember?" but "what does it remember, for how long, and who has the power to change that?".
Session: what disappears when you close it
Context for the current conversation. Cheap, disposable, and never meant to hold a decision that needs to last.
Profile and persistent facts: what carries across sessions
User preferences, confirmed data, decisions made. Each item with its source and date.
Update policy: who writes, who deletes
Can the agent add facts on its own? Does it need confirmation? Do facts expire? Without a policy, memory accumulates errors that look like truth.
New here? Update policy is the rule that says when a fact enters memory, when it is replaced, and when it expires. "The user said X once" and "the user confirmed X three times" deserve different treatment — the policy is where this is written down.
🎯 Copy and run
/memory para <agente>; classifique o que ele precisa lembrar em sessão / perfil / fatos / histórico, defina formato e origem de cada item, política de atualização (quem escreve, quando expira) e o que NUNCA deve ser memorizado
How to verify: the “never memorize” list exists and includes at least sensitive data and unconfirmed inferences.
🧫 /eval — evaluate before scaling
Define test cases, criteria, metrics, critical failures, and approval threshold. This is the foundation of the design above: nothing scales without passing through here—and “passed” is a number, not a feeling.
✓ Decision-making eval
- ✓30 real cases (including 8 that have already gone wrong in production), criteria for each case, threshold: 90% accuracy and ZERO critical failures.
- ✓Runs with every prompt change; results are compared with the previous run.
✗ Demo eval
- ✗"I tested it with about 5 examples and it looked good."
- ✗Only easy cases; no edge cases; no failures classified as critical—because no one thought about what one would be.
New here? Critical failure is an error that, even if it happens once in a hundred times, makes the system unviable: leaking another customer’s data, taking an irreversible action without authorization, inventing a price. Critical failures aren’t averaged — they make approval a zero.
🎯 Copy and run
/eval para <agente>; 20-40 casos de teste incluindo exceções e casos que já falharam, critério de acerto por caso, métricas agregadas, lista de falhas críticas (tolerância zero) e limiar de aprovação para escalar
How to verify: there is a list of critical failures separate from the overall metric — and the pass threshold is a number decided before the run.
📊 Why 90% isn't the number
The threshold depends on the cost of an error. An agent that suggests post titles can be wrong 20% of the time without a problem. One that sends proposals with pricing can’t. Set the threshold based on the cost of the worst common failure — not a round number.
🛡️ /guardrails — limits, fallback, escalation
Creates rules for security, authorization, validation, fallback, and escalation. A trustworthy agent isn’t one that never makes mistakes—it’s one that, when it doesn’t know, stops and asks instead of improvising.
🚧 Five layers of guardrails
- •Authorization: which actions require human confirmation (pay, delete, send externally)?
- •Input validation: what to do with an out-of-scope or malformed request?
- •Output validation: does the response go through a check before it’s sent (format, value range, sensitive data)?
- •Fallback: when the tool fails or confidence is low, what is the default behavior?
- •Escalation: under what condition does the agent hand off to a human — and to whom?
🎯 Copy and run
/guardrails para <agente>; ações que exigem autorização humana, validações de entrada e saída, comportamento de fallback por tipo de falha, condições de escalonamento com destinatário e o que registrar em log
How to verify: every irreversible action is on the authorization list, and every fallback has defined behavior — never "keep trying until it works".
⚠️ A prompt guardrail isn’t a guardrail
A rule written only in the prompt is a request, not a limit—the model may ignore it. A real guardrail lives outside the model: code validation, tool permissions, human confirmation. The prompt warns; the infrastructure blocks.
🔌 /integrate — integrations and synchronization
Maps systems, APIs, authentication, data, events, errors, and synchronization. It’s the command that turns an agent that works in the demo into one that works on Monday, with the real CRM and the spreadsheet someone renamed.
| Dimension | Question | Classic mistake |
|---|---|---|
| Authentication | How does the agent prove who it is to each system? | Developer’s personal token in production |
| Data | Which format goes in, which comes out, and who is the source of truth? | Two systems with the same field and different values |
| Events | What triggers the agent—polling, webhook, schedule? | Polling every 10 seconds on an API limited to 100 calls/hour |
| Errors | What happens when the API returns 500 or takes too long? | Infinite retries that duplicate requests |
| Synchronization | Who wins when both sides have changed? | "The last person who saved" — erasing someone’s work |
Teaching example: every row in the table has already been an incident in some real project.
🎯 Copy and run
/integrate para <agente> com <sistemas envolvidos>; para cada sistema: autenticação, dados de entrada/saída com fonte da verdade, gatilho (evento/polling/agenda), tratamento de erro com limite de retry e regra de sincronização em conflito
How to verify: every integration has a written conflict rule and retry limit — and none uses personal credentials.
💡 Composite recipe
Complete agent architecture, straight from the document: /agent /tools /memory /guardrails /eval /integrate. Note the order: eval before integrate—you evaluate in a controlled environment before connecting to the world.
Quick self-check (optional): why does /eval come before /integrate in the agent architecture recipe?
🎓 Module Summary
Next Track:
6.1 - Communication and learning — you build and evaluate; now learn to explain, teach, and adapt the message for decision-makers.