Do vibe ao production-grade

A rotina mudou por completo. Antes, o dia era cavar documentação de API, testar código linha por linha, descobrir se a linguagem usa substring in string, string.includes() ou string.contains() — e debugar a distância entre o código funcional e a intenção original. Hoje, coding agents como Antigravity e Gemini CLI não apenas sugerem texto: usam ferramentas, executam tarefas e despejam mil linhas documentadas em minutos.

O problema: a Illusion of Speed é real. O bug-to-code ratio continua sendo um desafio — a IA escreve muito mais rápido, mas também gera erros potenciais em taxa sem precedentes. E quando um agente alucina (o modelo inventa confiantemente algo que não é verdade), ele não cria um bug: cria mil linhas de lógica "vibe-consistent" e funcionalmente quebrada.

No mundo tradicional, devs são ensinados a ser "Code-First": ideia vaga → abrir o editor → digitar até algo funcionar. Na era da Agentic AI, a maior parte do tempo vira escrever especificações de alta qualidade — instruções técnicas detalhadas que dizem à IA exatamente o que construir. O papel do dev se aproxima mais de technical architect do que de coder tradicional.

Coding agents usam o LLM como cérebro (raciocinar) e ferramentas como mãos (executar). A consequência direta:

Uma spec production-grade funciona como Architectural North Star: previne a "context fragmentation" — o equivalente digital do jogo "telefone sem fio", em que a IA perde o fio da meada porque olha snapshots desatualizados de arquivos. A IA pode ser co-autora ou revisora da spec; ela vive no codebase (pasta specs/, em Markdown ou YAML) e age como source of truth para humanos e máquinas.

O que uma spec de projeto novo contém

O estudo SkCC (Ouyang et al., 2026 — "Portable and Secure Skill Compilation for Cross-Framework LLM Agents") mostrou que agentes exibem sensibilidade extrema a como instruções são formatadas: até 40% de queda de performance com Markdown genérico não otimizado. Os pesquisadores criaram o SkCC (Skill Compiler): uma ferramenta ultrarrápida que compila o arquivo de instrução single-source para o formato-alvo ótimo do modelo em menos de 10 milissegundos.

Uma spec BDD é a ferramenta final para transformar ideias vagas e ambíguas em design preciso que o agente pode construir sem adivinhar. Behavior Driven Development usa linguagem natural simples e estruturada para descrever exatamente como o sistema deve se comportar da perspectiva do usuário antes de qualquer código ser escrito. A sintaxe padronizada é o Gherkin: um template declarativo Scenario / Given / When / Then que força o LLM a pensar em State → Action → Outcome — eliminando completamente o "vibe coding" e mantendo o agente em trilha estrita.

Feature: Retry de pagamento

  Scenario: Cartão recusado, nova tentativa automática
    Given um pedido "#8842" com pagamento "recusado"
    And o cliente tem 2 tentativas restantes
    When o webhook "payment.retried" é recebido
    Then o sistema agenda nova tentativa em 30 minutos
    And o cliente recebe notificação por email

Specs executáveis vencem prosa: cada cenário vira um teste verificável, e o agente segue uma trilha estrita em vez de interpretar parágrafos ambíguos.

⚛️ A física dos tokens

LLMs não interpretam estruturas de dados — processam texto tokenizado. Cada caractere enviado é decomposto em tokens; cada token consome budget, tempo e capacidade de contexto. Escrever specs production-grade é tratar a tokenização como restrição física rígida: cada newline e espaço de indentação se traduz diretamente em budget de desenvolvimento e latência. Mesmo plataformas generosas como o Antigravity estão limitadas pela física dos tokens dos modelos subjacentes — cada espaço desnecessário num YAML aninhado e cada Given/When/Then repetitivo consome ciclos e attention-heads em loops de raciocínio multi-turno. Trate /specs não como documentação, mas como conjunto de instruções compilado e enxuto: Markdown legível por humanos + blocos YAML planos e altamente direcionados.

Para praticar SDD, entenda como as ferramentas de coding consomem instruções: elas não são escritas num único lugar. Jogar um documento massivo de design de 100 páginas direto na janela de chat esgota o budget de contexto de curto prazo, aumenta a latência e fragmenta o contexto. As instruções vivem em três camadas:

Não existe uma única forma de transformar spec em código — cada trabalho pede um execution mode diferente. Clique nos personagens para ver o playbook de cada um:

O Model Context Protocol (criado pela Anthropic, hoje padrão aberto) é apelidado de "the USB-C for AI tools" — um exagero, mas a analogia captura a ideia: construa um servidor MCP para seu banco de dados, API ou sistema de arquivos, e qualquer agente compatível pode usá-lo sem escrever integração customizada.

from mcp.server import Server
from mcp.server.stdio import stdio_server
import sqlite3

server = Server("knowledge-base")
conn = sqlite3.connect("knowledge.db")

@server.list_tools()
async def list_tools():
    return [
        {"name": "query_knowledge",
         "description": "Query the knowledge base with SQL",
         "inputSchema": {"sql": "SQL query to execute (SELECT only)"}},
        {"name": "add_knowledge",
         "description": "Add a new knowledge entry",
         "inputSchema": {"title": ..., "content": ..., "tags": "Comma-separated tags"}},
    ]

@server.call_tool()
async def call_tool(name, arguments):
    if name == "query_knowledge":
        sql = arguments["sql"]
        if not sql.strip().upper().startswith("SELECT"):
            return "Error: Only SELECT queries allowed"
        rows = conn.execute(sql).fetchall()
        return [dict(zip(cols, r)) for r in rows]   # → TextContent
    if name == "add_knowledge":
        conn.execute("INSERT INTO knowledge (title, content, tags) VALUES (?, ?, ?)", ...)
        conn.commit(); return "Knowledge entry added."

async def main():
    async with stdio_server() as (r, w):
        await server.run(r, w, server.create_initialization_options())

Trabalhar com coding agents modernos exige mudança de mentalidade e de cultura. Sem ela, o cenário clássico: PRs ficam enormes, conflitos de merge se multiplicam (devs chegando nos mesmos arquivos) e a cadeia de dependências fica impossível de desembaraçar — PR #1 não mergeia sem o PR #2, que precisa do PR #3, bloqueado por um reviewer em outro fuso horário. Algumas mudanças aprovadas enquanto as relacionadas esperam → ainda mais conflitos. De repente: branch quebrado.

Estratégias para high-velocity integration

Act as a Senior Software Engineer and Security Researcher. Review the provided code for this Github PR or Diff using these strict criteria: Use the command line to fetch the Github PR: `gh pr view <PR NUMBER>` First analyze the code, then code review: 1. **Critical Vulnerabilities:** Check for hardcoded secrets (API keys), SQL injection, XSS, or broken authentication. 2. **Logic & Efficiency:** Identify "off-by-one" errors, infinite loops, or redundant API calls. 3. **Readability:** Suggest better naming conventions or breaking down "megafunctions" into smaller pieces. 4. **Edge Cases:** What happens if the input is null? What if the network fails? Output Format: - **Description:** - What is this PR doing? Explain in details. ISSUES: -⚠ **Critical:** (Stop-ship issues) -⚠️ **Warnings:** (Code smells or style issues) -✅ **Best Practices:** (Specific lines to refactor for better performance) -💡 **Quick Win:** (One sentence summary of the biggest improvement) When there are no issues return - **Description:** - What is this PR doing? Explain in details. LGTM

Você pode escrever um ótimo prompt de review — mas a skill só roda quando invocada de dentro da IDE. O próximo passo é o revisor contínuo: serviços que observam o repositório, reagem a eventos (PR aberto, cron noturno) e postam descobertas sem ninguém pedir. Pegam o que revisores cansados perdem numa sexta à tarde: dependência com CVE novo, TODO de 6 meses que virou brecha silenciosa. Quando o time envia PRs gerados por IA em volume, o revisor contínuo é a única coisa que escala com o output. A questão é quão custom você precisa ir — a resposta é um espectro de 3 tiers:

As 3 perguntas que dizem qual tier você precisa

Em codebases legacy de cem milhões de linhas, carregar código como texto plano na context window fica sem espaço, e RAG padrão remove a estrutura que torna o código legível (classe pertence a arquivo, chamada de função remete a um doc de requisitos escrito há uma década). Achatar tudo em vector store = o mapa desaparece. O padrão que emergiu nas maiores modernizações: construir o agente sobre um knowledge graph — ingerir código, docs, tickets e PDFs de design em um graph database (ex.: Spanner Graph) e combinar 3 modos de retrieval:

Resumo do espectro: Managed = revisor genérico em minutos · Hybrid = SEU revisor em um dia · Custom = revisor que entende o sistema INTEIRO — ao custo de ser dono do runtime e da evaluation.

Um fenômeno novo: diante de um fluxo constante de micro-aprovações (melhorar uma única linha, ajustar uma tool call), devs começam a clicar "Approve" reflexivamente. É uma forma de exaustão de baixo grau em que o time para de verificar o trabalho da máquina só para acompanhar o ritmo — e perde atenção aos detalhes. A supervisão constante não escala; os limites estruturados, sim.

Durante uma atualização de rotina, o autor descobriu o poder — e os limites — do browser built-in do Antigravity: o recurso deixa o agente interagir com aplicações em desenvolvimento sem credenciais de login (inestimável para testes de UX). Mas em modo YOLO (auto approve), o agente pode agir mais rápido do que um humano consegue pensar. Um prompt simples para criar um botão disparou a seguinte cadeia:

O incidente destacou o risco de context hallucination: quando a IA não tem dados suficientes, ela preenche lacunas usando quaisquer strings que existam no contexto — incluindo informação sensível como endereços de email hardcoded ou URLs. Pode parecer menor se for "só um email". Mas considere o que o agente estava fazendo: cumprindo sua diretiva com os dados disponíveis, sem qualquer verificação se deveria. Esse é o risco central de sistemas autônomos.

Conforme os limites da Agentic AI se expandem, surge um paradoxo: agentes devem ser autônomos o suficiente para resolver problemas complexos, mas não dá para arcar com o risco de ficarem "rogue" em ambiente enterprise. Imagine um agente encarregado de "resolver disputas de clientes": para ser eficaz, precisa de acesso a dados de clientes, ferramentas de email e sistemas internos — mas o desafio é garantir que não envie email acidentalmente para o banco de dados inteiro ou compartilhe código proprietário.

Além de sanitizar strings, segurança de verdade requer um ambiente de execução restrito para conter as ações do agente. Mesmo com filtragem rigorosa de output, o LLM pode gerar código sintaticamente válido mas logicamente malicioso. Executar tarefas em containers efêmeros e de baixo privilégio — isolados da rede principal e de sistemas de arquivos sensíveis — cria um "blast radius" que protege a infraestrutura central: se o agente é enganado para executar um comando destrutivo, o dano fica confinado a uma instância descartável, limpa e resetada sem consequências.

comando destrutivo → erro de permissão rígido no nível do kernel → host completamente intocado

Embora automação seja o objetivo, operações de alto risco exigem protocolo Human-in-the-Loop (HITL) como fail-safe final: checkpoint gates para ações que atendem a um perfil de risco específico. Apresentar a intenção sanitizada do agente a um supervisor humano para sign-off manual balanceia a velocidade da IA com o julgamento nuançado do dev — e garante que a responsabilidade final pela integridade arquitetural permaneça em mãos humanas.

O surto de testes gerados por IA

O surto de código gerado por IA empurra o processo de testes manuais para cobertura de testes gerada por IA — e aqui a IA tem vantagem estrutural: como implementação não é mais o gargalo, ela pode escrever cobertura de testes mais abrangente que qualquer humano no mesmo tempo, de forma programática e poderosa. Em ambiente high-velocity, test-driven development vira realidade: a máquina escreve os próprios testes que validam seu output.

O processo força o agente a produzir um teste unitário que falha ou um comando de reprodução (como um request curl) antes de tentar qualquer correção. Embutir esses testes no codebase significa que toda iteração rápida é respaldada por uma suite verificável — bugs não voltam, e revisores humanos podem confiar no "sinal verde" automatizado para integração.

Por que checagem de qualidade especial para sistemas dirigidos por ML? Porque testes de software tradicionais são insuficientes para sistemas cujo output é gerado em vez de computado. Um agente (ou qualquer componente dirigido por ML — classificador, sumarizador, retriever) pode passar em 100 testes unitários de suas ferramentas e ainda falhar espetacularmente escolhendo a ferramenta errada, parafraseando uma resposta crítica ou alucinando um fato. A margem de erro não é defeito a eliminar — é propriedade inerente do modelo, e a estratégia de testes deve acomodá-la.

O exemplo central de guardrail do paper é o Hybrid Policy Server: um middleware que intercepta ações antes de atingirem sistemas externos, operando em duas camadas complementares.

environments:
  localhost:
    blocked_tools:
      - send_email
roles:
  viewer:
    allowed_tools:
      - list_files
      - read_file

def is_tool_allowed(self, tool_name):
    # 1) Environment blocks
    if tool_name in env_blocked: return False
    # 2) Role permissions
    return "*" in role_allows or \
           tool_name in role_allows

def check_action_semantic(self, action_description):
    client = Client(vertexai=True)
    prompt = "Evaluate if this action violates " \
             f"PII policies: {action_description}"
    response = client.ai.models.generate_content(
        model="gemini-3.1-pro", contents=prompt)
    return not response.text.startswith("VIOLATION")

Um perigo significativo do desenvolvimento autônomo é a Context Hallucination: sem dados específicos, o agente preenche lacunas com quaisquer strings disponíveis no contexto — potencialmente vazando endereços de email hardcoded ou URLs privadas. A mitigação é Context Hygiene rigorosa via middleware: PII masking e placeholder injection, para que o agente opere sempre com dados esterilizados. E todos os outputs do agente devem ser sanitizados contra prompt injection e interações de UI rogue — o "vibe" da máquina nunca pode virar vulnerabilidade arquitetural.

def resolve_context(template_str, override_state):
    def replacement(match):
        var_name = match.group(1)
        # 1) Prioriza overrides de runtime state
        if var_name in state_to_check \
           and state_to_check[var_name] is not None:
            return state_to_check[var_name]
        # 2) Fallback para env vars validadas
        if var_name in os.environ:
            return os.environ[var_name]
        # 3) Deixa não resolvido — sem falhas silenciosas
        return match.group(0)
    return re.sub(r'\[\[([^\]]+)\]\]',
                   replacement, template_str)
# ex.: resolve [[COMMENTER_EMAIL]] dinamicamente

def validate_tool_call(tool_call):
    args = tool_call.function_call.args
    resolved_args = {}
    for k, v in args.items():
        if isinstance(v, str):
            resolved_args[k] = resolve_context(
                v, override_state)
        elif isinstance(v, list):
            resolved_args[k] = [
                resolve_context(i, override_state)
                if isinstance(i, str) else i
                for i in v]
        else:
            resolved_args[k] = v
    args.clear(); args.update(resolved_args)
# intercepta TODA tool call ANTES de rodar

Com o middleware conectado diretamente ao pipeline de execução, qualquer tentativa do agente de executar uma ação — enviar email, consultar uma apresentação na nuvem — é interceptada. O engine traduz placeholders como [[COMMENTER_EMAIL]] ou [[DEFAULT_PRESENTATION_ID]] em assets de teste autorizados, de forma segura e silenciosa — eliminando PII hardcoded de test suites e system prompts.

Em menos de um ano, os ciclos de desenvolvimento ficaram dramaticamente mais rápidos. Mas a velocidade revelou a mudança importante: a IA eliminou o gargalo de produção de código e moveu a restrição downstream — para os humanos que devem revisar, testar e integrar esse output. Isso é carga cognitiva compartilhada: humanos agem como arquitetos (Test Specs, Integration Specs, blueprints de MLOps/DevOps), enquanto a IA cuida do trabalho pesado (código de teste real, integrações, detalhes operacionais granulares).

O sucesso depende de evoluir dinâmicas de time, refinar a colaboração com agentes e definir limites estritos para ferramentas que nunca dormem. O desafio mudou de mera produção de código para orquestrar sistemas que verificam, integram e entregam trabalho.

🚀 Os padrões viram comandos que você roda hoje

# geração de projeto spec-driven
agents-cli scaffold

# gate de cobertura de testes gerada por IA
agents-cli eval run

# deployment com sandbox para Cloud Run ou Vertex AI Agent Engine
agents-cli deploy