> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 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.

## 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](https://supastack.dev/pt/docs/web/before-you-start.md)

[Noções básicas de terminal](https://supastack.dev/pt/docs/web/terminal-basics.md)

[Configuração local da Web](https://supastack.dev/pt/docs/web/ship-in-5-minutes.md)


## 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ê](https://supastack.dev/pt/docs/web/agent-setup.md)

- `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](https://supastack.dev/pt/docs/web/agent-setup.md)


## 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](https://supastack.dev/pt/docs/web/testing.md)

- 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.


Para continuar a configuração, leia [Crie suas contas externas](https://supastack.dev/pt/docs/web/external-accounts.md).


## Seguinte

[Crie suas contas externas](https://supastack.dev/pt/docs/web/external-accounts.md)