Funções dos agentes

Coroid não utiliza um único agente de propósito geral. Cada etapa do caminho desde a descrição até o pull request é gerenciada por um agente com uma função específica e um conjunto de ferramentas deliberadamente restrito.

Essas restrições são o objetivo principal. Um agente que não pode escrever código não vai acidentalmente escrever código.

As funções#

Função	Etapa	Pode modificar seu código
Arquiteto	Especificação e planejamento	Não
Desenvolvedor	Criar	Sim
QA	Verificar	Não
Revisor	Revisão	Não
Testador web	Verificar fluxos do navegador	Não
Explorador	Pesquisar, em qualquer etapa	Não
Analisador de dependências	Análise	Não

Os quatro primeiros são os agentes de entrega que aparecem em todas as tarefas. No modo padrão, eles são executados nesta ordem:

Arquiteto → Desenvolvedor → QA → Revisor

No modo Coordinator, um coordenador define a ordem à medida que a tarefa avança. Ambos os modos são descritos abaixo.

Apenas uma função — o desenvolvedor — pode alterar arquivos no seu repositório. Todos os demais agentes apenas leem, executam, geram relatórios ou criam tarefas de acompanhamento.

Duas formas de execução de uma tarefa#

Uma tarefa é executada em um de dois modos. O seu AI profile e o seu implantamento determinam qual modo será utilizado.

Modo coordenador. O arquiteto não entrega seu plano e abandona a tarefa. Ele permanece na tarefa como coordenador. Após o planejamento, o coordenador passa as instruções ao desenvolvedor e aguarda o relatório. Em seguida, solicita ao QA que verifique o que foi construído e ao revisor que analise o que o QA aprovou. Depois de cada relatório, o coordenador decide o próximo passo: enviar os achados de volta ao desenvolvedor, responder a uma pergunta, revisar o plano ou finalizar a tarefa. O retrabalho é mais um passo para o coordenador, não uma nova execução.

Modo padrão. A plataforma conduz a tarefa pelos quatro agentes em uma ordem fixa, e uma verificação com falha a envia de volta ao desenvolvedor. Alguns trabalhos sempre seguem esse fluxo, como a resolução de conflitos de merge, e o modo padrão é usado quando o modo coordenador não está disponível.

Nos dois modos, os mesmos agentes executam o trabalho, respeitando as mesmas restrições e os mesmos gatilhos de controle. A diferença está em quem define o próximo passo: a plataforma no modo padrão ou o coordenador no modo Coordinator.

O coordenador#

O coordenador é o agente de planejamento associado à tarefa. Ele lê sua base de código e não pode alterá-la, então tudo o que faz é orientar.

O que o coordenador faz#

• Planos. O coordenador analisa o repositório e, em seguida, salva o plano com os critérios de aceitação que determinam se o trabalho foi bem-sucedido.
• Delegam. O coordenador trabalha com um agente por vez. Suas instruções especificam o objetivo, os critérios de aceitação que exigem atenção especial e, ao devolver o trabalho, as correções exatas a serem feitas. Enquanto o agente trabalha, o coordenador aguarda e não consome tempo de modelo.
• Responde a perguntas. Um agente que chega a uma decisão pode consultar o coordenador. O coordenador responde com a decisão e o motivo. Ele não deixa a pergunta aguardando intervenção humana.
• Reage. Caso o QA identifique falhas no trabalho ou o revisor solicite alterações, o coordenador encaminha as correções para o desenvolvedor, e o QA verifica a nova versão.
• Finaliza a tarefa. O coordenador conclui a tarefa ou a marca como falha e explica o motivo.

O que o coordenador não pode fazer#

O coordenador orienta o processo; ele não atua como juiz. A plataforma impõe esses limites, portanto eles não dependem das decisões do coordenador:

1. Os vereditos pertencem ao time de QA e ao revisor. Apenas o time de QA e o revisor emitem vereditos, cada um com seu próprio resultado. As instruções do coordenador não incluem veredito, e o coordenador não pode marcar uma verificação como aprovada.
2. A conclusão requer as etapas de validação. Uma tarefa só pode ser concluída quando o QA aprovar a versão exata que será lançada (ou o código atual, quando nada mudar) e, nos casos em que a tarefa exigir revisão, o revisor tiver aprovado essa versão. Se o branch for alterado após a execução do QA, a conclusão é recusada e a nova versão retorna ao QA.
3. O retrabalho tem limites definidos. Cada agente pode ser iniciado apenas um número limitado de vezes por tarefa, e um plano só pode ser revisado algumas vezes. O número de etapas e o tempo total de execução também são limitados. Quando esse limite é atingido, o coordenador só pode finalizar ou marcar a tarefa como falha.
4. O tempo de espera é limitado. Toda espera tem um prazo limite.

Portanto, uma tarefa gerenciada por um coordenador termina de uma de três maneiras: um pull request para você aprovar; a confirmação do QA de que o código já cumpre o que a tarefa pede, logo não há nada a alterar; ou uma tarefa com falha que indica o motivo. Ela não termina simplesmente porque o agente responsável declarou que estava pronta.

Caminhos que um coordenador pode seguir#

O coordenador escolhe como uma tarefa chega às etapas de validação. As etapas acima são as mesmas em qualquer caminho.

• O caminho completo. Planejar, construir, verificar, revisar, finalizar. É assim que uma tarefa é executada, a menos que o coordenador tenha motivo para seguir outro caminho.
• Enviando o trabalho de volta. Quando o QA reprova o trabalho ou o revisor solicita alterações, as correções retornam ao desenvolvedor. A nova versão precisa passar pelo QA antes que a tarefa possa ser concluída. A aprovação da versão anterior não se aplica à nova.
• Já feito. O código pode já cumprir o que a tarefa pede. Nesse caso, o coordenador pode solicitar ao QA que verifique o código sem alterações em relação aos critérios de aceitação, em vez de gerar novos artefatos. Quando o QA aprovar e o revisor conceder sua aprovação, onde a revisão for necessária, a tarefa é concluída sem um pull request, pois não há nada para mesclar. A verificação do QA é o resultado final. Esse caminho é encerrado assim que a execução gerar alguma alteração própria, pois o QA acabaria aprovando código que não corresponde à versão lançada.

Dois caminhos mais curtos são opcionais. O Coroid não os utiliza por padrão. Eles alteram o caminho do coordenador, nunca as etapas de validação:

• Uma alteração rápida. Para uma pequena correção em um local conhecido, o coordenador elabora um plano mais curto e fornece ao desenvolvedor instruções específicas que indicam os arquivos afetados pela alteração. O desenvolvedor trabalha dentro de um limite de etapas menor, e qualquer alteração fora desses arquivos é reportada ao QA e ao revisor.
• Uma reavaliação mais focada. Após uma pequena correção para resolver um problema identificado pelo QA ou pelo revisor, o QA começa a partir dessa descoberta e dos testes do projeto. Ele ainda emite seu parecer sobre a versão inteira resultante.

Quando a revisão é obrigatória#

Por padrão, uma tarefa que você executa sozinho sempre passa pelo revisor. Independentemente do caminho escolhido pelo coordenador, inclusive quando nada precisava ser alterado, a tarefa não pode ser concluída até que o revisor aprove a versão aprovada pelo QA. O QA sempre realiza a verificação, com ou sem revisão, e a revisão nunca substitui a aprovação do QA. Tarefas que fazem parte de um plano seguem as regras da respectiva etapa.

Coroid também possui uma política opcional baseada em riscos. Ela não está ativada por padrão. Sob essa política, uma tarefa executada de forma independente pode ser finalizada sem a necessidade de revisão quando a alteração for pequena e comum. A revisão ainda é obrigatória quando:

• uma revisão já tiver sido iniciada para a tarefa, ou as regras de revisão do seu projeto ou o Quality Graph da sua organização exigirem uma;
• a alteração envolver autenticação, sessões, permissões, segredos ou criptografia, migrações de banco de dados, configurações de compilação e implantação, arquivos de dependência ou código que se comunique com serviços externos;
• a alteração for grande (por padrão, mais de 80 linhas modificadas) ou incluir arquivos binários, links simbólicos ou submódulos;
• Coroid não consegue ler a política nem a própria alteração. Em caso de dúvida, a revisão é obrigatória.

Uma alteração que não modifique nada nunca precisará de revisão. O código toma essa decisão, não o coordenador, e o coordenador não pode contornar essa regra. Uma linha no final da descrição do pull request indica o resultado e o motivo: ela começa com "Revisão obrigatória" ou "Revisão não obrigatória".

Arquiteto#

Transforma sua descrição em uma especificação e a especificação em um plano. Ele lê o código-fonte para alinhar o plano com a realidade do projeto, mas não escreve nenhum código.

O resultado gerado é o item que você aprova antes do início da compilação. No modo Coordinator, esse agente continua atuando como coordenador.

Desenvolvedor#

Realiza o trabalho: lê o código relevante, faz a alteração, escreve ou atualiza os testes e os executa localmente no espaço de trabalho até que sejam aprovados.

Quando o Revisor envia os Achados de volta, o Desenvolvedor é a função que age com base neles. No modo Coordenador, o coordenador encaminha os Achados, com as correções a serem feitas.

QA#

Executa a verificação de forma independente do agente que escreveu o código: sua suíte de testes, as portas de qualidade configuradas para o projeto e os critérios de aceitação da especificação.

O QA emite um veredito. Ele não corrige o que encontra; as falhas são encaminhadas de volta ao Desenvolvedor como retrabalho.

Revisor#

Lê o diff finalizado e produz Achados, aplicando quaisquer regras de revisão configuradas pela sua organização. Os Achados são encaminhados de volta ao desenvolvedor como retrabalho ou anexados ao pull request para você.

Testador web#

Utiliza um navegador real para testar uma prévia em execução do seu aplicativo e verificar fluxos de usuário de ponta a ponta. É usado quando não é possível fazer uma afirmação sobre o comportamento apenas a partir do código.

Explorador#

É uma função de pesquisa somente para leitura. Outros agentes o utilizam para responder perguntas sobre um código-fonte sem precisar carregar tudo em seu próprio contexto: "onde a autenticação é tratada?", "quem chama essa função?".

Analisador de dependências#

Examina as dependências e como as alterações se propagam pelo código-fonte, incluindo projetos onde dependências entre projetos estão configuradas.

Por que a separação é importante#

Quatro propriedades resultam dessa divisão do trabalho:

1. A verificação é independente. O agente que analisa o trabalho não é o mesmo que o escreveu, portanto não tem interesse pessoal no resultado.
2. O raio de impacto é limitado. Apenas a função de desenvolvedor possui ferramentas para escrever código; assim, uma falha na revisão ou na análise não pode corromper seu repositório.
3. Cada função utiliza um modelo adequado ao seu propósito. O planejamento exige amplo conhecimento do mundo; já a escrita de código que compila requer algo distinto. AI profile contém um modelo por função justamente por esse motivo.
4. A conclusão da tarefa é determinada pelas verificações, não pelo agente responsável. No modo Coordinator, o coordenador que gerencia a tarefa não pode finalizá-la sem a aprovação do QA e do revisor.

Próximo#

Voltar para Como uma tarefa se transforma em pull request para ver em quais etapas essas funções se aplicam, ou O que é Coroid para obter uma visão geral mais resumida.