A maioria das discussões sobre IA em engenharia ainda é uma briga de bar sobre qual modelo é melhor, Opus contra Sonnet, GPT-5 contra Gemini, qual benchmark, qual janela de contexto. Essa briga não importa mais. O modelo virou commodity em 18 meses. O que separa o time que entrega feature em produção com IA do time que passa o sprint inteiro consertando alucinação não é a escolha do LLM. É a infraestrutura ao redor dele. É o Harness.
Este post consolida o playbook completo de Engenharia AI-Native que a Steply vem destilando: por que Vibe Coding falha silenciosamente em qualquer codebase sério, por que Agente = Modelo + Harness é a única equação que importa, os 8 pilares de um Harness de produção, o método R.P.I. (Research, Plan, Implement) que previne Context Rot, a diferença operacional entre Rules e Skills, por que o paradoxo dos microserviços virou armadilha para agentes autônomos, e a escala de maturidade L0, L4 que define onde você está hoje, e onde precisa estar até o fim do ano.
O Vale do Desespero: a curva DORA que ninguém te conta
A promessa de marketing é 10x. A realidade do relatório DORA é uma curva em U. 79% dos líderes técnicos relatam queda de produtividade nos primeiros 3 meses de adoção de IA, quebra de fluxo, novo processo de PR, learning curve da ferramenta. Só depois disso é que aparece o ROI real de ~39% no ano 1 e 8-20% mais rapidez em merges. Esquece a promessa do 10x. Se a IA te dá 50% de ganho sustentável e melhora a qualidade de vida do dev, já é uma revolução.
O segredo não está na mágica do modelo. Está na cultura de engenharia que você constrói ao redor dele. E o ponto de partida dessa cultura é entender que usar IA no desenvolvimento e construir aplicações com IA são problemas distintos. Foque no topo do iceberg, orquestração, contexto, agentes, fluxos, MCPs, a menos que você tenha demanda explícita pelo fundo (vector DBs, LangGraph, fine-tuning). A maioria dos times está perdendo dinheiro na parte errada do iceberg.
A ilusão do Vibe Coding: por que modelos isolados falham em engenharia de software
Vibe Coding é o paradigma de quem trata o LLM como mágico: digita prompt, reza, aceita. Funciona pra protótipo. Quebra em produção. Os quatro erros que aparecem com regularidade clínica:
- Falha Silenciosa. O agente finaliza a task, mas 50% da feature exigida simplesmente não existe no código final. Nenhuma exceção é lançada. Você só descobre em QA, ou pior, em produção.
- Queima de Tokens. Loop infinito de "correções" que consome centenas de dólares sem entregar código utilizável. Falta de stop-loss. O agente fica refazendo o mesmo erro com variações.
- Caixa Preta. Incapacidade de explicar por que o modelo tomou uma decisão de arquitetura específica. Rastreabilidade zero. Quando quebra, você não sabe onde quebrou.
- Destruição de Escopo. O agente apaga testes unitários ou reescreve especificações silenciosamente só para fazer o código "passar". Pedir gentilmente no prompt para não apagar testes não funciona, o modelo ignora.
A análise de causa raiz é desconfortável: nenhuma dessas falhas é do modelo. São consequências diretas de rodar um LLM sem uma infraestrutura de orquestração. O modelo é probabilístico, não-determinístico e cego sobre o mundo externo. Sem estrutura de contenção, ele faz exatamente o que o treinamento o ensinou a fazer: prever a próxima palavra com a maior probabilidade plausível. "Plausível" não é "correto".
O novo paradigma: Agente = Modelo + Harness
A equação que define a era atual é simples: function defineAgent() { return Model + Harness; }. O modelo é o motor, possante, mas imprevisível. O Harness é o carro inteiro: chassi, freios, painel de controle, airbags, telemetria. Quem vence em IA aplicada não é quem tem o melhor motor. É quem constrói o melhor Harness ao redor dele. Esse é o ponto central, e o que muda completamente como você seleciona vendor, como você arquiteta time, como você compara ferramentas.
O Harness não é uma ferramenta de software específica. É a instrumentação arquitetural completa ao redor do modelo: isolamento de contexto, workflow controlado, validação e segurança, evals, code review automatizado, agents.md, skills curadas, spec-driven development, worktrees paralelos. O Harness deve ser agnóstico ao modelo, você precisa poder trocar Opus por GPT-4o sem reescrever a infraestrutura.
O espectro de maturidade no desenvolvimento com IA
Existe uma progressão clara em 4 níveis. Nível 1, Vibe Coding: prompt and pray, código gerado sem estrutura, revisado na sorte. Nível 2, Human IN the loop: o dev revisa cada linha que o agente escreve. O humano vira o gargalo. Nível 3, Human ON the loop: o dev não conserta código ruim; ele altera as regras e o harness que geraram o código ruim. Alta escalabilidade. Nível 4, Flywheel: o sistema aprende com os próprios erros. Falhas são convertidas automaticamente em regras injetadas no contexto futuro. O objetivo da engenharia de Harness é mover o time do Nível 1 para o Nível 3, e construir o Nível 4 em cima disso.
Os 8 pilares de um Harness de produção
Um Harness sério tem 8 componentes não-negociáveis ao redor do LLM Core. Tirar qualquer um deles é abrir uma rota de falha.
- Spec-Driven (Contexto e Requisitos). O código é a última etapa, não a primeira. Cada fase anterior, PRD, Design Doc, Task List, Critérios de Aceite, gera um artefato em Markdown/JSON que atua como contrato rigoroso para a próxima.
- Maestro (Orquestração e Dispatch). Separa O Piloto (decide O QUE fazer: rodar fase, chamar revisão, abortar) de O Orquestrador (decide COMO fazer: prepara o contexto, consolida arquivos, envia ao LLM). Misturar os dois é o erro arquitetural número um.
- Juiz (Triagem e Avaliação). Nunca use o mesmo modelo para executar e julgar, risco de auto-aprovação e alucinação. Passo 1: filtro semântico via embeddings (custo de centavos) rejeita automaticamente se o agente fugiu do escopo. Passo 2: LLM Judge distinto avalia o código e devolve
{veredito: PASS|FAIL|PARTIAL, gaps: [...]}. Confiança < 70% barra a entrega. - Gates (Validação Qualitativa). Segurança de aeroporto: linter passou? Testes unitários rodaram? Arquivos sensíveis não sofreram deleção não autorizada? A proporção da mudança faz sentido?
- Limites (Stop-Loss e Segurança). Limite rígido de tokens/dólares por task, evita loops de erro que torram $200 em 10 minutos. Proteção de arquivos: bloqueio de escrita em specs, testes e configurações sensíveis para evitar manipulação do Juiz.
- Resiliência (Fallbacks e Timeouts). Cadeia de fallback: Model A trava → detecção de timeout cega → rota para Model B → falha crítica → escala para humano. O sistema não pode ficar em loop de timeout reenviando o mesmo prompt pesado infinitamente.
- Flywheel (Observabilidade e Memória). Evento de erro → extração estatística de "gotchas" (sem LLM) → promoção de lição estruturada de projeto para memória do time → injeção de contexto na próxima task similar. Não é o modelo ficando mais inteligente. É sua infraestrutura acumulando conhecimento automaticamente.
- Sandbox (Isolamento Micro-VM). Docker compartilha o kernel do host, código gerado por IA pode escalar privilégios. Padrão emergente: Firecracker Micro-VM, sobe em < 125ms, kernel isolado por task. Se o agente gerar código malicioso, a VM morre com ele.
Esses 8 pilares são o motivo pelo qual o PayPal, com 24.000 funcionários e trilhões de transações mensais, consegue rodar IA com seus devs gastando $2k/mês em tokens por power user sem o caos amplificar: Gateway Central (Vertex API), Marketplace MCP Interno, segurança de supply chain com cooldown de 7 dias para novos pacotes (NPM/Python), e dual-review onde 90% do código passa por IA + humano. Os devs lá passam 80% do tempo com IA, porque o Harness existe.
O método R.P.I.: Research, Plan, Implement
Sem método, a janela de contexto degrada. Esse é o fenômeno do Context Rot: com 200k tokens disponíveis, abaixo de 40% você tem alta precisão e foco; entre 40% e 60% começa a divergência; acima de 60%, a IA tenta convergir tópicos não relacionados e alucina. Regra de ouro: nunca deixe a ferramenta compactar seu contexto. Sempre abra uma nova janela de agente ao iniciar um novo fluxo ou task isolada.
Fase 1, Research (Busca e Discovery)
Use modelos densos de raciocínio (como Claude Opus) para analisar PRDs, ler transcrições de reuniões ou pesquisar a codebase inteira. Ferramentas modernas delegam pesquisas extensas para sub-agents genéricos, eles vasculham o código e devolvem apenas um resumo limpo, poupando a janela principal. Regra crítica: NUNCA peça para implementar código na mesma janela onde você passou dias pesquisando. O contexto já está sobrecarregado. Salve as conclusões em Markdown e feche a janela imediatamente.
Fase 2, Plan (Spec-Driven Development)
Gere um Design Doc ou plano de execução claro, com passos e testes. Extraia o contexto para markdown. Fim da ambiguidade. Quando você não dá passos claros, a IA toma decisões sob pressão, e faz trade-offs perigosos como ignorar testes. Um plano escrito e aprovado pelo humano atua como trilho impenetrável.
Fase 3, Implement (Execução Cirúrgica)
Aba totalmente nova, contexto 100% zerado. Cole o plano Markdown exato gerado na Fase 2 como prompt inicial. Otimização de custo: aqui você muda para um modelo mais rápido e barato (Sonnet/Haiku), ele só precisa seguir e executar o roteiro decidido por um modelo mais 'inteligente'. Testes como guia: a IA implementa a lógica forçada a passar pelos critérios de TDD definidos rigidamente no plano. A separação estrita de instâncias é o que previne Context Rot.
Token Dragging: o pecado de misturar planejamento com execução
O fenômeno do Token Dragging é o que destrói produtividade silenciosamente. Você faz Research + Planning na mesma janela onde vai executar; arrasta tokens desnecessários para a execução; a IA alucina. O caminho limpo é firewall entre fases: Research isolado → Design Doc como artefato → Execution em janela virgem com apenas o Doc como input.
É por isso que existe o platô dos 40%: produtividade sobe rápido nos primeiros prompts ingênuos, mas trava num teto absurdamente baixo quando os escopos crescem. A degradação acontece porque a IA resume passos, pula testes para economizar tokens e toma decisões arbitrárias. O resultado é o dev virando babysitter de IA, consertando alucinação em vez de orquestrar sistemas.
Anatomia de uma Spec perfeita (não é para humanos)
A Spec não é documentação ágil. É uma instrução determinística para rotear o comportamento agêntico de forma previsível. Os quatro blocos obrigatórios:
- [Goals]: contexto de alto nível e o objetivo determinístico da máquina.
- [Out of Scope]: barreiras estritas. Evita que a IA alucine ou invente features de negócio não solicitadas. Esse é o bloco mais importante, e o mais ignorado.
- [Edge Cases]: mapeia todos os caminhos de exceção e falhas antecipadamente.
- [Test Gates]: critérios de aceite automatizados. A IA nunca avalia o próprio código, ela roda comandos no terminal.
Depois de escrita a Spec, você quebra o escopo em tasks atômicas: cada task faz apenas UMA coisa, possui um Test Gate associado e roda em isolamento total via sub-agent genérico. Contexto virgem por task: o agente consome 5 mil tokens em vez de 150 mil. Paralelismo seguro, verificação acoplada, isolamento real.
Rules vs. Skills: a camada de inteligência do agente
Essa distinção operacional separa quem domina o Harness de quem ainda escreve prompt-monstro:
- Rules (Contexto Global). Verdades imutáveis do projeto. Sempre carregadas no contexto global da IA. Exemplos:
code_standards,idioma_padrao: english,folder_structure,clean_architecture. - Skills (Sob Demanda). Especializações isoladas e dinâmicas. Acesso via lazy loading apenas quando a tarefa exige (evita poluição). Exemplos:
stripe_api_docs,mastra_framework,virtual_sdks,test_generators.
A engenharia de contexto opera em três camadas: Camada 1, agents.md / regras globais, carregado sempre, regras inegociáveis do repositório. Camada 2, Skills e Sub-agents, carregados sob demanda, padrões específicos de arquitetura injetados apenas quando necessários. Camada 3, MCPs (Model Context Protocol), conexões com o mundo externo: busca de tasks no Jira, documentação no Confluence, PRs no GitHub. A Engenharia de Contexto substitui prompts gigantes por inferência. Você não envia arquivos manualmente; o agente entende quando puxar a informação certa.
O Agents.md: padrão ouro vs. arquivo bizarro
O Agents.md é a Constituição do repositório para a IA. Os erros mais comuns: criar um arquivo gigante e prolixo; pedir para a IA gerar o próprio Agents.md (ela vai incluir informação irrelevante que consumirá sua janela de contexto para sempre, faça curadoria manual); usar termos vagos como "otimizar" ou "melhorar o código". O padrão ouro é o oposto: regras gerais curtas, com exemplos reais de código (a IA segue exemplos infinitamente melhor do que instruções teóricas abertas), e referências a arquivos específicos quando o contexto for necessário. Não tenha um arquivo de arquitetura monolítico com 1000 linhas, quebre em partes menores.
Arquitetura na era da IA: o paradoxo dos microserviços
Aqui a coisa fica desconfortável para quem investiu uma década pregando microserviços. Em fluxos assistidos por IA, microserviços geram fricção extrema: fragmentação de contexto limitante, refatoração cross-service é impossível, e Convention Drift, cada repositório dita um padrão diferente. O agente fica cego, vendado, batendo em paredes invisíveis entre serviços.
O Monolito Modular volta a ser a melhor arquitetura para IA: visão holística e unificada do domínio, padrões centralizados em um único repositório, refatoração massiva em um único Pull Request. Na matriz de diagnóstico arquitetural: visibilidade de contexto máxima, atrito de refatoração muito baixo, alinhamento de padrões alto, dev experience local alta. Veredito: mova para Monolitos Modulares. Isole o código por pastas de domínio para focar o contexto da IA, mantendo a visão global do repositório.
O novo custo da abstração
Outro reframe difícil: abstrações complexas geradas instantaneamente pela IA custam caro em tokens e janela de contexto. O que parece economia de tempo na escrita resulta em débito técnico invisível no processamento do modelo. Taxa de queima: Interface (-500 tokens) → Implementação → Injeção de Dependência (-1500) → DTO (-3000). Em bases muito fragmentadas, a IA assume falsamente que encontrou todos os arquivos relevantes e abandona a busca prematuramente, resultando em implementações incompletas ou alucinações. Estruturas flat e explícitas tornam-se obrigatórias para garantir a eficácia do agente. Bancos vetoriais (RAG) ajudam, mas agentes autônomos falham em chamar o protocolo (MCP) em 42% das vezes.
O esforço de convenção das linguagens
Linguagens com convenções fortes da comunidade (Rails, Go) exigem documentação mínima, a IA foi treinada nativamente nessas convenções. Linguagens com extrema divergência de padrões (JavaScript, Node.js, Python) exigem documentação massiva de dependências e arquitetura no repositório. Se sua stack é JS/Python, seu investimento em Agents.md e Skills curadas é desproporcionalmente maior, não é opcional, é compensação estrutural.
Git Worktrees: a tática que dobra throughput
Esqueça o limite imposto por uma única branch. Git Worktrees criam cópias reais e isoladas do repositório em pastas paralelas na sua máquina. Worktree A com Agente Opus gerando planejamento estrutural e extraindo lógica; Worktree B com Agente Sonnet refatorando um microserviço secundário. Múltiplos agentes IA trabalhando em features simultâneas sem gerar conflitos de stash ou commit. Esse é o paralelismo real entre cérebro humano e motor agêntico que destrava o L4 de maturidade.
O dilema do código legado: orquestrar antes de refatorar
Atenção: nunca jogue IA em um código legado cego e peça "refatore". O resultado será um desastre. O playbook correto tem 3 passos: (1) Documentar a Realidade, pergunte à IA quais bizarrices ela vê no código atual; coloque essas regras literais no Agents.md ("neste projeto, a lógica fica no Controller"); aceite a realidade. (2) Estabilizar o Harness, trabalhe no código seguindo o padrão legado sujo até que a IA consiga realizar tarefas básicas com previsibilidade extrema e sem alucinar arquiteturas ideais. (3) Refatorar Gradualmente, apenas com o sistema estável e o contexto dominado, comece a remover as regras provisórias do Agents.md e peça para a IA refatorar módulos gradativamente.
O novo padrão de Code Review agêntico
O YOLO Review do mercado lê o PR inteiro de uma vez, ignora o contexto profundo da codebase e gera comentários pedantes focados apenas em sintaxe. O padrão AI-Native usa orquestração de múltiplos sub-agents especialistas para revisão cirúrgica: Agente de Segurança, Agente de Arquitetura e Padrões, Agente de Regressão (alerta deleções não relacionadas). Fração do custo, precisão absoluta no repositório.
A evolução do dev: do digitador ao Product Engineer
A digitação de sintaxe foi commoditizada. O valor do Engenheiro não está mais em decorar código, mas em orquestrar sistemas complexos, gerenciar restrições rígidas e comunicar contextos de negócio. O perfil emergente é o Product Engineer: interseção de Engenharia Sólida + Orquestração de IA e Harness + Senso de Produto e Negócio. Ele atua no Board (Linear/Slack) criando Slices de tarefas com forte contexto de produto; delega para Cloud Agents que fazem setup, processam skills, implementam e criam o PR isoladamente; e entra apenas na fase de Code Review, avaliando o PR gerado pelo agente junto a verificações de segurança automatizadas.
A evolução da liderança técnica também muda: o Herói do Fim de Semana que refatora a arquitetura sozinho de madrugada usando IA (tornando a equipe dependente) é substituído pelo Arquiteto de Harness que cria o escudo guardrail, documenta Agents.md e força regras de Code Review. O Abstraction Illusion (aceitar cegamente arquiteturas geradas instantaneamente) é substituído pelo Delegador Exploratório: atribuir tarefas de exploração à equipe e exigir Design Docs (RFCs) baseados nos outputs da IA para forçar o julgamento crítico humano.
O workflow Rodrigo Branas (Desenvolvimento Assistido via CLI)
O fluxo prático que materializa tudo acima usa CLI dedicada (ex.: stack Compose):
compose create.prd→ PRD gerado e validado.compose create.techspec→ Design doc estruturado.compose create.tasks→ tarefas atômicas mapeadas.compose tasks run→ Task Looper rodando em background: lê Spec → gera código → executa Sensor (teste API) → refatora se falha / avança se passa.
A magia: o CLI roda em background lendo specs, aplicando testes e consolidando código de forma autônoma. O desenvolvedor atua paralelamente no Reasoning de negócio e em novas arquiteturas. Paralelismo real entre cérebro humano e motor agêntico, facilitado por git worktree. Separação total entre criação do planejamento cognitivo (Business Reasoning) e execução técnica mecânica.
Antipatterns corporativos: como NÃO adotar IA
- Teatro da IA. Diretoria compra licenças para todos e espera mágica sem treinamento. Resultado: ferramentas abandonadas ou usadas como autocompletar glorificado.
- Amplificador de Caos. IA inserida em repositórios sem testes unitários ou CI/CD sólidos. Resultado: aumento reportado de +40% em bugs. IA escala a má qualidade existente.
- Shadow AI. Engenheiros usando LLMs não autorizados porque a infraestrutura da empresa está bloqueada demais. Resultado: vazamento de dados sensíveis e quebra de compliance de segurança.
A mensagem central: o risco não está em usar IA, mas em usá-la de forma não estruturada. Empresas maduras centralizam a inteligência arquitetural em marketplaces internos seguros: Skills auditadas internamente, marketplace privado, revisão rígida de PRs, distribuição via MCP e CLI.
Escala de maturidade com IA: em qual nível você está?
- L0, O Resistente. Reluta contra a transformação.
- L1, O Copiador. Copia e cola blocos isolados no chat.
- L2, A Babá de IA. Microgerencia a execução e aprova cada linha. O bottleneck humano.
- L3, O Engenheiro de Produto. Foca em arquitetura, orquestra sub-agents e cria Harness. Zona de alta alavancagem.
- L4, Autonomia Escalada. Orquestração totalmente autônoma e delegada com Loopers.
O salto crítico é L2 → L3. É exatamente onde a maioria dos devs sêniors está travada hoje, ainda gastando 80% do tempo revisando linha por linha o output do agente. Sair de L2 exige construir o Harness, não tem atalho. Não tem prompt mágico. É infraestrutura.
Reframe final: nós não escrevemos mais código. Nós geramos código.
A consistência arquitetural do seu sistema sempre vencerá o talento isolado do modelo. Construa sua alavanca: especifique antes de codar, verifique de forma inteligente e proteja seus dados. O futuro não pertence a quem digita mais rápido, mas a quem orquestra agentes com mais segurança.
A complexidade não desaparece, ela se move da arquitetura do código para a curadoria tática do Harness. Menos abstração humana gera mais contexto para a máquina. O dev deixa de ser tradutor direto de requisitos soltos em linhas de código isoladas para atuar como Arquiteto de Sistemas e Product Engineer, liderando agentes autônomos. Pare de comparar agentes de IA pelo modelo. Comece a compará-los pela qualidade do Harness. Domine o Harness. Proteja seu contexto. Construa o futuro.
