⌨️ Step 5 — Implement the changes
Now the agent can write code—within the loop you defined, with the plan approved beforehand. Approving the plan takes two minutes and saves an hour of rework in the wrong direction.
🧪 Do it now — trigger the loop
Objective: run step 5 without improvising.
Leia, nesta ordem: AGENTS.md, docs/exercicio/spec.md, docs/exercicio/loop.md. Siga o loop exatamente como está escrito. Comece pelo passo 1: apresente o PLANO em no máximo 10 linhas (o que vai mudar, em quais arquivos, e como cada critério de aceitação será verificado) e PARE. Não escreva código antes da minha aprovação.
Review the plan with these three questions: (1) does it touch only the expected files? (2) does it cover every criterion? (3) did it invent an abstraction no one asked for? Approve or correct it. Then:
Plano aprovado <com ajustes: ...>. Prossiga com os passos 2 e 3 do loop. Ao terminar: cole a saída REAL e completa de <comando de teste> e rode "git diff --stat" para eu ver o tamanho da mudança.
How to verify: check the --stat against the AGENTS.md limit and run the test command yourself. Never accept the agent’s summary as evidence—run it.
⚠️ Attention
If the loop hits the cap (3 attempts) or repeats the same failure twice, stop — as agreed. That’s not a failure of the exercise: it’s the control working. Record what was attempted in the log and decide what to do next.
Plan first
Your approval
--stat
Check the size
You run it
The test, for real
Stop
It’s the right control
🚦 Step 6 — Apply Quality Gates
Run the module 3.3 test suite against your change. Here you find out which gates your repository still lacks — and this list is one of the exercise’s most valuable outputs.
🧪 Do it now — the gate walkthrough
<comando de build> # ☐ passou <comando de lint> # ☐ passou <comando de teste> # ☐ passou · cole a saída no registro git diff --stat # ☐ dentro do limite de arquivos git diff -- <pasta de testes> # ☐ VAZIO (nenhum teste existente alterado) git diff -- <arquivo de dependências> # ☐ VAZIO (nenhuma dependência nova) git log -p | grep -iE "senha|password|secret|token|api[_-]?key" # ☐ nada
How to verify: record in the log which of these gates are already automated in your CI and which ones you just ran manually. Every manual check is a backlog item: it should be in the pipeline, not in your memory.
✓ Sign of good execution
- ✓Diff within the agreed limit
- ✓Existing tests left untouched; new tests covering the new behavior
- ✓Zero dependencies added
- ✓You can explain every changed file
✗ Red flags in the diff
- ✗An old test “adjusted” along with the fix
- ✗Exception caught and silently swallowed
- ✗Configuration file changed for no apparent reason
- ✗New abstraction for a single use
All gates
No exceptions
Manual today
Automatic tomorrow
Untouched test
Check with git diff
Explain everything
File by file
🔍 Step 7 — Independent Review
Open a new session, without the implementation history. This is the step that most surprises people doing the exercise: the reviewer finds things the implementer defended with conviction just ten minutes earlier.
🧪 Do it now — the reviewer
Você é o revisor independente. Não implementou nada disto e não deve confiar em nenhuma afirmação de quem implementou. Especificação: docs/exercicio/spec.md Diff: <cole a saída de "git diff origin/<base>...HEAD"> Leia os arquivos relacionados antes de concluir e responda: 1. a mudança cumpre TODOS os critérios de aceitação? o que ficou faltando? 2. algo fora do escopo declarado foi alterado? 3. algum comportamento existente muda para quem consome? 4. o tratamento de erro cobre os casos previstos na spec? 5. os testes provam o comportamento novo ou apenas executam o código? 6. existe algo aqui que passa nos testes e ainda assim está errado? Formato: no máximo 7 achados, cada um com [bloqueante | importante | menor] · arquivo:linha · por que é problema · como verificar. Se não houver bloqueante, diga isso explicitamente.
How to verify: take each blocking finding and try to reproduce it yourself. Fix the ones that hold up—returning to the loop with the same rules—and record it in the registro.md how many findings were real. This rate is your measure of trust in the reviewer.
💡 Practical tip
Question 6 (“passes the tests and is still wrong”) is the most useful. Ask this question in every review from now on — it’s the direct antidote to the most dangerous flaw in track 4.
New session
Clean context
Spec + diff
And nothing else
Reproduce
Before fixing
Actual rate
Measure the reviewer
📦 Step 8 — Prepare the delivery
A PR with evidence is reviewed in minutes; a PR without evidence gets approved without being read—which is worse than not being reviewed, because it creates the illusion of control.
🧪 Do it now — pull request body
## O que muda <2 a 3 linhas, em português, do ponto de vista de quem usa> ## Especificação docs/exercicio/spec.md (critérios de aceitação atendidos: <liste>) ## Fora do escopo (não foi alterado de propósito) - <...> ## Evidência <saída real do comando de teste — colada, não resumida> git diff --stat: <n> arquivos, +<n> -<n> gates: build ✓ · lint ✓ · testes ✓ · sem dependência nova ✓ · sem segredo ✓ ## Revisão independente <achados do revisor e o que foi feito com cada um> ## Risco e reversão Risco: <baixo/médio> · Como reverter: <comando ou passo>
How to verify: ask someone on the team to read only the PR body (without opening the diff) and say what the change does and what the risk is. If they can, the work is ready. If they can't, evidence or clarity is missing—and it's faster to fix that now.
Evidence
Pasted, not narrated
Out of scope
It’s also declared
Reversion
In one line
Reader test
Without opening the diff
📊 Review the exercise
Every intervention you make during the exercise could become a rule, a gate, or an AGENTS.md item. That’s how the system gets better on its own for the next task—and that’s what sets people who use AI apart from those who build with AI.
How to read: this is the cycle that makes the method pay off. Whenever you correct the agent by hand, ask which of the three buckets it belongs in. If it doesn’t fit any of them, it’s probably a decision only a human can make—and that’s useful information too.
Quick check: during the exercise, you had to remind the agent three times not to change the tests. What should you do about that?
Intervention
Becomes a rule
Repeated 3x
Automate
Missing gate
Goes to the backlog
Next time
Requires less from you
🎒 Build your deliverables kit
You’ve reached the end with artifacts, not notes. Gather everything in one place — that’s what turns two days of workshop into a permanent change in practice.
📦 What you take away
💡 One last practical tip
Don’t try to install all twelve artifacts across the team at once. Start with two: the AGENTS.md e o independent review prompt. These deliver visible results in the first week—and visible results are what make room for the other ten.
Artifact
Not a note
Versioned
In the repository
Start with 2
Not with twelve
Result
Buys room
🏁 End of the course
AI software engineering doesn’t eliminate traditional engineering — it makes the fundamentals more important. Models and tools will change quickly. Durable knowledge lies in knowing how to specify, structure context, create harnesses, design loops, automate, test, review, control architecture, limit autonomy, modernize safely, apply governance, and turn rules into executable checks.
The most valuable professional won’t be just the person who knows how to ask AI for code. It will be the person who knows how to build the system in which AI can work safely, with quality, speed, and control.