Além do vibe coding para a Web

1. Introdução

À medida que os agentes de programação se tornam parte integrante do desenvolvimento diário de software, seja você um engenheiro experiente ou um novo desenvolvedor querendo lançar seu primeiro app, a forma como você cria e o que você cria está mudando fundamentalmente. Ao começar a usar agentes de programação, você geralmente começa com comandos "zero-shot", ou seja, uma única instrução que diz em linguagem humana e de forma concisa o que você quer. Isso rapidamente causa problemas:

• Tendência a agradar as pessoas: os modelos geralmente aceitam restrições ou premissas falhas, buscando concluir seu pedido o mais rápido possível, e não verificam se o que estão criando realmente faz o que você pretendia.
• Lacuna de verificação: os agentes, mesmo quando escrevem testes, normalmente não verificam o trabalho para garantir que ele funcione. Ao tentar usar sites em um navegador ativo, surgem bugs ocultos, layouts quebrados e controles inacessíveis.
• Dívida técnica: devido à forma como os modelos são treinados e funcionam, o código que eles escrevem tende a padrões antigos e desatualizados, aumentando a dívida técnica, que custa mais tokens e mais tempo e esforço humano e de máquina para gerenciar. Ela pode até afetar negativamente a experiência do usuário.

O plano de jogo em quatro etapas

Para ajudar a orientar os agentes de programação a produzir um código melhor e mais alinhado aos seus requisitos, siga um ciclo de vida de desenvolvimento de produtos em quatro etapas:

1. Planejar e criar: escreva em colaboração Documentos de requisitos do produto (PRDs, na sigla em inglês) com o agente e peça para ele criar protótipos e designs dos PRDs no navegador antes de iniciar a implementação da produção. Depois, crie documentos de design arquitetônico (especificações) com base nos PRDs e designs antes de começar a programação.
2. Codifique e crie: instrua seus agentes a criar de acordo com seus PRDs, designs e especificações em vez de um comando de zero shot e faça com que ele execute outro agente para verificar o trabalho.
3. Enxaguar e repetir: siga as etapas 1 e 2 novamente para cada novo recurso que você quiser adicionar.
4. Implantar: enviar para produção.

Este documento mostra como usar agentes de IA como parceiros colaborativos ativos com práticas que ajudam a reduzir a dívida técnica e melhorar a qualidade do código de saída. Você usa o Antigravity com o Modern Web Guidance e o DevTools para agentes para criar um jogo de palavras casual e aprimorá-lo com recursos de IA. Em seguida, implante no Google Cloud usando o Firebase para compartilhar com amigos e familiares.

O que você vai aprender

• Como tratar tarefas de programação com IA como miniciclos de vida de desenvolvimento de produtos.
• Por que você deve separar os requisitos de produtos das especificações de arquitetura.
• Como orquestrar fluxos de trabalho multiagente para criar protótipos diretamente no navegador e revisar seu código.
• Como aproveitar habilidades e ferramentas de terceiros para melhorar o desenvolvimento e a experiência do usuário.
• Como implantar aplicativos da Web diretamente na produção usando o MCP do Firebase.

Pré-requisitos

• Uma Conta do Google pessoal e um projeto do Google Cloud ou Projeto do Firebase (instruções em configuração do projeto)
• Conhecimento de HTML, CSS e JavaScript.
• Um navegador da Web, como o Chrome.
• Node.js instalado (LTS recomendado).

2. Configurar o projeto

Conta do Google

Se você ainda não tiver uma Conta do Google pessoal, crie uma.

fazer login no console do Google Cloud

Faça login no console do Google Cloud usando uma Conta do Google pessoal.

Ativar faturamento

Dica:se você configurou o faturamento usando créditos do Google Cloud, pule para "Criar um projeto do Firebase".

Para configurar uma conta de faturamento pessoal, acesse "Ativar faturamento" no console do Cloud.

Criar um projeto do Firebase

Dica:se você configurou um projeto na nuvem do Google Cloud como parte da configuração dos créditos do Google Cloud, use esse projeto para configurar seu Projeto do Firebase. Se você fizer isso, não será necessário conectar sua conta de faturamento porque ela já está conectada.

1. Navegue até o Console do Firebase e faça login com sua Conta do Google pessoal.
2. Clique em Adicionar projeto ou Criar um projeto.
3. No assistente de criação de projetos:
   • Insira um nome de projeto (por exemplo, wordup-web-app) ou reutilize o projeto do Google Cloud configurado durante a configuração do projeto.
4. Conectar conta de faturamento
   • Na barra lateral do console do Firebase, localize o selo do plano na parte de baixo (ele diz "Spark"). Clique em Fazer upgrade.
   • Selecione o plano Pague conforme o uso.
   • Selecione a Conta de faturamento que você configurou na etapa Configuração do projeto.
   • Confirme a seleção para anexar a conta de faturamento ao projeto. O Firebase Hosting oferece um nível sem custo financeiro generoso. Normalmente, concluir este tutorial não gera custos financeiros.

Instalar ferramentas

• Antigravity 2.0: a principal estrutura de programação agêntica com que você trabalha, combinada com o modelo Gemini Flash mais recente para programação rápida e de ponta.
• Modern Web Guidance: Habilidade para agentes de programação que ajuda a escrever CSS, HTML e JavaScript modernos. Instale em Antigravity Configurações > Personalização > Criar com plug-ins do Google > Modern Web Guidance.
• DevTools para agentes: permite que os agentes controlem o Chrome, inspecionem o DOM ativo, testem o layout e depurem em tempo de execução. Instale em Antigravity Configurações > Personalização > Criar com plug-ins do Google > Chrome DevTools e Antigravity Configurações > Personalização > Adicionar servidores MCP > Chrome DevTools para agentes.
• Servidor MCP do Firebase: para configuração de projetos e implantações com um único comando. Instale pelo Antigravity Configurações > Personalização > Criar com plug-ins do Google > Configurações do Firebase e do Antigravity > Personalização > Adicionar servidores MCP > Firebase.

3. Começar com um plano

A tentação comum na programação com agentes é enviar um comando zero-shot ("Crie um jogo de palavras para mim") e torcer pelo melhor. Isso quase sempre resulta em casos extremos ignorados, bases de código inchadas e ciclos intermináveis de correção de bugs.

Em vez disso, trate cada tarefa como um miniciclo de vida de desenvolvimento de produto. Os agentes de programação têm ferramentas de pesquisa e raciocínio que permitem que eles atuem como um parceiro colaborativo para ajudar você a esclarecer suas ideias antes de escrever qualquer código. Falar sobre sua ideia geralmente ajuda a encontrar e responder a perguntas antes que elas se tornem problemas. Na engenharia de software, isso é chamado de depuração do patinho de borracha. Você pode usar seus agentes de programação como patos de borracha para planejar projetos e recursos.

Você está criando um jogo de palavras casual. Peça ao agente para ajudar você a criar o jogo que quer.

I want to make a casual word guessing game. Go do deep research on those kinds
of games, then ask me questions to help me write a PRD for the game's features.

Este é o formato básico do comando. Remixe-o para suas próprias necessidades. O importante é que ele faça uma pesquisa detalhada e faça perguntas com base nela para ajudar você a planejar seu trabalho.

Comece com esse comando porque trabalhar com agentes de programação envolve muita revisão. Dividir um plano de implementação completo em partes menores e focadas facilita muito a revisão, permite detectar casos extremos com antecedência, traz conhecimento fora dos dados de treinamento do agente e, mais importante, permite fazer mais pausas entre as revisões.

• Separa "o quê" de "como": definir a experiência do usuário e o escopo do produto em um documento formal de requisitos do produto (PRD, na sigla em inglês) separa o que você quer que aconteça de como isso é implementado. Assim, você pode se concentrar em um aspecto do desenvolvimento do produto por vez, em vez de tudo de uma vez.
• Identifica casos extremos com antecedência: uma sessão interativa de perguntas e respostas obriga você a esclarecer seus requisitos antes de iniciar o design ou a implementação.
• Pesquisa ativa do agente: como o treinamento do agente é interrompido em uma determinada data e as informações nele ficam altamente resumidas, a pesquisa em tempo real pode trazer novas informações que seriam perdidas.

Dica:se você gostar ou não gostar de algo que o agente de programação fez, adicione instruções a um arquivo AGENTS.md na pasta do projeto para corrigir ou reforçar o comportamento dele. Adicione o seguinte para garantir que o Antigravity use a ferramenta de perguntas integrada ao fazer perguntas para você:

When I ask you to ask me questions, you are **REQUIRED** to use your `ask_question` tool to do so.

Exercício 1

Agora é sua vez. Configure seu projeto e crie o PRD.

1. Adicione uma instrução ao arquivo AGENTS.md para salvar a saída em docs/plans/{{YYYY-MM-DD}}-{{description}}.md.
2. Execute o comando de pesquisa anterior com as alterações que quiser para criar o PRD.
3. [Meta ambiciosa] Atualize o arquivo AGENTS.md com coisas que você não gosta que o agente faça e execute o comando novamente.

Dica:o Antigravity 2.0 tem um comando /grill-me que pode ser executado especificamente para fazer esse tipo de análise.

Prática recomendada:o Antigravity 2.0 tem uma ferramenta "Artefato" que permite comentar linha por linha ou destacar um texto específico e deixar comentários, assim como no Google Docs. Deixe comentários inline em vez de adicioná-los ao comando. Salve o comando para comentários em todo o documento. Ao enviar seu comando, mesmo que ele esteja vazio, você envia seus comentários e pede para o Antigravity regenerar o documento com eles.

Atenção:às vezes, mesmo quando você pede para ele escrever apenas um PRD, ele inclui design e arquitetura de software no documento. Se isso acontecer, deixe um comentário ou peça para ele remover esses itens e se concentrar apenas na experiência do usuário.

4. Design no navegador

O design estático da interface depende de simulações que geralmente são impressionantes, mas podem não considerar casos extremos, restrições e interações reais do usuário. Assim como no código, pedir a um agente para "criar" o aplicativo do site resulta em designs que convergem para um design genérico (geralmente roxo).

Para apps da Web, use a capacidade do seu agente de controlar um navegador da Web com as DevTools para agentes e crie no navegador. Seja você um designer trabalhando para trazer mais fidelidade aos seus designs, um programador ou desenvolvedor buscando melhorar a interface e a experiência do usuário do seu projeto ou os dois trabalhando juntos, trabalhar no meio real para o qual você está criando produz resultados melhores.

Projetar no navegador também oferece a oportunidade de coordenar vários agentes trabalhando juntos para produzir uma única saída. Esses subagentes têm personas e metas específicas que podem ser coordenadas para produzir resultados melhores do que um único agente trabalhando sozinho. Com o design, você pode pedir que um agente de design visual, um agente de experiência do usuário e um agente de acessibilidade trabalhem juntos para ajudar você com seu design e mostrar tudo diretamente no navegador.

Atenção:usar subagentes para concluir tarefas usa mais tokens. Embora eles possam produzir resultados de qualidade muito maior, o uso deles pode ter custos adicionais.

Comece um painel de agentes de design para ajudar você a escolher um design com base no seu PRD.

Using the PRD, start a panel of expert agents: one UX design, one web
accessibility, and one for visual design, and have them work together to design
3 different UI mockups and show them to me in-browser.

Dica:digite @ na área de comando do Antigravity e comece a digitar o nome de um arquivo para que o Antigravity analise esse arquivo específico.

Projetar no meio em que você está criando, neste caso, a Web, em vez de um meio estático, permite detectar casos extremos e restrições difíceis de gerenciar de outra forma, além de receber feedback visual imediato que é fiel à produção.

Exercício 2

Agora é sua vez. Projete seu projeto.

1. Execute o comando de design anterior com as modificações que quiser para criar seu design. Inclua ideias para as diferentes direções de design que você gostaria de ver (como moderno, divertido, realista etc.).
2. Escolha um design que você goste e faça iterações com seu agente.
3. Peça ao seu agente para atualizar o PRD e apontar para o design acordado.
4. Meta ambiciosa: execute testes de acessibilidade e design responsivo para o design escolhido e faça ajustes com base nessas auditorias.

Atenção:às vezes, os agentes ficam muito entusiasmados e entendem essa orientação como uma aprovação para criar o aplicativo inteiro. Observe o raciocínio dele e, se você perceber que ele está fazendo mais do que o esperado, interrompa e peça para mudar de curso.

5. Escrever uma especificação

Com um PRD aprovado (o que construir) e um design visual selecionado (como ele vai ser), agora você precisa de alinhamento técnico na arquitetura (como construir).

Um documento de design técnico ou uma especificação (spec, para abreviar) detalha estruturas de arquivos, gerenciamento de estado, interfaces de componentes, pipelines de eventos e dependências. Criar uma especificação antes de escrever o código permite detectar desalinhamentos e padrões de programação indesejáveis no início, antes que eles se transformem em um código mais difícil de entender e refatorar.

Write a detailed technical design document on how to implement the game with
the chosen design.

Por que você está fazendo isso

• Clareza arquitetônica: definir a hierarquia de componentes e o fluxo de transição de estado (por exemplo, Idle → InGame → EvaluatingGuess → GameOver) evita condições de disputa e código spaghetti frágil.
• Alinhamento com padrões modernos: com o Modern Web Guidance ativado, o agente faz referência a padrões modernos (por exemplo, consultas CSS @container, elementos
  integrados para modais ou sobreposições de ajuda e módulos ES modulares) em vez de extrair bibliotecas legadas pesadas.
• Avaliações em etapas: separar a avaliação funcional do PRD da avaliação do documento de design técnico permite avaliar a arquitetura de forma independente da experiência do usuário.

Exercício 3

1. Instrua o AGENTS.md a salvar a saída na pasta atual:

   PRDs should _always_ be written to the current project's root in `docs/plans/{{YYYY-MM-DD}}-{{description}}.md` format
   

2. Execute o comando do documento de design e revise-o, garantindo que ele cubra aspectos como estrutura de diretório, tratamento de eventos e armazenamento.
3. Meta ambiciosa: inclua diagramas do Mermaid para explicar o fluxo de estado no aplicativo, se ainda não estiverem incluídos.

6. Por fim, crie o app

Com o PRD, o mockup da interface e o documento de design estabelecidos, é hora de criar. Esses três itens são a orientação clara e inequívoca de que os agentes precisam para o que devem criar.

Esta é outra boa oportunidade para usar subagentes. É possível executá-los depois que o código é criado para analisar o quanto o que foi criado se manteve fiel aos seus designs iniciais, e outro para verificar a qualidade do código do que foi criado.

Use the PRD, design doc, and mockup to implement the site, then send out 2
agents, one to check how closely you followed the requirements, and one to
review the code.

Por que você está fazendo isso

O desenvolvimento orientado por especificações com revisores de primeira passagem oferece ao seu agente requisitos claros e pré-testados para criar, além de um novo conjunto de olhos para garantir que ele seguiu o plano antes de chegar até você, melhorando a qualidade e a fidelidade.

• Requisitos verificados: o agente não precisa adivinhar o que você quer. Você já revisou tudo, exceto a implementação, antes de escrever qualquer código.
• Um novo olhar: um agente de revisão gerado em um novo contexto não tem viés de confirmação ao criar a base de código, o que o torna eficaz para detectar casos extremos não tratados, requisitos de implementação ausentes e outros detalhes de código ou produto que foram perdidos.

Exercício 4

1. Execute o comando de build, apontando para os arquivos exatos que você quer que ele revise.
2. Assista a saída enquanto ela é executada. Você vai ver o modelo raciocinar sobre seus requisitos enquanto tenta criar o código. Se algo parecer que está saindo do controle, você pode parar e corrigir.
3. Faça com que ele execute o servidor de desenvolvimento para conferir o site final e verificar o trabalho.
4. Meta ambiciosa: repita esse processo para adicionar testes automatizados.
5. Meta ambiciosa: escolha uma estrutura ou um conjunto de tecnologias específico para a criação do site. Com o PRD, o modelo e o documento de design separados, é fácil adaptar a diferentes opções.

7. Implantar para a produção

Você planejou, projetou e codificou. O que falta? Implantação em produção.

Deploy this site to my Firebase project [YOUR_PROJECT_ID] using Firebase
Hosting.

Atenção:se isso não funcionar, verifique se você tem o MCP do Firebase instalado. Talvez seja necessário fazer login na primeira vez que você executar esse comando.

Exercício 5

1. Execute o comando de implantação substituindo o ID do projeto.
2. Copie o URL de hospedagem ao vivo fornecido pelo agente.
3. Abra o URL ativo para verificar se ele está implantado e funcionando.
4. Meta ambiciosa: use o DevTools para agentes e execute uma auditoria do Lighthouse no seu site de produção, faça ajustes para melhorar a pontuação do Lighthouse e publique as atualizações.

8. [Opcional] Melhorias de IA

Seu jogo de palavras agora está totalmente funcional usando um dicionário estático. Para mudar o dicionário estático para uma palavra dinâmica, peça uma a cada vez usando um modelo de linguagem pequeno e local da API Prompt.

Atenção:se você ainda não fez isso, instale o Modern Web Guidance para ajudar.

Como esse recurso não está disponível em todos os dispositivos, use o aprimoramento progressivo para verificar se a API e o modelo estão disponíveis. Se estiverem, use-os. Caso contrário, volte para sua lista estática.

Exercício 6

Coloque em prática tudo o que você aprendeu.

1. Trabalhe com seu agente para escrever um PRD e usar a API Prompt para gerar uma palavra oculta válida.
2. Projete a barra de progresso do download e a interface de integração da IA no navegador.
3. Escreva uma especificação para a implementação. Dica: execute um agente para garantir que a sintaxe da API correta seja usada aqui.
4. Desenvolva seu novo recurso.
5. Implante-o em produção.

9. Conclusão

Parabéns! Você criou, refinou, melhorou e implantou um aplicativo da Web moderno, acessível e com foco em IA usando as práticas recomendadas de programação com agentes.

O que você aprendeu

• Fluxos de trabalho de agentes orientados a produtos: como tratar tarefas como miniciclos de vida de produtos (PRD → Design → Especificação → Criação) reduz a dívida, a sobrecarga de revisão e o atrito de idas e vindas.
• Painéis de especialistas com vários agentes: como executar vários subagentes de IA pode ajudar a melhorar a qualidade e a fidelidade do seu trabalho.
• PRD x documento de design: por que separar o escopo funcional (plano) da arquitetura técnica (especificação) é um processo mais escalonável e preciso do que o zero-shot feature prompting.
• Implantação perfeita: como usar servidores MCP (como o MCP do Firebase) para simplificar o acesso a sistemas de terceiros, como a implantação do seu site.