> ## 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ê, os skills incluídos e a revisão que mantém você no controle.

## Passo a passo para iniciantes

Pré-requisitos: leia os dois guias para iniciantes abaixo e conclua a configuração local de Desktop. Um agente de codificação é uma ferramenta de IA — Cursor, Claude Code, Devin ou um assistente similar — que lê seu projeto, edita arquivos e executa comandos. Tudo nesta página se aplica a qualquer um que você use.

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 `.agents/skills/` na raiz do repositório e copie o skill mais próximo da sua tarefa — `add-a-desktop-capability` é uma boa primeira tentativa.

2. Cole-o no seu agente e descreva sua mudança, depois adicione uma linha: Leia `llms.txt`, depois `AGENTS.md`, depois `.ai/PROJECT_CONTEXT.md` antes de tocar em 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. Publicação, lançamento de instaladores e chamadas a provedores pagos nunca fazem parte de um prompt de tarefa. Mantenha-os como etapas separadas que você aprova explicitamente.

[Antes de começar](https://supastack.dev/pt/docs/desktop/before-you-start.md)

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

[Configuração local do desktop](https://supastack.dev/pt/docs/desktop/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, gerado para listar apenas o que este checkout realmente inclui |
| `AGENTS.md` | Os limites inegociáveis: apenas trabalho local até você aprovar mais, o shell nunca bifurca UI de produto |
| `.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 |
| `.agents/skills/` | Runbooks de tarefas escritos para agentes — os cinco skills Desktop listados abaixo |
| `docs/agent-security.md` | A checklist de aceitação — autenticação, verificações de workspace e permissões, logs redigidos |
| `docs/desktop-updates.md` | O runbook do canal de atualização — chaves de assinatura, endpoints e canais de release |
| `.env.example` | O inventário completo do ambiente — o agente nunca inventa um nome de variável ausente deste arquivo |


## Os skills incluídos

Cada arquivo sob `.agents/skills/` é um briefing completo: cole-o ou deixe o agente lê-lo, e as regras do kit viajam com ele — a UI do produto fica no aplicativo web, apenas comportamento de SO vai para o Rust.

A biblioteca `prompts/` pronta para colar só é incluída no repositório Web; este checkout traz skills em seu lugar. Para uma configuração autônoma, use o prompt pronto no guia de agent-setup.

[Deixe o agente executar a configuração](https://supastack.dev/pt/docs/desktop/agent-setup.md)

- `add-a-desktop-capability` — mudanças de janela, bandeja, atalho, atualização ou build
- `adding-a-dependency` — adicionar, atualizar ou mover uma dependência npm com segurança
- `reviewing-a-pr` — revisar um diff quanto a correção, isolamento de workspace e segredos
- `upgrading-from-upstream` — trazer uma versão mais nova do kit para o seu shell
- `verify-changes` — escolher e executar as verificações corretas antes da entrega


## Como o agente lembra entre sessões

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, um documento espelho como `.ai/apps/desktop/src-tauri/src/lib.md` explica as decisões por trás de `apps/desktop/src-tauri/src/lib.rs` 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.


## 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/desktop/testing.md)

- Ele executou as verificações que alega — cargo test, cargo check ou o preflight de release — peça o comando e sua saída, não uma conclusão.
- Os segredos ficaram apenas no servidor — nenhuma chave de assinatura ou certificado foi impresso num relatório ou commit, e o shell ainda não carrega credenciais de provedores.
- O comportamento do produto ficou no aplicativo web — o diff não adiciona UI, autenticação ou lógica de chat paralela em Rust.
- O espelho `.ai/` de cada arquivo alterado mudou junto com o código.
- Publicação, lançamento de instaladores e chamadas a provedores pagos permaneceram etapas separadas que você aprovou — o agente nunca fez merge, push ou release sozinho.
- 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 [Criar as contas de lançamento de desktop](https://supastack.dev/pt/docs/desktop/external-accounts.md).


## Seguinte

[Criar as contas de lançamento de desktop](https://supastack.dev/pt/docs/desktop/external-accounts.md)