For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/web/agents.md (or send Accept: text/markdown).

Desenvolva com um agente de codificação

Entregue tarefas a um agente de codificação: os arquivos que ele lê, a biblioteca de prompts prontos para colar, a configuração sem supervisão e a revisão que mantém você no controle.

Perguntar sobre este guia

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.

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.

Arquivo	O que ele fornece ao agente
`llms.txt`	O mapa de entrada do repositório — cada documento que vale a pena ler mais os protocolos de segurança, na ordem de leitura
`AGENTS.md`	Os limites não negociáveis: trabalho apenas local até você aprovar mais, escopo por workspaceId, segredos só no servidor
`.ai/PROJECT_CONTEXT.md`	Memória entre sessões — o que mudou recentemente e por quê; leia antes de alterar código
documentos espelho `.ai/`	Uma nota .ai/<caminho>.md correspondente ao lado de arquivos importantes, registrando decisões por arquivo e tópicos em aberto
`docs/agent-setup.md`	O runbook autônomo — fases de instalação, migração e implantação com um ponto de verificação após cada uma
`prompts/`	Prompts de tarefa prontos para colar para os trabalhos que os proprietários mais pedem
`docs/agent-security.md`	A checklist de aceitação — autenticação, verificações de workspace e RLS, logs com dados ocultados, evidências de implantação
`.env.example`	O inventário completo do ambiente — o agente nunca inventa um nome de variável ausente deste arquivo

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/packages/web-core/src/reports.md explica as decisões por trás de packages/web-core/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.