Capítulo 0 · leitura antes do Sábado 1 · leia e pratique no seu ritmo
Como um agente pensa
Comece do zero em IA: o que é um modelo, como ele aprende e como produz uma resposta. Depois, descubra como orientar um agente a trabalhar no seu projeto e conferir o resultado, com exemplos simples de cadastro de produtos.
Na sala, deixe assim e acompanhe a voz do professor. Animações, jogos e legendas continuam funcionando.
Pense num assistente que ajuda a escrever e revisar um cadastro de produtos. Ele recebe seu pedido, produz uma resposta e pode usar ferramentas para trabalhar nos arquivos. Vamos entender cada peça antes de pedir que ele faça algo sozinho.
IA — inteligência artificial Nome amplo para sistemas que realizam tarefas como reconhecer padrões, gerar texto ou ajudar a tomar decisões. Aqui vamos estudar modelos de linguagem.
Modelo Um sistema de cálculos ajustado durante o treinamento. Ele usa padrões aprendidos para produzir saídas, como uma resposta em texto.
Prompt A mensagem ou instrução que você envia: “Explique este código” é um prompt. Ele faz parte das informações usadas na resposta.
Spec — especificação Um texto que descreve o que deve acontecer e como conferir. Exemplo: “Não salvar produto com preço negativo; verificar com -500 centavos”. Vamos construir uma mais adiante.
Agente é o sistema que combina modelo, ferramentas e um ciclo de ações. Projeto é o conjunto de arquivos do programa; quando esses arquivos estão organizados com histórico de versões, você também ouvirá “repositório”.
Nosso caminho: conhecer os nomes → ver o treinamento → acompanhar uma resposta → entender contexto e erros → usar ferramentas → escrever uma especificação → revisar a entrega.
Nos exemplos, o preço é um inteiro em centavos: 1000 significa R$ 10,00. Negativos serão recusados; zero será permitido. Teste é uma verificação: escolher uma entrada e comparar o resultado com o que esperamos.
🔥 O cadastro aceitou um produto de preço negativo. O agente disse “testes passando”. O que você faz?
🚚
Antes da conversa: como o modelo aprende
Dados de exemplo, ajustes internos e uso do modelo são etapas diferentes
Como ele aprendeu a completar frases?
O aplicativo é a interface onde você conversa; o modelo é o sistema que produz a resposta. Uma interface pode oferecer modelos diferentes. Antes de você fazer uma pergunta, existe uma fase de treinamento. O modelo pratica com exemplos e um algoritmo ajusta seus cálculos. Depois, durante o uso, ele recebe sua mensagem e produz uma resposta. Vamos separar as duas situações.
A GARAGEM E A FÁBRICA
Uma viagem pelo treinamento
O caminhão representa uma família; os livros representam exemplos de treinamento. As dimensões não medem parâmetros, dados de treinamento, memória ou desempenho. Não representam “toda a internet”.
ENCENAÇÃO DO PROCESSO · HAIKU
📘📄⌨
🏭TreinamentoDados → cálculos ajustados
🔬 PAINEL DO LABORATÓRIO · PARE, APONTE E EXPLIQUE
ANTES
AÇÃO
DEPOIS
COMO PROVAR
Treinamento
Aprender com exemplos: o algoritmo modifica parâmetros, números internos que influenciam o comportamento do modelo.
Uso ou inferência
Produzir uma resposta com o modelo já treinado e com as informações disponíveis naquela interação.
Consulta a fontes
Buscar um arquivo ou uma página por uma ferramenta. Ter essa informação no contexto não é a mesma coisa que treinar novamente o modelo.
A Anthropic descreve pré-treinamento com dados diversos e ajustes posteriores para o comportamento de assistente. A mistura de dados e os métodos dependem da versão. Isso não significa acesso a toda informação existente. Relatórios de treinamento ↗
Famílias consultadas: Haiku, Sonnet, Opus e Fable. Os rótulos resumem propostas de uso; não garantem acerto nem uma ordem universal de capacidade.
👀 Conferiu? Treinar e responder são a mesma coisa?
Não. Treinar ajusta o modelo. Responder usa o modelo com o contexto atual. Um documento recém-lido pode ajudar na resposta sem se tornar uma nova lembrança permanente nos parâmetros.
🎛️
Fine-tuning: um ajuste adicional
Treinar com exemplos é diferente de fornecer informação para uma resposta
Consultar uma informação ou mudar o modelo?
O cadastro ganhou mensagens de atendimento: “quero saber o preço” e “não consigo salvar”. Você quer classificá-las como DÚVIDA ou PROBLEMA. Primeiro pode tentar instruções claras e alguns exemplos no pedido. Se isso não atender ao objetivo, uma opção a avaliar é o fine-tuning, ou ajuste fino.
Fine-tuning é treinamento adicional de um modelo já treinado, com exemplos selecionados. Ele ajusta parâmetros do modelo ou parâmetros adicionais, conforme a técnica. Não é simplesmente anexar um documento a uma conversa.
DOIS CAMINHOS PARA COMPARAR
Catálogo de hoje ou exemplos para treinar?
O modo mudo do capítulo vale aqui também.
Comparação ilustrativa. Nenhum modelo é treinado aqui; resultados não são medições de um provedor.
Treinar exige exemplos de qualidade e avaliação em dados separados. Não presuma que melhora qualquer tarefa. Informação que muda diariamente, como preço ou estoque, pede uma fonte atualizada; a consulta pode ser usada com um modelo ajustado também. Referência sobre ajuste de modelos ↗
🔮
O LLM por dentro
Como o contexto ajuda o modelo a prever o próximo pedaço de texto
ChatGPT, Claude, Gemini: por trás de todos há um LLM (Large Language Model, ou grande modelo de linguagem) fazendo uma
geração de texto passo a passo: dado o contexto (as informações disponíveis nesta interação) e o que já foi escrito, o modelo calcula possibilidades para o próximo token.
Um token é um pedaço de texto: pode ser uma palavra, parte dela, um espaço ou sinal de pontuação. O sistema escolhe um, acrescenta à resposta e repete o processo.
Pense num recurso de completar texto automaticamente, o autocomplete que considera a conversa inteira disponível. Na animação, acompanhe a pergunta de Lia,
o balão de Beto e a bancada da LLM. Depois mude o contexto e veja por que uma continuação plausível não é garantia de verdade.
UM PEDACINHO DE CADA VEZ
A oficina de falas
Lia pergunta. Beto responde. Abra os bastidores do autocomplete.
Liatraz o contexto
CONVERSA
·················
↓ vira entrada ↓
Betofala gerada pela LLM
•‿•
▰ ▰
Tico · a LLM“O que pode vir agora?”
1 · LEIO O QUE JÁ TENHO
2 · CALCULO POSSIBILIDADES
3 · ESCOLHO UM PEDAÇO E REPITO
Três personagens, três vozesAperte Assistir para ouvir a conversa.
Teatro didático: Beto representa a resposta do modelo. Os percentuais e as divisões em pedaços são ilustrativos, não uma medição real. Tokens podem ser palavras, partes de palavras, espaços ou pontuação. A escolha pode usar amostragem: nem sempre vence o mais provável.
📖 pausa teórica
"Mas ele raciocina?"
Para o nosso uso, a pergunta certa é outra: ele produz texto plausível. Prever muito bem exige capturar
padrões de linguagem e código (gramática, lógica, estilo e formas comuns de programar), então o resultado muitas vezes funciona como
raciocínio. O que importa nesta aula é conseguir verificar os passos e o resultado, em vez de aceitar a aparência de uma explicação.
Uma resposta plausível pode estar correta ou não; a aparência do texto, sozinha, não distingue os dois casos.
Consequência prática para quem revisa: o código do agente vem com a cara de quem sabe o que está fazendo, mesmo
quando não sabe. Você não pode usar a confiança do texto como sinal de qualidade. Só o critério (a spec, o
teste, o padrão do projeto) serve de sinal.
EM SALA · JOGUE EM DUPLA
Pilotando o próximo token
Vocês assumem o controle da geração: leiam o contexto, apliquem a regra da rodada e confirmem uma escolha. Só depois o mecanismo é revelado.
10 pontos por decisão correta, sem bônus de velocidade. Distribuições, bilhetes e divisões em pedaços são didáticos, não medições de uma LLM real. Cada dupla joga neste navegador. O placar é local à partida, sem sincronização entre dispositivos; ao recarregar, começa de novo.
5 rodadas · 50 pontos · 5–8 minutos
📦
Contexto e alucinação
O que está na mesa, o que ficou de fora e o que precisa de prova
📖 a história antes do conceito
“Mas eu já tinha explicado isso!”
Você combinou que o cadastro recusaria preços negativos. O agente seguiu a regra, ajudou em outras tarefas e, muito depois,
entregou uma versão que aceita um produto com preço de -500 centavos. Sua primeira reação é: “ele esqueceu”.
Antes de repetir a instrução em letras maiúsculas, investigue: a regra ainda estava disponível?
Havia outra instrução contradizendo? Ou ela estava presente e mesmo assim foi descumprida?
Agora imagine outro erro: ele sugere um método que não existe na classe do projeto. O contexto pode estar curto,
organizado e completo — e a sugestão ainda assim ser inventada. Os dois problemas se parecem na tela,
mas pedem diagnósticos diferentes. Vamos abrir os bastidores.
O QUE ESTÁ NA MESA AGORA?
A mesa do Tico
Uma regra perdida, um resgate e um método suspeito.
Lia
Liadirige e revisa
•‿•
▰ ▰
Ticoabre os bastidores
Betoexperimenta
CONTEXTO ATUAL
🗂️ FORA DA MESA
Diff significa a comparação do código antes e depois da alteração. Encenação: a mesa representa o contexto disponível nesta etapa. As oito unidades do medidor são ilustrativas, não tokens reais. O resumo que perde uma regra é um cenário possível, não o comportamento obrigatório de todo agente. As falas também estão escritas nos balões.
📦 1 · a mesa não é a biblioteca
Treinamento, contexto e arquivos são coisas diferentes
O modelo traz padrões aprendidos no treinamento. Para responder agora, ele também usa o conteúdo fornecido
na interação. No agente, essa entrada pode incluir instruções, mensagens e resultados de ferramentas.
Ter um arquivo no projeto não significa que seu conteúdo já esteja no contexto.
Ler o arquivo é uma ação; o resultado da leitura pode então alimentar a próxima resposta.
📚 Padrões aprendidos
Conhecimento incorporado ao modelo durante treinamento. Não é uma consulta automática à versão atual do seu projeto.
🧾 Contexto atual
Informação disponibilizada para esta geração: pedido, instruções, trechos da conversa, arquivos lidos e saídas de ferramentas.
🗂️ Fontes persistentes
Arquivos, specs e registros que continuam no disco. Podem ser consultados novamente; precisam ser encontrados e carregados.
A janela tem um limite, que varia por modelo e configuração. Não existe uma quantidade universal de mensagens
ou de arquivos que “cabe”. Um log enorme pode custar mais contexto que muitas mensagens curtas.
Caber também não garante que a informação seja bem utilizada.
🧭 2 · diagnosticar antes de repetir
Três maneiras de uma instrução deixar de ajudar
Não entrou
A regra estava num arquivo que não foi lido. Peça a leitura do arquivo relevante e confira qual restrição foi identificada.
Não foi preservada
Uma sessão longa pode ser resumida ou ter partes removidas, conforme a ferramenta. Confira se o resumo reteve as decisões e os limites da tarefa.
Entrou, mas não foi seguida
Instruções ambíguas, conflitantes ou pouco destacadas podem atrapalhar. O modelo também pode errar mesmo com a regra clara. Revise e teste.
Compactar é trocar um histórico detalhado por uma representação menor. Pode ajudar a continuar o trabalho,
mas o resumo é uma seleção. “Implementamos Produtos” não preserva “não aceitar preço negativo”.
Por isso, decisões importantes merecem registro verificável fora da conversa.
Evite duas conclusões automáticas: “o modelo apagou tudo que era antigo” e
“se eu mandar o repositório inteiro, ele não erra”. O mecanismo de contexto depende da ferramenta, e quantidade não substitui seleção.
📄 3 · persistir, carregar, conferir
O arquivo de instruções é um ponto de recuperação
Um arquivo .md guarda texto em Markdown, com marcações simples como # para títulos. A pasta .specs/ reúne as especificações das tarefas neste curso. Mais adiante, você vai criar essa pasta na IDE simulada.
Um arquivo de instruções guarda orientações gerais do projeto. No Claude Code, CLAUDE.md fornece instruções persistentes e entra no contexto.
Ele consome tokens e orienta o modelo; não é uma garantia de cumprimento.
Confirme o carregamento e mantenha as regras específicas, curtas e coerentes.
Como o Claude Code carrega instruções ↗
No nosso fluxo, convenções recorrentes ficam no arquivo de instruções usado pelo agente;
o objetivo e os critérios de aceite (condições para aceitar o resultado) de uma tarefa ficam na spec. Ao retomar um trabalho, peça para ler
as fontes relevantes e explicar as restrições antes de propor mudanças.
Um pedido que recompõe o contextoprompt
# Fontes e escopo
Leia o arquivo de instruções do projeto,
.specs/cadastrar-produto.md e ProdutoService.java.
# Antes de alterar
Liste as regras que se aplicam ao cadastro.
Se houver conflito ou informação faltando, aponte.
Proponha uma mudança limitada a esta tarefa.
# Evidência de pronto
Mostre o diff e os resultados das verificações.
Explique como conferiu que um preço negativo é recusado.
Nos exemplos deste capítulo, o preço é um número inteiro em centavos: 1000 significa R$ 10,00. A regra é recusar negativos; zero é permitido. Confira três entradas: -500, 0 e 1000. Um teste com preço positivo não prova que negativos serão recusados.
🎭 4 · quando a resposta inventa
Alucinação não é só “esquecer a conversa”
Chamamos de alucinação, aqui, uma resposta que apresenta conteúdo inventado ou sem sustentação como se fosse
correto. O modelo pode combinar nomes e padrões conhecidos e produzir um método, uma opção ou uma explicação
convincente. Ele também pode reconhecer a incerteza: inventar não é inevitável, mas é um risco a verificar.
Imagine que a classe ProdutoService tenha apenas os métodos cadastrar e listar. O agente sugere salvarComDescontoAutomatico(). O nome soa útil, mas esse método não existe nessa classe do exemplo. Abrir o arquivo e compilar permite conferir. Se for necessário criar descontos, primeiro precisamos definir a regra.
Para ler os exemplos: método é uma operação do código; biblioteca/dependência é código pronto usado pelo projeto; compilar verifica e traduz o código Java, mas não testa todos os comportamentos. Diff é a comparação entre o código anterior e o alterado.
O que veio errado?
Como conferir?
O que não basta?
Dependência ou método inventado
Documentação da versão e resolução/compilação.
O nome parecer familiar.
Configuração não suportada
Documentação, inicialização e comportamento observado.
A compilação passar.
Regra de negócio incorreta
Spec e testes com casos válidos e inválidos.
Só o caminho feliz funcionar.
Alteração fora do pedido
Comparar os arquivos alterados com o escopo da tarefa.
A aplicação subir.
Consultar fontes e fornecer contexto pertinente ajuda. Ainda assim, verifique se a fonte sustenta a afirmação
e se os testes medem a regra certa. Um teste gerado a partir da mesma suposição errada pode apenas repetir o erro.
🔬 agora é você · escolha a evidência
O código compilou. Você aprova?
O agente aceitou preço negativo. A especificação proíbe esse cadastro, mas o único teste usa preço positivo e passou. Qual é a próxima ação mais útil?
Monte um contexto útil para uma falha real
Escolha um erro do seu projeto. Registre: a tarefa, a regra que não pode ser violada,
os arquivos ou trechos necessários e a evidência que confirmará a correção.
👀 Ver um exemplo de raciocínio
“CadastrarProduto aceita preço negativo”. Levar:
spec da operação, método que cadastra o produto, teste atual e mensagem do erro. Evitar: logs de outros serviços.
Verificar: teste para preço negativo, outro para zero e outro para preço positivo e diff limitado à operação.
Se o agente afirmar algo sobre uma biblioteca, consultar a documentação da versão usada.
EM SALA · JOGUE EM DUPLA
Detetives do contexto
Uma entrega suspeita, cinco fontes e apenas três consultas. Montem o dossiê, escolham o diagnóstico e proponham a próxima ação.
O limite de três fontes simula tempo de revisão; não é uma janela real de tokens. Confirmou? A escolha fica fechada até terminar a partida. Cada dupla joga neste navegador. O placar é local à partida, sem sincronização entre dispositivos; ao recarregar, começa de novo.
3 casos · 30 pontos · 8–12 minutos
Para a próxima seção: uma LLM sozinha produz uma resposta. Um agente pode ler arquivos,
consultar fontes e executar verificações. Essas ferramentas ajudam a obter evidência — mas você ainda precisa julgar se a evidência é suficiente.
🔎
RAG: responder consultando fontes
Buscar → selecionar → colocar no contexto → responder e verificar
O modelo sabe o regulamento da nossa loja?
O modelo não tem como adivinhar uma regra que só existe nos documentos da empresa. RAG significa Retrieval-Augmented Generation, ou geração aumentada por recuperação: buscar trechos relevantes, colocá-los no contexto e gerar a resposta com esse apoio.
Pense em responder uma prova consultando o material permitido. É preciso encontrar a página certa e interpretar o que ela diz. Um documento antigo pode estar bem escrito e ainda assim levar ao resultado errado.
JOGO · ENCONTRE A EVIDÊNCIA
Quanto custa o caderno com o cupom?
Cliente: “Quero um caderno com o cupom ESTUDO. Qual o preço final, sem frete?” Estamos em setembro de 2026. O produto é elegível ao cupom.
🔎Buscar
📄Selecionar trechos
📦Montar contexto
💬Responder e conferir
A resposta ainda não foi gerada. Primeiro precisamos de fontes.
O modo mudo do capítulo vale aqui também.
Busca e resposta são simuladas. A dupla faz a seleção para observar o mecanismo; sistemas reais podem selecionar trechos automaticamente, com diferentes técnicas.
A busca pode falhar, recuperar material desatualizado ou não encontrar a resposta. Confira relevância, vigência e se a conclusão é sustentada pelo trecho. RAG não altera os parâmetros a cada consulta e não elimina alucinações. Referência sobre recuperação de contexto ↗
🦾
Do chat ao agente
Ler, editar, testar — e usar o resultado para decidir o próximo passo
📖 A HISTÓRIA CONTINUA
O cadastro aceitou um preço negativo. Quem vai corrigir?
Uma resposta em texto pode sugerir um if, mas alguém ainda precisa abrir o arquivo, aplicar a mudança e testá-la. Quando a IA tem ferramentas para realizar essas ações, ela pode participar de um ciclo: agir, observar o resultado e decidir o próximo passo.
A diferença não é a aparência da tela. Uma interface de chat também pode oferecer ferramentas. O que importa aqui é o acesso disponível: apenas responder, ou também ler arquivos, editar e executar verificações.
UM PEDIDO, FERRAMENTAS E EVIDÊNCIAS
Tico ganha ferramentas
O cadastro parece pronto. Mas o que foi realmente testado?
Lia
Liadirige e revisa
•‿•
▰ ▰
Ticoabre os bastidores
Betoexperimenta
FERRAMENTA / ETAPA
🧪 LABORATÓRIO SIMULADO
Encenação local: as ferramentas e saídas são ilustrativas. Nenhum Java é executado aqui. Os controles permitem pausar, repetir e avançar sem áudio. O aluno revisa o plano como combinado pedagógico da aula; permissões reais dependem da configuração do agente.
O que cada ferramenta devolve?
Ferramenta é um recurso que realiza uma ação e devolve o resultado. Um comando, como ./mvnw test, é uma instrução para o computador executar os testes do projeto Java com Maven. Veremos o comando no setup; aqui basta entender o que ele verifica.
📖 Ler
Traz o conteúdo de um arquivo para a investigação. Permite conferir como o cadastro funciona hoje.
✏️ Editar
Altera o código. A alteração ainda é uma proposta que precisa de verificação.
🖥️ Executar
Roda um comando e devolve uma saída: sucesso, falha, mensagem e resultados dos testes.
O agente não precisa seguir sempre a mesma sequência. Se um arquivo não existe, deve localizar o correto. Se a regra não diz se zero é permitido, precisa esclarecer. Se o teste falha, o resultado orienta a investigação.
Um if que dá para acompanhar
Aqui, if significa “se”: o bloco é executado quando a condição é verdadeira. O preço usa centavos inteiros. -500 é negativo, 0 é permitido e 1000 representa R$ 10,00. Neste trecho de método Java, a verificação vem antes de salvar:
Trecho de ProdutoService.javaexemplo
if (precoEmCentavos <0) {
return"Preço inválido";
}
// Só chegamos aqui quando o preço não é negativo.
produtos.add(produto);
return"Produto cadastrado";
return encerra este método. produtos.add(produto) adiciona o produto à lista do exemplo. Se a condição fosse <= 0, bloquearia zero também. É por isso que testar o limite importa.
Plano, autorização e conclusão são decisões diferentes
Plano: quais alterações fazer e como conferir. Permissão: quais ações a ferramenta pode executar. Revisão: se a entrega cumpre o pedido.
No exercício da aula, você revisa o plano antes da execução. Isso é um combinado do curso. Na ferramenta real, pedidos de confirmação variam conforme o modo e as permissões configuradas; não aparecem obrigatoriamente antes de toda edição.
“Terminei” é um relato. Para aceitar, confira qual teste rodou, o resultado e o diff — a comparação entre o código anterior e o novo. Se faltou acesso a uma ferramenta, a entrega precisa explicitar essa limitação.
EM SALA · DECIDA EM DUPLA
Você dirige o agente
Escolha o próximo passo diante de um arquivo não lido, um teste verde incompleto e uma falha. Antes de confirmar, diga à sua dupla o que espera descobrir.
Simulação local, sem executar comandos. 10 pontos por decisão. Cada dupla joga no próprio navegador; recarregar zera a partida.
4 rodadas · 40 pontos · 5–8 minutos
🧰
Harness: o programa que coordena o agente
O modelo solicita; o sistema encaminha, observa e continua
Quem transforma o pedido do modelo em uma ação?
Quando o modelo solicita “ler ProdutoService.java”, ele produz uma chamada de ferramenta. Outro programa precisa receber essa chamada, conferir os controles aplicáveis, encaminhar a execução e devolver o resultado para o modelo.
Esse programa ao redor do modelo é chamado de harness. Ele organiza o ciclo de execução e pode cuidar de contexto, registro de ações, limites e tratamento de falhas. É parte do sistema do agente; não é outro nome para o modelo.
ABRA OS BASTIDORES
O pedido vai e o resultado volta
HARNESS · coordena a passagem entre as peças
🧠Modelo
🚦Controles e roteamento
📖Ferramenta de leitura
📦Resultado no contexto
O modo mudo do capítulo vale aqui também.
Simulação: a caixa agrupa a coordenação do ciclo; não significa que o modelo é implementado dentro do mesmo processo. Nenhum arquivo é lido de verdade.
O nome pode abranger componentes diferentes em cada sistema. A ideia central aqui é separar quem produz a solicitação de quem coordena e executa a ação. Mesmo com bons controles, o conteúdo devolvido e a resposta precisam de revisão. Um exemplo de organização de harness e ferramentas ↗
🧩
Anatomia do agente
As peças aparecem quando resolvem uma necessidade
“Corrija o preço negativo.” O que precisa existir ao redor desse pedido?
Não basta uma caixa de texto. O agente precisa de informações sobre a tarefa, ferramentas para agir e critérios para conferir o resultado. Comece pelas quatro peças abaixo; abra as demais quando a situação pedir.
1 · Instruções do projeto
Convenções que se repetem: onde testar, como representar preços e como limitar alterações. São texto que orienta o trabalho; não substituem controles de acesso.
2 · Spec da tarefa
Um pequeno documento sobre esta mudança: recusar preço negativo, aceitar zero, preservar a listagem e verificar três casos. A pasta .specs/ é a convenção deste curso, não uma exigência de toda ferramenta.
3 · Ferramentas e resultados
Ler ProdutoService.java, editar a condição e executar os testes. Cada ação deve produzir algo observável para decidir o próximo passo.
4 · Plano e revisão
Você examina a proposta, depois compara o resultado com a regra. Uma lista de testes sem execução ainda é um plano de verificação.
Quando a necessidade cresce
“Repito a mesma orientação em várias tarefas” → Skill
Reúna um procedimento reutilizável. Exemplo: revisar um cadastro, verificando campos obrigatórios, preço e listagem. A skill orienta; não prova que os passos foram executados.
“Quero checar uma regra automaticamente” → Verificação e hook
Um teste pode verificar preços negativos. Um hook pode disparar um comando em um evento suportado pela ferramenta. Primeiro escreva uma verificação útil; depois decida onde acioná-la.
“Preciso consultar outro sistema” → Integração
Uma ferramenta externa pode trazer dados ou documentação. MCP é um padrão de comunicação usado para integrar ferramentas. A integração precisa estar disponível e autorizada; o nome sozinho não concede acesso.
“Há uma investigação independente” → Subagente
Uma parte do trabalho pode ser delegada com objetivo e contexto próprios. Sua conclusão também precisa de evidência; delegar não garante uma revisão melhor.
“A sessão ficou longa” → Gestão de contexto
Selecione fontes relevantes e confira o que foi preservado. Ler um arquivo também ocupa contexto; passar o caminho ajuda a selecionar, mas não torna seu conteúdo gratuito.
👥 Qual peça resolve? Em dupla: onde guardar como testar o projeto? Onde registrar que somente esta tarefa permite zero? E o que investigar quando uma ferramenta nega acesso ao banco?
👀 Comparar os argumentos
“Toda vez precisamos explicar como testar”: instrução ou skill, conforme seja uma regra curta ou um procedimento. “Só este cadastro aceita zero”: spec da tarefa. “Acesso ao banco foi negado”: permissões e conexão, não uma frase mais insistente no prompt. Justifique a escolha.
MCP: uma conexão padronizada
MCP significa Model Context Protocol. É um padrão de comunicação entre uma aplicação de IA e servidores que disponibilizam ferramentas, informações e outros recursos. Um servidor é um programa que atende solicitações; pode estar na mesma máquina ou em outro lugar.
No nosso exemplo, a aplicação possui um cliente MCP, que se comunica com o servidor do catálogo. O servidor oferece uma ferramenta para consultar produtos. Conectar não concede automaticamente acesso a qualquer operação: permissões e configuração continuam valendo.
CONECTAR · DESCOBRIR · CONSULTAR
Um catálogo do outro lado
💬Aplicação de IA
🔌Cliente MCP
🗄️Servidor do catálogo
🏷️Fonte de produtos
O modo mudo do capítulo vale aqui também.
Conexão ilustrativa e dados fixos. Nenhum servidor MCP real ou banco de dados é acessado nesta página.
Uma ferramenta pode existir sem MCP. Uma aplicação pode usar uma ferramenta MCP para buscar documentos num fluxo de RAG, mas RAG também funciona sem MCP. O protocolo padroniza a conversa; não garante que o dado seja correto. Arquitetura oficial do MCP ↗
📄
CLAUDE.md e AGENTS.md
Orientações que você consegue localizar, carregar e conferir
O que você não quer explicar de novo a cada tarefa?
No nosso cadastro, o preço usa centavos, os testes têm um comando e mudanças precisam respeitar o pedido. Essas orientações podem ficar em um arquivo do projeto. A regra de uma alteração específica fica na spec dessa tarefa.
O arquivo usado depende do agente. Neste material, mantemos CLAUDE.md e AGENTS.md como pontos de entrada para as instruções. Ao usar uma ferramenta, confira quais arquivos ela carregou e qual escopo se aplica. Não suponha que qualquer arquivo do repositório foi lido.
Exemplo curto de instruções do projetoexemplo
# Cadastro de Produtos
- Use Java e Spring conforme as versões do projeto.
- Preços são inteiros em centavos: 1000 = R$ 10,00.
- Leia a spec da tarefa antes de propor mudanças.
- Use ./mvnw test para executar os testes.
- Preserve alterações existentes que não pertencem à tarefa.
- Ao concluir, mostre os arquivos alterados e as verificações.
Stack é o conjunto de tecnologias do projeto, como Java e Spring. Convenção é um acordo que a equipe quer manter. Não há um número mágico de linhas. Prefira instruções relevantes, específicas e sem repetição. “Código bonito” não diz o que conferir; “não alterar a listagem nesta tarefa” é um limite observável.
Se uma instrução não foi seguida, investigue carregamento, escopo, conflitos e a implementação. Reescrever a frase pode ajudar, mas o erro não prova que ela estava mal escrita.
Escolha o destino de cada cartão. Instruções gerais, spec desta tarefa, documentação de referência ou configuração segura de credenciais?
Uma API permite que programas se comuniquem. Uma chave de API é uma credencial de acesso; seu valor não deve entrar nas instruções do projeto.
🗺️
Como comparar agentes
Avalie o trabalho produzido com a mesma tarefa
Você pode encontrar agentes no terminal, no editor ou em uma interface de conversa. Para acompanhar o curso, procure um fluxo que permita ler o projeto, propor mudanças, executar verificações e revisar o diff.
Integração
Consegue trabalhar no projeto usado pela turma e mostrar os arquivos alterados?
Controle
Você entende quais ações estão permitidas e como interromper ou limitar uma tarefa?
Evidência
É possível distinguir o que foi proposto do que foi executado e verificar os resultados?
Em aula, compare ferramentas com a mesma tarefa curta: recusar um preço negativo sem mudar a listagem. Observe leitura do contexto, clareza do plano, tamanho do diff e testes executados. Não conclua que uma ferramenta é sempre melhor a partir de uma única tentativa.
Disponibilidade de recursos, planos e limites muda. Confira as condições oficiais da ferramenta escolhida antes da aula. O objetivo aqui é aprender um procedimento de trabalho que você consiga repetir.
📝
SDD e o ritual de revisão
Do pedido ao critério de pronto, com um cadastro simples
📖 DA CONVERSA PARA UM DOCUMENTO
Spec, especificação, SDD e .specs/: cada nome tem uma função
Uma especificação descreve o resultado esperado e como verificar. Spec é a abreviação em inglês. Pode começar com poucas linhas: objetivo, regras e exemplos que mostrem quando deu certo.
SDD significa Spec-Driven Development: desenvolvimento orientado por especificações. Neste curso, escrevemos e revisamos o combinado antes da implementação, e depois usamos o documento para conferir o resultado.
.specs/ é a pasta escolhida para organizar esses textos. A barra final indica pasta; o ponto faz parte do nome. Não é um comando, não instala uma biblioteca e não faz o agente ler automaticamente. cadastrar-produto.md será um arquivo dentro dela. Markdown é texto simples com marcações: # indica um título.
JOGO GUIADO · A SUA PRIMEIRA SPEC
Da conversa à pasta .specs/
Você dirige os próximos passos. A IDE e o chat abaixo são simulados, sem conexão com uma IA e sem acesso aos arquivos do seu computador. Escolhas incorretas explicam o problema e permitem tentar de novo.
IDE da turma · cadastro-produtos
Boas-vindas
MINI CHAT · VOCÊ ↔ AGENTE
Você pode reformular o pedido. Este exercício sempre usa o cadastro de produtos: negativo é recusado e zero é permitido.
🔬 PAINEL DO LABORATÓRIO · PARE, APONTE E EXPLIQUE
ANTES
AÇÃO
DEPOIS
COMO PROVAR
Na árvore, src/ representa a pasta do código; pom.xml é o arquivo de configuração do projeto Maven. O botão de voz lê a explicação deste passo. O avanço acontece pelas suas decisões no mini chat. Recomeçar limpa somente esta simulação.
“Melhore o cadastro.” Melhore em qual sentido?
Beto quer aceitar mais produtos. Lia quer impedir preços inválidos. Sem esclarecer, a mesma frase pode levar a mudanças opostas. A spec registra o combinado e torna a revisão possível.
SDD, neste curso, é trabalhar a partir de uma especificação: descrever o comportamento esperado, propor um plano, executar e revisar o resultado. O documento ajuda a orientar; não garante que a implementação esteja correta.
1 · Esclarecer
Zero é permitido? Sim. Negativo? Não. Listagem muda? Não.
2 · Planejar e executar
Ler o cadastro; adicionar a verificação antes de salvar; testar três valores.
3 · Revisar
Comparar a condição, os casos executados e os arquivos alterados com a spec.
Spec curta — cadastrar-produto.mdexemplo
# Contexto
Existe um cadastro e uma lista de produtos.
O preço é um número inteiro em centavos.
# Tarefa
Recusar preço negativo antes de salvar o produto.
# Regras e limites
Zero é permitido. Preço positivo também.
Não alterar a listagem nem adicionar bibliotecas.
# Evidência de pronto
Testar -500, 0 e 1000 centavos.
Conferir que o produto recusado não entrou na lista.
Mostrar o diff e o resultado dos testes.
👀 Compare com um plano possível
1. Ler o método de cadastro e os testes existentes. 2. Adicionar a condição antes de salvar. 3. Testar os três valores e observar a lista após a recusa. 4. Executar os testes existentes e revisar o diff. Se a implementação real exigir outro arquivo, explicar por quê antes de ampliar o escopo.
O ritual de revisão
O que foi executado? Confira o comando e o resultado, não apenas “deu certo”.
Que casos foram testados? Positivo sozinho não demonstra recusa do negativo.
O código cumpre a regra? Observe a condição e se a validação ocorre antes de salvar.
Houve mudança fora do pedido? Confira a listagem, configurações e bibliotecas.
Consigo explicar? Diga o que acontece com -500, 0 e 1000 sem repetir a justificativa do agente.
EM SALA · APROVA OU DEVOLVE?
Três problemas numa entrega
A spec acima vale para esta entrega. Clique nos trechos que violam o combinado. Os trechos representam alterações em métodos existentes; não são um programa Java completo.
0 / 3 problemas encontrados.
🐛
Cinco erros recorrentes ao usar agentes
Pequenos incidentes, evidências e correções limitadas
Em cada incidente, discuta: qual é o problema, qual evidência sustenta o diagnóstico e qual é a menor correção útil?
1 · O método inventado
A resposta usa salvarComDescontoAutomatico(), mas esse método não existe no arquivo consultado.
👀 Ver investigação possível
Confira a classe e a mensagem do compilador. Use o método existente adequado ou esclareça a nova regra antes de criar outro.
2 · A pequena correção virou reforma
Você pediu recusar preço negativo; a entrega também reescreveu a listagem e mudou o visual.
👀 Ver investigação possível
Compare o diff com o escopo. Remova apenas as mudanças indevidas desta tarefa, preservando o trabalho anterior. Evite mandar “desfazer tudo” sem identificar o que será perdido.
3 · O verde insuficiente
O teste com 1000 passou. Ninguém tentou -500 ou zero.
👀 Ver investigação possível
Adicione os casos que faltam e observe se o produto recusado fica fora da lista. O sucesso só sustenta o que foi verificado.
4 · A dívida de compreensão
O cadastro funciona, mas você não sabe explicar por que existe um return antes de salvar.
👀 Ver investigação possível
Percorra o método com três entradas. O return encerra o método; no caso negativo, a linha que salva não deve ser executada.
5 · A regra descumprida
A regra de preço estava combinada, mas a entrega aceita negativos.
👀 Ver investigação possível
Não conclua automaticamente que “a mesa encheu”. Confira se a regra foi carregada, preservada e seguida. Corrija com base na evidência.
📐
Desenhe o loop
Primeira prancheta do curso. Cada exercício vai ter uma.
Ao longo do curso você desenha o que está construindo, antes e depois de pedir ao agente. Use o cadastro de produto como história: desenhe o
agente no centro, as ferramentas que ele usa no seu projeto (ler, editar, rodar) e o que alimenta a mesa dele
(CLAUDE.md, a spec, a conversa). Use a paleta SDD; ligue puxando o ● de um nó até o outro; dê
rótulo às setas com duplo clique. Fica salvo neste navegador e aparece na Prancheta do curso.
📐Desenhe: o agente, ler ProdutoService.java, editar a condição e testar preços; a regra entrando no contexto; o resultado do teste retornando ao agente; você revisando se -500 foi recusado e zero foi aceito. Depois clique em ▶ para ver a mensagem andar na ordem que você ligou.
✓
Do primeiro conceito à primeira especificação
Explique o ciclo com suas palavras e leve uma regra verificável
Peça
O que faz?
No nosso exemplo
Harness
Coordena o ciclo e as ferramentas.
Encaminha a leitura e devolve o arquivo ao modelo.
MCP
Padroniza uma conexão.
Aplicação consulta a ferramenta do catálogo.
RAG
Busca fontes para alimentar a resposta.
Preço e regulamento entram no contexto.
Fine-tuning
Ajusta o modelo por treinamento adicional.
Exemplos de classificação orientam um ajuste.
Essas peças podem trabalhar juntas. Não são quatro nomes para a mesma coisa nem quatro alternativas que se excluem.
🔮LLMPrevê o plausível. Confiança do texto não é sinal de qualidade; critério é.
📦ContextoMesa finita. Regra de projeto mora em arquivo; respostas precisam de evidência e revisão.
🦾AgenteLLM + ferramentas + loop. Termina quando ele acha que terminou.
📄CLAUDE.md / AGENTS.mdConvenções recorrentes e como verificar. Regras da tarefa ficam na spec.
📝SDDDescrever o comportamento → plano → execução → evidência → revisão.
Consegue explicar sem decorar? Como treinar difere de responder? Que informação entrou no contexto? O que sua spec promete? Que teste confirma essa promessa? Use o cadastro de produtos para responder.
🎫 O agente terminou e disse "Pronto, testes passando ✨". Qual é o seu próximo passo?
CLAUDE.md · AGENTS.md
📝 Especificações (SDD)