Do prompt ao agente: como amadureci a forma de trabalhar com IA

Voltei à atuação técnica hands-on depois de alguns anos longe do teclado, mais perto de planilhas de governança do que de terminal. Quando reabri o editor, a ferramenta que mais mexeu com a minha prática não foi um banco novo nem um framework: foi a forma de trabalhar com um assistente de IA dentro do fluxo de desenvolvimento. O que segue não é tutorial. É o relato honesto de uma curva de maturidade, em três estágios, onde cada degrau resolveu uma dor que o degrau anterior tinha exposto.

Uso esses estágios também em sala de aula, porque eles ilustram bem uma ideia antiga de engenharia: a melhor automação não nasce da empolgação com a ferramenta, nasce do incômodo de repetir trabalho.

Estágio 1: o prompt no chat, e o teto que ele tem

Comecei como quase todo mundo: conversando. Aprendi a escrever prompts melhores, dar contexto, pedir o formato de saída, mostrar exemplos do que eu queria e do que eu não queria, pedir o raciocínio passo a passo. O ganho é real e imediato. Um prompt bem construído transforma uma resposta vaga em algo aproveitável.

O problema apareceu na repetição. Prompt resolve uma pergunta, não um trabalho recorrente. Toda vez que eu precisava do mesmo tipo de saída (revisar um trecho de SQL, padronizar a mensagem de um incidente, estruturar um runbook), eu reconstruía o contexto do zero. O conhecimento de como pedir bem ficava na minha cabeça e no histórico do chat, não em lugar nenhum reutilizável. Eu estava otimizando o tiro, não a arma.

Esse foi o primeiro insight: prompt é ótimo para o que acontece uma vez. Para o que se repete, ele vira custo.

Estágio 2: skills, ou encapsular o "como eu faço isso"

O segundo degrau foi descobrir que dá para empacotar um processo inteiro, não só um prompt. No ecossistema do Claude Code isso se chama skill: um diretório com um arquivo de instruções (o SKILL.md) que descreve quando aquele conhecimento deve ser usado e como executá-lo, com a opção de carregar arquivos de apoio só quando necessário (o conceito de divulgação progressiva, para não inflar o contexto à toa). A skill é invocada pelo próprio modelo quando a descrição casa com o que você pediu, então o gatilho deixa de ser você lembrando e passa a ser a tarefa em si.

Na prática, foi aqui que comecei a transformar conhecimento tácito em ativo. Um processo de governança que eu repetia, a forma de redigir uma comunicação técnica padronizada, a estrutura de um material didático: cada um virou uma skill com critério de qualidade embutido. O conhecimento saiu da minha cabeça e virou algo que sobrevive a mim, versionável, corrigível.

A dor que esse estágio expôs foi mais sutil. A skill organiza o "como", mas ainda sou eu quem orquestra passo a passo, e ela depende do modelo decidir usá-la. Funciona quase sempre, e "quase sempre" é exatamente o problema quando o custo do erro é alto. Quem trabalhou em ambiente regulado sabe: processo que depende de alguém (ou de um modelo) lembrar de executar não é processo, é sorte com boa documentação.

Estágio 3: agentes e hooks, delegação com determinismo de volta

O terceiro degrau resolveu as duas pontas dessa dor com duas ferramentas de naturezas opostas.

Os agentes (subagentes) resolveram a orquestração. Em vez de eu conduzir cada passo, passei a delegar tarefas multi-etapa a um agente com contexto próprio, ferramentas próprias e um objetivo definido: pesquisar em vários arquivos e voltar só com a conclusão, ou tocar uma rotina mais longa sem poluir a conversa principal. É a diferença entre fazer junto e mandar fazer.

Os hooks resolveram o determinismo, e para mim foram a virada conceitual mais importante. Hook é um gatilho de ciclo de vida que dispara um comando de shell em momentos específicos da sessão: antes de uma ferramenta rodar (PreToolUse), depois (PostToolUse), ao iniciar a sessão (SessionStart), quando um prompt é enviado (UserPromptSubmit), entre outros eventos. Eles vivem no settings.json do projeto e não dependem do modelo "lembrar" de nada. Um PreToolUse que retorna código de saída 2, por exemplo, bloqueia a ação antes de ela acontecer.

Aqui está o ponto que demorei a entender e que hoje ensino assim: a IA generativa é probabilística por construção, e isso é uma virtude para gerar e uma fraqueza para garantir. Hook traz o determinismo de volta exatamente onde ele não pode faltar. Validar antes de executar, formatar depois de escrever, registrar o que aconteceu: nada disso pode ficar a cargo da boa vontade estatística do modelo. O hook é a regra que sempre roda. O agente é o trabalhador que você delega. A skill é o manual que ele consulta. Os três operam em camadas, não competem.

O fio que costura os três estágios

Olhando para trás, a progressão não foi sobre a ferramenta ficar mais poderosa. Foi sobre eu mudar a pergunta. Saí de "como peço melhor" (prompt), passei por "como guardo o jeito de fazer" (skill) e cheguei em "como garanto que aconteça sem mim no circuito" (agentes e hooks). É a velha primeira virtude do programador que Larry Wall descreveu no glossário de Programming Perl: a preguiça produtiva, "a qualidade que faz você se esforçar muito para reduzir o gasto total de energia". Você investe agora para não repetir depois.

Onde isso aterrissou, na prática, foram projetos pessoais que usei como laboratório: um sistema de locação voltado ao agronegócio, um produto próprio de dados e uma automação para a rotina de um escritório de contabilidade. Não vou detalhar nenhum deles aqui, e de propósito; o que importa para este texto é que foram o banco de provas onde a teoria virou cicatriz. Foi mexendo neles que entendi onde cada estágio ganha e onde cada um cobra seu preço.

A fronteira: quando o degrau mais alto é desperdício

Seria desonesto terminar vendendo agentes e hooks como destino de todo mundo. Eles compensam quando há duas condições juntas: recorrência (você vai fazer aquilo muitas vezes) e custo de erro relevante (falhar dói, em retrabalho, incidente ou compliance). É o cenário de produção, de ambiente regulado, de processo que precisa ser auditável.

Fora disso, o degrau mais alto vira sobre-engenharia. Numa exploração única, num spike de descoberta, num protótipo antes de validar o problema, montar skill, agente e hook é gastar energia para economizar energia que você talvez nunca gaste. Ali o prompt no chat, rápido e descartável, continua sendo a escolha mais inteligente. O critério nunca é "qual é a ferramenta mais avançada", é "qual é o custo de errar e quantas vezes vou repetir isto".

Continuo no meio dessa curva, aprendendo. A dúvida honesta que ainda carrego é sobre o equilíbrio: quanto determinismo via hook é proteção e a partir de quando vira rigidez que sufoca a parte criativa do trabalho com IA. Não tenho a resposta fechada, e desconfio de quem tem. Por enquanto, o que aprendi cabe numa frase: a maturidade no uso de IA não está em pedir melhor, está em saber qual camada cada problema merece.

Referências: as três virtudes do programador estão no glossário de Programming Perl (O'Reilly), de Larry Wall et al. A documentação de hooks, skills e subagentes do Claude Code está em code.claude.com/docs.