Skip to content
← Todos os capítulos

Capítulo 05

Arquétipos de repositório

Antes de alterar uma única linha, um agente toma uma decisão que molda tudo o que vem a seguir: que tipo de repositório é este? O arquétipo que ele infere define o limite dentro do qual raciocina pelo resto do trabalho — como faz o onboarding, até onde um plano alcança e onde o estado reside. Errar significa definir o escopo do trabalho para a superfície errada, a causa mais comum de deriva em tarefas de longo horizonte. Acertar permite ao agente trabalhar de forma autônoma por horas, porque planos, onboarding e estado se alinham com a forma real do código.

O DWP reconhece dois arquétipos. A maioria dos repositórios é do primeiro tipo; o segundo existe para as equipes que coordenam muitos.

Repositório individual

O caso comum: uma base de código autocontida — uma aplicação, uma biblioteca ou um serviço. Há uma única superfície coerente sobre a qual raciocinar, de modo que os planos operam diretamente sobre o código no repositório e o onboarding lê a estrutura e as convenções do próprio repositório. O agente mantém toda a base de código como contexto e trabalha nela de ponta a ponta.

Características:

  • Uma única base de código coerente.
  • Os planos modificam arquivos neste repositório.
  • O espaço de trabalho .dwp/ vive na raiz do repositório.

Hub orquestrador

O caso de coordenação: um repositório cuja função é gerenciar outros repositórios. Aqui a unidade de trabalho não é um arquivo, mas um repositório filho; portanto, os planos podem criar planos filhos em sub-repositórios, e o onboarding lê o registro de repositórios gerenciados do hub em vez de uma única base de código. O agente raciocina sobre fronteiras e transferências — qual repositório é dono de qual trabalho e como o estado entre eles permanece consistente.

Características:

  • Coordena múltiplos sub-repositórios.
  • Os planos podem delegar a planos filhos.
  • Mantém um registro de repositórios gerenciados.
  • O espaço de trabalho .dwp/ na raiz do hub rastreia o estado entre repositórios.

Heurística de classificação

Os dois arquétipos se parecem diferentes em disco, e o agente decide entre eles a partir de sinais que pode verificar — não de um rótulo que lhe foi informado. A árvore de decisão abaixo mostra o caminho; em resumo, trate um repositório como hub orquestrador somente quando a evidência o exigir, e como repositório individual nos demais casos.

Um agente deve classificar um repositório como hub orquestrador quando encontra múltiplos repositórios git aninhados ou submódulos, um registro ou manifesto de repositórios gerenciados, ou configuração que aponta para repositórios externos. Na ausência desses sinais, ele trata o repositório como um repositório individual — o padrão seguro, pois ampliar o escopo de um plano além de fronteiras que não existem é pior do que trabalhar dentro de uma que existe.

Como o onboarding difere

O arquétipo não é um rótulo cosmético; ele muda o que o agente lê, o que um plano pode tocar e onde o estado é registrado.

Aspecto Individual Orquestrador
Escopo Este repositório Múltiplos repositórios
Onboarding Estrutura do repositório Registro do hub
Alvo do plano Arquivos locais Planos filhos
Estado .dwp/ local .dwp/ entre repositórios

O efeito prático é que um agente de repositório individual raciocina sobre uma base de código de ponta a ponta, enquanto um agente orquestrador raciocina sobre coordenação — qual repositório filho é dono de qual trabalho e como o estado entre repositórios permanece consistente.

Acertar o arquétipo é o que permite a um agente trabalhar de forma autônoma por horas sem supervisão: ele ajusta os planos, o onboarding e o estado à fronteira certa, de modo que o agente opere sobre a superfície correta da primeira à última tarefa.