Desenvolva com um agente de codificação

Passo a passo para iniciantes

Pré-requisitos: leia os dois guias para iniciantes abaixo, conclua a Configuração local da Web e abra este repositório na pasta raiz no seu editor. Um agente de codificação é uma ferramenta de IA — Cursor, Claude Code, Devin ou um assistente semelhante — que lê o seu projeto, edita arquivos e executa comandos. Tudo nesta página se aplica a qualquer um deles.

Termos rápidos: um prompt é o texto de instrução que você cola no agente. Um diff é a lista de alterações de arquivos que ele propõe. A raiz do repositório é a pasta de nível superior que contém o package.json — o agente deve sempre começar por ela.

1. Abra a pasta prompts/ na raiz do repositório e copie o prompt mais próximo da sua tarefa. new-landing-page.md é uma boa primeira tentativa.

2. Cole-o no seu agente e preencha os <placeholders>: a rota que você quer, o que a página ou a tela deve fazer, quem pode usá-la e como é o sucesso. Depois adicione uma linha: Leia llms.txt, depois AGENTS.md, depois .ai/PROJECT_CONTEXT.md antes de tocar no código.

3. Deixe o agente listar os arquivos que vai alterar e as verificações que vai executar antes de editar. Quando ele terminar, revise o diff — você está aprovando alterações reais no seu produto.

4. Publicar, implantar e chamar provedores pagos nunca faz parte de um prompt de tarefa. Mantenha essas ações como etapas separadas que você aprova explicitamente.

• Antes de começar
• Noções básicas de terminal
• Configuração local da Web

Os arquivos que o seu agente lê

O repositório traz uma pequena pilha de arquivos escritos para agentes, não apenas para humanos. Você nunca cola esse contexto manualmente — aponte o agente para o llms.txt e ele lê o resto sozinho.

A ordem de leitura importa: llms.txt é o mapa, AGENTS.md define os limites e .ai/PROJECT_CONTEXT.md carrega o que as sessões anteriores aprenderam. Um agente que pula os limites produz código que você não pode publicar.

A biblioteca de prompts

prompts/README.md é o índice. Cada arquivo é um briefing completo: cole-o, preencha os <placeholders> e as regras do kit — tokens de design em vez de cores fixas, blocos do kit em vez de padrões inventados — viajam junto com ele.

Para o caminho do zero até o app rodando, cole prompts/agent-setup.md — ele aciona a configuração sem supervisão descrita a seguir.

• Deixe o agente executar a configuração por você

• agent-setup.md — levante o kit e implante-o com um agente
• pick-a-style.md — aplique um estilo de design em todo o produto
• new-landing-page.md — monte uma página de marketing a partir de blocos do kit
• new-app-screen.md — adicione uma tela dentro do shell do app do espaço de trabalho
• restyle-product.md — reaplique o tema de uma página existente com os tokens do kit
• ui-audit.md — execute a auditoria visual e de acessibilidade em uma rota

Deixe o agente instalar e implantar

O kit consegue, em grande parte, configurar a si mesmo. Colar prompts/agent-setup.md faz o agente executar docs/agent-setup.md — o runbook entregue — fase por fase: verificações preliminares, arquivos de ambiente, instalação, inicialização do banco de dados, migrações, inicialização do app e, opcionalmente, uma implantação em VPS. Após cada fase, ele executa o ponto de verificação daquela fase e relata a saída real, não uma afirmação.

Dois auxiliares mantêm isso seguro. scripts/setup-env.mjs cria os arquivos de ambiente a partir de .env.example: cria apenas arquivos ausentes, gera apenas segredos ausentes ou de placeholder, e o modo --check valida sem escrever. docker-compose.dev.yml é um ambiente de desenvolvimento totalmente em contêineres — Postgres mais um contêiner de desenvolvimento Node 22 — então o agente não precisa de Node.js instalado no seu computador.

O repositório que você recebeu importa aqui. O repositório Web e o monorepo Todas as Plataformas trazem o runbook, os arquivos compose, scripts/setup-env.mjs e prompts/. Os repositórios Mobile e Desktop independentes trazem um llms.txt com escopo próprio, AGENTS.md, os documentos espelho .ai/ e documentos selecionados, incluindo docs/agent-security.md — mas não o runbook de configuração nem os arquivos compose, porque o back-end com o qual esses apps falam vive no repositório Web.

• Siga a configuração guiada pelo agente

Como o agente lembra entre sessões

Os agentes não têm memória entre sessões — a pasta .ai/ é a memória. .ai/PROJECT_CONTEXT.md registra o que mudou recentemente e por quê. Ao lado dele, um documento espelho como .ai/apps/web/src/reports.md explica as decisões por trás de apps/web/src/reports.ts que o código sozinho não mostra.

O contrato é simples: leia o espelho de um arquivo antes de editá-lo e atualize o espelho quando a alteração entrar. As entradas de Open Threads registram trabalho inacabado para que a próxima sessão retome em vez de recomeçar. Um espelho desatualizado é pior do que nenhum — ao revisar o diff do agente, verifique se os espelhos dos arquivos alterados mudaram junto com ele.

A superfície para agentes do próprio app em execução

O seu produto implantado também responde a agentes — estes endpoints existem no app em execução, não apenas no repositório.

• GET /llms.txt — o app serve o seu próprio índice llmstxt.org: os guias, as páginas públicas e os endpoints públicos, com URLs absolutos.
• POST /api/mcp — um endpoint MCP sem estado que expõe as ferramentas do app. Aceita chaves de API sk_ apenas como bearer tokens — sessões de cookie do navegador nunca se aplicam. Crie chaves em Configurações → Desenvolvedores.
• GET /api/v1/openapi — a especificação OpenAPI da API REST pública, para geradores de cliente e ferramentas de agente.
• GET /api/health — a sonda de disponibilidade e dependências que balanceadores de carga e verificações de uptime chamam; ela informa os tipos de configuração dos provedores, nunca segredos.
• /status — uma página legível que informa a saúde de cada subsistema.

Revise o trabalho do agente com honestidade

Uma tarefa concluída é evidência, não um resumo. Antes de manter o trabalho do agente, verifique-o da mesma forma que docs/agent-security.md verifica uma implantação:

Quando algo está errado, devolva o diff — o agente corrige o próprio trabalho mais rápido quando você aponta a verificação que falhou. Para qualquer coisa que ele nunca deveria ter tentado sozinho, diga isso explicitamente uma vez; o limite vale para o resto da sessão.

• Portões de verificação e a suíte de testes

• Ele executou os testes que afirma — peça o comando e a saída dele, não uma conclusão.
• Os segredos ficaram apenas no servidor — nada novo carrega o prefixo NEXT_PUBLIC_ ou EXPO_PUBLIC_, e nenhuma chave foi impressa em um relatório ou commit.
• Cada leitura e escrita de dados do usuário permaneceu com escopo por workspaceId — nenhuma query confia em um id enviado pelo navegador.
• O espelho .ai/ de cada arquivo alterado mudou junto com o código.
• Publicar, implantar e chamar provedores pagos permaneceram etapas separadas que você aprovou — o agente nunca fez merge, push ou implantação por conta própria.
• Se uma etapa falhou duas vezes, ele parou e relatou o comando que falhou em vez de improvisar uma saída.