Configure com o seu assistente AI

Esta página é um guia prático escrito para um assistente AI: Claude Code, Codex, Cursor ou qualquer assistente capaz de ler uma página da web e, idealmente, trabalhar em uma cópia local do seu repositório. Ele orienta o assistente na configuração do Coroid para um ou mais repositórios. Ele para em cada etapa que requer ação humana: fazer login, conceder acesso, inserir um segredo ou aprovar uma alteração.

Entregue-o ao seu assistente#

Abra seu assistente no repositório onde deseja que o Coroid opere e forneça a ele este prompt:

Set up Coroid for this repository. Follow the runbook at
https://coroid.ai/docs/export/en-US/getting-started/assistant-setup.md
step by step. Ask me before you change anything, and never ask me to paste a
password or token into this chat.

Para vários repositórios, abra o assistente em um diretório que os contenha todos e mencione-os no prompt. O assistente realiza a inspeção e a verificação, indicando exatamente o que fazer em cada etapa que exigir sua intervenção.

Regras básicas para o assistente#

Você define o plano; o assistente prepara tudo. Você está configurando o Coroid, uma fábrica de software AI hospedada que transforma a descrição de um trabalho em um pull request testado e revisado no repositório do usuário. Siga estas regras durante todo o processo:

1. O usuário age; você prepara. Você não pode se cadastrar, fazer login, aceitar termos, instalar aplicativos ou conceder acesso em nome do usuário. Indique exatamente o que fazer e onde, e aguarde a confirmação do usuário de que a tarefa foi concluída.
2. Mantenha os segredos fora da conversa. Nunca peça senha, token de acesso pessoal, chave de provedor ou token MCP. O usuário insere esses segredos no portal do Coroid ou no próprio shell. Se algum deles for colado no chat, oriente o usuário a revogá-lo e criar um novo.
3. Pergunte antes de cada alteração: commits, ramificações e pull requests no repositório do usuário, projetos do Coroid e convites.
4. Verifique cada etapa antes de prosseguir. Se uma verificação falhar, utilize as observações dessa etapa e continue somente após a aprovação ou se o usuário decidir ignorá-la.
5. Siga o produto, não suas suposições. Se o portal exibir algo que este guia não descreve, informe ao usuário o que você vê e siga as instruções do portal. Não invente configurações.
6. Mantenha um registro da configuração de cada etapa e seu resultado, para consulta final.

Cada etapa vincula as páginas com os detalhes. https://coroid.ai/llms.txt Indexa toda a documentação.

Etapa 1: Definir o plano#

Faça estas perguntas ao usuário de forma conjunta, não uma por vez:

Em seguida, repita o plano: os passos abaixo que exigem a intervenção do usuário e os repositórios em escopo.

Veja Planos e preços, Limites e cotas e Sincronizado ou apenas local.

Passo 2: Verifique se cada repositório compila e testa a partir de um clone limpo#

Esta é a tarefa mais útil que você pode realizar. Toda tarefa do Coroid é executada em um ambiente de trabalho Linux limpo e descartável: um clone novo, sem nada em cache, sem nada instalado além do conjunto de ferramentas da imagem. Um agente que não consegue compilar e testar o projeto não pode validar seu próprio trabalho, e suas tarefas falham na verificação por motivos não relacionados à alteração.

Se você puder trabalhar no repositório localmente, faça o seguinte para cada um:

1. Identifique as linguagens, o gerenciador de pacotes e se é um monorepo.
2. Encontre os comandos de instalação, compilação e teste no README, na configuração de CI e nos manifestos.
3. Pergunte antes de executar qualquer coisa. Em seguida, clone o repositório em um diretório temporário vazio e execute instalação, compilação e teste ali, sem nenhuma outra configuração. A cópia de trabalho do usuário possui caches e .env arquivos que ocultam problemas.
4. Anote tudo o que a execução necessitou e que um clone novo não possui:
   • serviços que os testes esperam, como um banco de dados, um cache ou uma fila
   • passos antes dos testes, como geração de código, migrações ou fixtures
   • variáveis de ambiente ou um .env arquivo que não foi commitado
   • registros de pacotes privados
   • um runtime que não está no ambiente do agente

Nunca execute comandos que façam deploy, publiquem ou toquem em ambientes compartilhados. Se a suíte for lenta ou utilizar serviços pagos, pergunte ao usuário antes.

Gere um relatório rápido de verificação de prontidão por repositório: os comandos usados, o tempo que a suíte levou para executar, quais testes passaram e cada falha com uma correção proposta.

A ausência de um runtime também não é um impedimento: um contêiner que inclua o conjunto de ferramentas resolve isso. Se você não conseguir acessar o repositório localmente, colete o máximo possível do usuário e registre que a verificação de clone limpo não ocorreu.

Veja Configuração de build e teste e Suporte a linguagens e o ambiente dos agentes.

Passo 3: Escreva as instruções que os agentes do Coroid irão ler.#

Antes de cada tarefa, os agentes do Coroid leem os arquivos de memória no repositório: AGENTS.md, CLAUDE.md ou GEMINI.md na raiz, e .cursor/rules. Os comandos que você verificou no Passo 2 devem estar ali.

Proponha um AGENTS.md, ou uma adição ao existente, que contenha:

• os comandos de instalação, build e teste, verificados em um clone limpo, e o diretório onde devem ser executados.
• as etapas e serviços necessários para os testes.
• como executar o conjunto mais restrito e útil de testes, como um pacote ou um arquivo.
• convenções e limites que o código não mostra: módulos congelados, áreas que não devem ser alteradas, dependências que não devem ser adicionadas.

Deixe de fora o que o código já indica e mantenha o arquivo curto. Se CLAUDE.md or .cursor/rules contiver as mesmas instruções, mantenha-as apenas em AGENTS.md e importe-o do outro arquivo com um @AGENTS.md linha.

Mostre o diff ao usuário. Com sua aprovação, commit no novo ramo e abra um pull request, ou deixe que ele faça o commit. O arquivo deve chegar ao ramo base antes da primeira tarefa, pois cada tarefa lê os arquivos de memória a partir de seu próprio checkout desse ramo. Trate as correções do Passo 2 que o usuário aceitou da mesma forma.

Veja Configurações de contexto do projeto e Contexto do projeto.

Passo 4: Conta e organização (o usuário)#

Pule esta etapa se o usuário já pertencer a uma organização Coroid como Proprietário ou Administrador.

Peça ao usuário para:

1. se cadastrar em https://client.coroid.ai/auth/signup com seu e-mail corporativo e verificar o endereço
2. aceitar os termos de serviço
3. criar a organização

Verifique: se o usuário consegue abrir https://client.coroid.ai/projects. A pessoa que conclui esta configuração precisa ter a função de Proprietário ou Administrador, pois apenas essas funções permitem conectar o controle de versão e adicionar chaves de provedor.

Veja Crie sua conta e organização.

Passo 5: Conectar o controle de versão (o usuário)#

Reveja os requisitos de acesso com o usuário antes de começar. Uma instalação que para no meio aguardando aprovação de outra pessoa é o motivo comum pelo qual esta etapa leva um dia em vez de um minuto.

GitHub#

O usuário abre Configurações → Conexões → Controle de versão (https://client.coroid.ai/settings/connections/source-control).

GitHub App: na tela de instalação do GitHub, o usuário seleciona Selecione apenas repositórios e seleciona os que foram acordados na Etapa 1. O aplicativo continua funcionando mesmo quando a pessoa que o instalou sai, recebe eventos de webhook e é isso que permite que o Coroid publique suas verificações nos pull requests. Um token não consegue publicar verificações do GitHub.

Token de acesso pessoal: o usuário cria no GitHub com um prazo de validade e cola no portal do Coroid. Prefira um token com escopo restrito aos repositórios acordados. Os pull requests são atribuídos ao proprietário do token, e a conexão é interrompida se essa pessoa perder acesso.

GitLab#

GitLab está em pré-visualização privada e só aparece em contas onde foi habilitado. Ele se conecta usando um token de acesso pessoal com o api escopo. Se o GitLab não aparecer em Controle de versão, oriente o usuário a entrar em contato com o Coroid e não conte com ele.

Proteção de ramificação#

Coroid abre pull requests comuns, portanto a proteção de ramificação, as verificações obrigatórias e as regras de revisão ainda se aplicam. Recomenda-se manter a proteção ativada. Se as regras exigirem commits assinados ou uma verificação de status que o Coroid não consiga gerar, seus pull requests serão abertos e permanecerão não mescláveis. Informe o usuário e não altere suas regras.

Verificação: o provedor aparece como conectado em Controle de versão. A prova real vem na Etapa 6, quando os repositórios aparecem na lista de projetos.

Veja Conectar seu código, GitHub, GitLab e Configurações de repositório e ramificação.

Etapa 6: Criar os projetos (o usuário)#

Crie um projeto por repositório; nunca crie dois para um único repositório. O usuário abre Projetos → Novo (https://client.coroid.ai/projects/new) e, para cada repositório:

1. seleciona-o do provedor conectado ou usa Conectar com URL para um repositório público
2. escolhe o Modo de repositório: Sincronizado, onde o Coroid envia ramificações e abre pull requests, ou Apenas local, onde o Coroid nunca grava no repositório até que alguém escolha Iniciar sincronização
3. verifica a ramificação padrão
4. cria o projeto

Se a equipe fizer merge em algo diferente da ramificação padrão, como develop, defina a ramificação base nas configurações de repositório do projeto. Uma ramificação base incorreta envia pull requests para uma ramificação que ninguém revisa.

Se um repositório estiver ausente da lista, a causa quase sempre é uma das seguintes:

• o aplicativo GitHub não recebeu permissão para acessar esse repositório
• o escopo do token é muito restrito para listá-lo
• o repositório pertence a uma organização diferente daquela conectada

Veja Crie seu primeiro projeto e Configurações de repositório e ramificação.

Passo 7: Verifique o que o Coroid encontrou#

Peça ao usuário para abrir a visão geral de cada projeto e ler em voz alta as Repositório detalhes e tudo o que estiver listado em Finalizar configuração:

• Status e Ramificação: o repositório é clonado na ramificação base que você acordou. Se a visão geral indicar que o repositório ainda não foi clonado, o usuário deve selecionar Clonar repositório.
• Pilha: as linguagens, frameworks, gerenciadores de pacotes e ferramentas de teste que o Coroid detectou. Compare-os com sua verificação de prontidão. Se a pilha estiver vazia ou incorreta após a primeira sincronização, o usuário pode escanear novamente a partir daí.
• Finalizar configuração: itens como "Dependências não foram instaladas corretamente" apontam para as mesmas lacunas do Passo 2. Resolva-os junto com o usuário.

Em seguida, o usuário abre as Configurações → Conhecimento → Contexto. O arquivo de memória do Passo 3 deve estar listado em Fontes de repositório e estar ativado. Se aparecer Criar em vez disso, o arquivo ainda não chegou à ramificação conectada.

Veja Configurações de contexto do projeto e Configuração de compilação e teste.

Passo 8: Configurações da organização (opcional)#

Pergunte se o usuário deseja configurar alguma dessas opções agora. Todas têm valores padrão viáveis:

• Membros, em Configurações → Membros: as pessoas que irão revisar pull requests, como Proprietário, Administrador, Membro ou Revisor. Recomende a função de Administrador apenas para quem precisar alterar políticas e chaves de provedor. Requer plano Professional.
• Chaves de provedor, em Configurações → Chaves de provedor: apenas para usar as contas de provedor de modelo próprias da organização. O usuário insere a chave no portal. Recomende uma chave restrita com limite de gastos no provedor.
• Configurações de outra organização: exporte um pacote de configurações lá e importe-o em Configurações → Dados → Exportar configurações. Os segredos são transmitidos como placeholders, portanto cada needsRebind item na pré-visualização requer atenção.

Veja Crie sua conta e organização, Chaves de provedor e Exportar e importar configurações.

Passo 9: Conecte-se ao Coroid (opcional)#

Se o seu cliente suportar servidores MCP remotos, você poderá acessar o Coroid por meio do seu servidor MCP em https://api.coroid.ai/mcp. A configuração não depende disso, mas permite que você verifique os projetos pessoalmente e ajude o usuário a executar tarefas posteriormente.

1. O usuário abre Configurações → Conexões → Coroid MCP server (https://client.coroid.ai/settings/connections/coroid-mcp). Se ele não estiver disponível para a organização dele, pule este passo.
2. Configuração do cliente mostra os comandos por cliente. Com OAuth, o usuário aprova seu acesso no navegador. Com um token de acesso pessoal, o usuário o cria em Tokens de acesso e o armazena em uma variável de ambiente no próprio shell dele. Você nunca precisará ver o valor.
3. Recomende o menor nível de acesso que funcione: mcp.read para verificar a configuração, além de mcp.work.write somente se você for criar tarefas. Limite o token a esses projetos, defina um prazo de validade e configure Políticas de automação antes que qualquer cliente execute tarefas sem supervisão.

Verifique: chame list_projects, depois get_project para cada projeto do Passo 6, e confirme o repositório e o branch.

Use apenas api.coroid.ai para MCP. O nome de host do portal do cliente não oferece esse recurso.

Veja Coroid como servidor MCP.

Passo 10: Rascunhe uma primeira tarefa#

Termine rascunhando uma pequena primeira tarefa com o usuário em um dos novos projetos. Uma boa primeira tarefa é real, pequena, próxima de testes existentes e tem um objetivo claro. Evite autenticação, pagamentos, migrações de dados, limpezas sem fim e qualquer coisa que exija uma decisão de design ainda não tomada.

Descreva o resultado, não a implementação: o que deve estar certo quando o trabalho for concluído, quais arquivos são relevantes e o que não deve ser alterado. O usuário envia isso de Novo trabalho (https://client.coroid.ai/work/new), lê a specificação e aprova o plano. A execução de tarefas consome horas de agente, e o plano gratuito inclui 2 por dia UTC; deixe o usuário decidir quando executar.

Veja Execute sua primeira tarefa e Especificações.

Passo 11: Entrega final#

Forneça ao usuário o registro de configuração:

• cada repositório, seu projeto, modo de repositório e branch base
• como o controle de versão está conectado e quem é o proprietário da conexão: o instalador do aplicativo ou o proprietário do token e sua data de expiração
• por repositório, as correções feitas, as pendentes (como um pull request aberto com AGENTS.md), e as que o usuário optou por deixar de lado
• as configurações opcionais aplicadas e ignoradas, e a primeira tarefa rascunhada

Depois, indique ao usuário o Revisar e mesclar o resultado para ver o que chega com o primeiro pull request.

Próximo#

Crie sua conta e organização — a mesma configuração, feita manualmente.