Passei as últimas semanas escrevendo posts sobre como uso AI coding agents. Rules. Skills. Subagents. Workflows. Cada post era confiante o suficiente pra parecer que eu sabia o que estava fazendo. Na maior parte do tempo eu sei, mais ou menos. Mas tem uma lista real de coisas sobre as quais eu ainda estou confuso, e fiquei hesitando em escrever sobre elas porque não encaixam no tom de “aqui está o que funciona pra mim.”

Vou escrever essa lista mesmo assim. Não porque vulnerabilidade é conteúdo — pode ser, e esse é outro post — mas porque acho a lista em si interessante. O formato daquilo que um praticante inicial-mas-não-iniciante ainda está resolvendo provavelmente diz algo útil sobre onde o campo realmente está.

Servidores MCP — mal arranho a superfície

MCP — o Model Context Protocol — é o que permite que agentes de IA conversem com sistemas externos através de uma interface padronizada. Já existe há um tempinho. Pessoas estão construindo servidores pra tudo: filesystems, bancos de dados, calendários, motores de busca, APIs internas customizadas. O modelo se integra com esses servidores e ganha um jeito estruturado de fazer coisas fora do seu próprio contexto.

Eu usei servidores MCP — o MCP do Slack, o MCP de documentação Context7, alguns outros. Funcionam. São úteis quando já estão configurados.

O que eu não fiz foi escrever um. Não sentei pra construir um servidor MCP pra um sistema interno customizado, expor a superfície certa, pensar em autenticação e rate limiting e tratamento de erros. A razão é honesta: eu ainda não precisei o suficiente pra superar a energia de ativação. Os MCPs existentes cobrem a maior parte do que eu quero.

O que eu suspeito estar perdendo é o momento onde escrever um MCP customizado se torna o movimento obviamente certo pra um problema específico. Imagino que esse momento é quando um agente precisa operar num sistema interno mais profundamente do que uma skill baseada em script consegue dar conta. Mas eu ainda não tenho experiência de primeira mão nisso.

O formato da minha lacuna: eu consigo usar MCP. Eu ainda não consigo projetar um. O modelo conceitual — estado no lado do servidor, registro de ferramentas, distinções entre resource versus tool versus prompt, como clientes negociam capacidades — ainda está um pouco nebuloso na minha cabeça.

Se você construiu um servidor MCP e tem opiniões sobre quando é a ferramenta certa versus quando uma skill baseada em script é suficiente, por favor me conte. A literatura atual é majoritariamente tutoriais; o que eu quero é a visão de engenheiro experiente.

LangGraph — copiei padrões sem entender totalmente o runtime

Essa é constrangedora. O projeto de agente em que trabalho é construído em LangGraph — um framework Python pra construir agentes de IA stateful, multi-step, usando um grafo de nós. Contribuí bastante código pra esse projeto. O grafo roda. Coisas passam por ele.

Mas se eu for honesto, meu modelo mental de como o runtime realmente funciona é mais nebuloso do que deveria. Sei as peças grandes — checkpointing, streaming, interrupção, composição de subgrafos, serialização — mas não tenho o modelo profundo que quero para os casos de borda. O que é salvo, quando, em que ordem? Como channels sobrepostos se comportam na fronteira de subgrafos? Por que alguns formatos de Pydantic passam pelo checkpointer sem problemas e outros não?

Já entreguei código funcionando apesar dessas lacunas. O padrão é: copiar uma forma que funciona em outro lugar do codebase, adaptar pro meu caso, rodar os testes. Quando algo é estranho, perguntar ao agente ou a um colega. O colega, em particular, tem um modelo muito mais profundo do LangGraph do que eu, e várias dessas lacunas só fecharam quando ele explicou o runtime pra mim.

Esse não é um modelo sustentável a longo prazo. O fato de eu conseguir entregar sem um modelo mental completo significa que o framework é bem projetado; não significa que eu posso continuar evitando a profundidade pra sempre.

O trabalho pra corrigir isso é meu. Parece com ler o código-fonte do LangGraph, construir alguns grafos de brinquedo do zero (não adaptados de existentes), e provavelmente escrever algumas notas-pra-mim-mesmo que eu teria vergonha de publicar.

Sutilezas de prompt engineering que eu continuo errando

Escrevi muitos prompts. De alguns eu tenho orgulho. De outros, olho seis meses depois e não reconheço.

O padrão nos que não envelhecem bem geralmente é que eu superespecifiquei na camada errada. Adicionei constraints muito frágeis, exemplos muito específicos, instruções que se contradiziam em edge cases que eu não antecipei. O prompt funcionava pro caso pra qual escrevi e produzia falhas surpreendentes quando o input desviava.

Coisas específicas que eu continuo errando:

• Ordem das instruções. Sei que importa. Não tenho um modelo confiável de qual ordem ganha de qual, além de “coisas importantes primeiro, exemplos depois das instruções.” Famílias de modelos diferentes parecem reagir de forma diferente a escolhas de ordenação, e eu não construí a intuição pra cada uma.
• Quando usar exemplos few-shot vs. quando eles atrapalham. Exemplos few-shot frequentemente ajudam. Mas também às vezes ancoram o modelo em padrões superficiais que não generalizam. Já vi os mesmos exemplos melhorarem o output numa tarefa e degradarem em outra. Não consigo prever qual com confiança.
• Instruções negativas. “Não faça X” é famosamente frágil. O modelo frequentemente faz X de qualquer jeito, ou evita X evitando Y, que era o que eu realmente queria. Tenho heurísticas (“reformule como instruções positivas quando possível”) mas nenhum modelo profundo.
• Os tradeoffs de temperature/sampling. Geralmente deixo os defaults. Sei que há tarefas onde temperature mais baixa ajudaria e outras onde mais alta ajudaria. Não rodo minhas próprias avaliações pra descobrir qual.
• Modelos reasoning vs. não-reasoning. Os modelos reasoning mais recentes se comportam diferente dos instruction-tuned. Prompts que funcionavam muito bem na geração anterior às vezes performam pior na nova. Me adaptei por tentativa e erro ao invés de por compreensão.

O fio que conecta essas lacunas é que venho escrevendo prompts como um ofício — por feeling, com iteração. Não construí o equivalente de uma prática empírica, onde rodo comparações controladas e aprendo com os resultados. Essa prática é o que transformaria o ofício em engenharia. Eu não comecei.

Infraestrutura de avaliação na qual eu realmente não investi

Esta é a meta-versão da lacuna anterior. Construir estruturas de avaliação rigorosas — pequenos conjuntos de entradas de teste que pontuam outputs de modelos contra comportamentos esperados — é o jeito do engenheiro maduro de superar o prompt engineering no feeling.

Tenho um ou dois desses. Na maioria pequenos, na maioria informais. Pegam regressões óbvias e perdem sutis.

O que eu não construí é a infraestrutura pra rodar uma avaliação significativa rotineiramente: um dataset marcado de inputs representativos, rubrics de pontuação que produzem números comparáveis entre execuções, um jeito de ver “essa mudança de prompt melhorou o score em X” de uma forma que eu realmente confie.

A razão é a mesma da lacuna de MCP, na maioria: consigo entregar sem isso, aceitando alguma volatilidade na qualidade do output. O custo de construir é real, e o retorno imediato é incerto porque a maioria dos prompts que escrevo hoje não sobrevive tempo suficiente pra merecer o investimento.

Acho que isso está errado. Eventualmente deveria construir o harness. Quanto mais eu espero, mais efeito composto eu perco.

Padrões de coordenação multi-agente

Tenho um subagent em uso regular (o revisor de segurança) e um punhado de outros agentes que ocasionalmente são criados pra trabalho em paralelo. Não construí nada que se qualificaria como sistemas coordenados multi-agente — múltiplos agentes especializados que passam trabalho entre si, negociam sobre estado compartilhado, ou rodam em loops colaborativos de longa duração.

A literatura aqui está agitada. Tem papers, frameworks e argumentos. Alguns parecem genuinamente promissores; outros parecem soluções em busca de problemas. Não tenho experiência pra distinguir.

O que eu gostaria de saber melhor:

• Quando o overhead de coordenação multi-agente compensa, versus um único agente com as rules e skills certas?
• Quais padrões se sustentam sob cargas reais, e quais ficam bonitos em demos e desmoronam em produção?
• Como falhas de coordenação aparecem, e como você faz debug delas?

Até eu ter respostas que consiga defender, vou ficar no padrão de agente-pai-único-com-subagents-ocasionais, que tem funcionado. Migrar pra uma configuração mais elaborada antes de entender os tradeoffs seria prematuro.

Fine-tuning — nunca tentei de verdade

Fiz zero fine-tuning de modelos de linguagem. Leio sobre o assunto. Vejo outras pessoas fazendo. Nunca produzi um modelo fine-tuned eu mesmo, nem pra um projeto de hobby.

Por que a lacuna existe: toda vez que considerei fine-tuning, a pergunta “um prompt melhor ou um modelo menor com o contexto certo me levaria 90% do caminho?” respondeu sim. Fine-tuning ficou abaixo do limiar de “o próximo passo óbvio.”

Pode continuar sendo verdade. Também pode deixar de ser em algum momento — pra tarefas onde o prompt certo é longo demais, ou onde o budget de latência descarta um modelo grande, ou onde o caso de uso é repetitivo o suficiente que um modelo pequeno especializado claramente ganharia.

O que eu quero saber: quais sinais indicam que fine-tuning é o movimento certo? E inversamente, quais sinais aparentes são pistas falsas que levam pessoas a fazer fine-tuning quando não deveriam?

O que estou fazendo a respeito

Não estou parado, mas também estou tentando não mexer superficialmente em tudo ao mesmo tempo. A primeira área em que eu deveria me comprometer de verdade é infraestrutura de avaliação, porque evals melhores tornam possível uma prompt engineering melhor, e prompt engineering melhor torna possíveis skills e subagents melhores. Depois disso, provavelmente os internals do LangGraph, porque o projeto em que trabalho os usa diariamente.

Servidores MCP, coordenação multi-agente e fine-tuning podem esperar até ficarem mais perto do meu trabalho atual.

Um pequeno pedido

Se alguma dessas coisas é algo que você sabe bem, quero aprender com você. Ninguém tem um mapa completo deste território ainda, e fingir o contrário envelhece mal.

Se você tem algo pra me ensinar — sobre MCP, LangGraph, avaliação, prompts, qualquer outra coisa da lista — por favor mande. Vou ler com atenção.