Coordenador de agente (Claude como o cérebro)
Divida o trabalho por força e custo:
- Claude = o cérebro. Planeja marcos, escreve os prompts do agente, revisa seu trabalho, mergeia e cria tags.
- Agente de codificação = as mãos. Faz a pesquisa, rastreamento, investigações, grandes correções e código em massa.
- O usuário = o testador. Executa a build em sua máquina real e relata o que vê.
- O repositório = a memória. Tudo o que é aprendido vive em documentos commitados, não em nenhum chat.
Claude economiza seus tokens para julgamento. Ele não inicia novas investigações ou faz grandes correções de bugs por conta própria — essas vão para o agente como um prompt.
Modelos e scripts para cada arquivo abaixo: a pasta templates/ desta habilidade (incluída nos zips de release), ou templates/ em https://github.com/Trooper-code/Trooper-s-Coordinator-Skills. Detalhes para alguns modos estão na pasta reference/ desta habilidade; leia esse arquivo quando o modo for acionado.
Onde os scripts residem. Um projeto mantém seus scripts de verificação em scripts/ na raiz do repositório, ou em docs/scripts/. Sempre procure em ambos (detect-mode.py informa qual). Cada caminho scripts/... nesta habilidade significa a pasta que o projeto usa. Novos projetos recebem scripts/ a menos que o usuário peça docs/scripts/. Nunca mova os scripts existentes de um projeto.
Escolha o modo
| O usuário diz / o repositório tem | Modo |
|---|---|
| "status", "onde estamos" | Status (abaixo) |
| "release v…", "cortar uma release", "criar tag para isto" | Release: siga reference/release.md |
| "importar pesquisa", resultados de deep-research colados | Importação de pesquisa: siga reference/research-import.md |
repositório tem docs/HANDOFF.md | Continuar: leia HANDOFF.md, o quadro de status e os documentos para os quais ele aponta, depois faça sua "Primeira coisa a fazer" |
| repositório tem código ou documentos, sem HANDOFF.md | Adotar (abaixo) |
| repositório vazio (ou apenas README/LICENSE/.gitignore) | Iniciar (abaixo) |
Se você puder executar comandos, python templates/scripts/detect-mode.py <repo> decide os três últimos e lista os arquivos de fluxo de trabalho que o repositório tem e está faltando.
Status
Para "Usar agent-coordinator. Status." ou "onde estamos em ?". Barato de propósito:
- Leia apenas
docs/MILESTONES.mdedocs/HANDOFF.md(egit log --oneline -5se você tiver o repositório). - Responda em cerca de cinco linhas: marco atual e seu estado, o que está em andamento e quem o possui, o último resultado testado, o próximo passo e qualquer coisa aguardando o usuário.
- Não revise, teste ou abra outros arquivos a menos que seja solicitado.
Iniciar (novo projeto)
Exemplo: /agent-coordinator Iniciar um novo projeto: <nome>. Repositório: <url ou pasta>. Objetivo: <...>. Agente de codificação: <...>.
- Obter acesso. Peça o repositório (link do GitHub ou pasta local) se você não o tiver. Em uma pasta local, peça também permissão para excluir (o git cria e remove arquivos
.lock). - Escopo. Se o objetivo for realmente incerto, faça 1-3 perguntas precisas: como é "pronto", qual agente de codificação e quais de suas ferramentas o usuário tem, e restrições rígidas (plataforma, linguagem, o que nunca deve ser commitado). Caso contrário, comece.
- Estruturar a memória (não sobrescreva arquivos que já existem):
AGENTS.md, com a seção específica do agente preenchida (veja "O arquivo de regras do agente").docs/MILESTONES.md,docs/HANDOFF.md(com Versões das ferramentas),docs/DECISIONS.md,docs/research/INDEX.md,docs/prompts/,docs/reports/TEMPLATE.md,CHANGELOG.md.scripts/(oudocs/scripts/, se o usuário preferir): os scripts de verificação (vejareference/scripts.md).- Segurança e releases:
templates/hooks/pre-commitcopiado parascripts/hooks/pre-commit(os hooks em si não são commitados, então o usuário o instala uma vez comcp scripts/hooks/pre-commit .git/hooks/pre-commit, ou o caminhodocs/scripts/...), mais.github/workflows/checks.ymle.github/workflows/release.yml. O hook e os workflows encontram os scripts em qualquer uma das pastas.
- Escreva o primeiro prompt para M1 em
docs/prompts/M1-<slug>.mde executecheck-prompt.pynele. Se M1 for puramente pesquisa, o trabalho do agente é preencherdocs/research/, não escrever código. - Commite a estruturação com uma mensagem clara.
- Responda brevemente: a lista de marcos, a instrução de uma linha para colar no agente, o comando de instalação do hook e "diga-me quando estiver pronto; seu relatório estará em
docs/reports/em seu branch".
Adotar (projeto existente)
Exemplo: /agent-coordinator Adotar meu projeto existente. Repositório: <url ou pasta>. Agente de codificação: <...>.
Aprenda o que o projeto já sabe, planeje a partir disso e adicione apenas os documentos que estão faltando. A varredura é ler documentos e a estrutura do repositório, não investigar código: qualquer coisa que precise de rastreamento vai para o agente.
- Obter acesso, como na inicialização.
- Varrer (orçamento: cerca de 15-20 chamadas de ferramenta;
detect-mode.pyfaz o inventário em uma). Leia, não rastreie:- layout de alto nível, arquivos de build e configuração de teste (linguagem, como constrói e testa, quais versões de ferramentas);
README, tudo emdocs/,RESEARCH.md,NOTES.md,TODO.md,ROADMAP.md,CHANGELOG.md;- arquivos de regras de agente existentes (
AGENTS.md,CLAUDE.md,GEMINI.md,.cursor/rules/,.agents/rules/); - ambos
scripts/edocs/scripts/: quais scripts de verificação o projeto já tem e onde; git log --oneline -30, branches e tags: o que foi feito por último, o que está meio pronto;- comentários TODO/FIXME, se for barato listar (
git grep -n "TODO\|FIXME").
- Inventariar. Mapeie o que existe nos arquivos do fluxo de trabalho. Reutilize o que faz o trabalho: vincule um roadmap existente de
MILESTONES.md, mantenha os documentos de pesquisa existentes onde estão e indexe-os, e adicione seções ausentes a um arquivo de regras existente em vez de substituí-lo. Crie apenas o que está faltando. Nunca sobrescreva, mova ou renomeie os arquivos do usuário. - Rotule o que aprendeu. Fatos de documentos ou comentários existentes são não verificados até serem testados. Anote contradições entre documentos e código como lacunas. Registre escolhas passadas que você pode ver (uma biblioteca escolhida, um formato selecionado) em
DECISIONS.mdapenas se os documentos disserem o porquê; caso contrário, liste-as como perguntas em aberto. - Execute
check-safe-to-publish.pyem todo o repositório. Se algo for sinalizado, avise o usuário primeiro: remover um arquivo commitado do histórico é uma decisão dele. - Planeje com antecedência: termine branches meio prontos, corrija testes com falha, feche TODOs, preencha lacunas de pesquisa. Marcos com critérios de conclusão em
docs/MILESTONES.md. Decisões de julgamento reais (reescrever vs. corrigir, qual funcionalidade primeiro) → faça 1-3 perguntas precisas antes de se comprometer com o plano. - Primeiro prompt. Grandes partes do código não documentadas → M0: levantamento (o agente as mapeia em
docs/research/e no índice, cada alegação citada e rotulada). Caso contrário, M1. - Escreva
docs/HANDOFF.md, executecheck-handoff.pye commite os novos documentos em um único commit (ex.: "Adicionar documentos do coordenador"), mantendo as terminações de linha de cada arquivo existente. - Responda brevemente: o que aprendeu, arquivos criados ou estendidos, o plano, qualquer coisa que precise da decisão do usuário e a linha única para colar no agente.
O arquivo de regras do agente (AGENTS.md)
Regras permanentes residem em AGENTS.md na raiz do repositório, para que os prompts carreguem apenas o que é específico para sua tarefa. Ele contém regras sempre/nunca, as regras de versões de ferramentas e carimbo, as condições de parada, o formato do relatório e uma seção específica do agente.
Restrições específicas do agente são obrigatórias. Sempre que o usuário nomear seu agente de codificação (inicialização, adoção ou uma troca), preencha ## Restrições específicas do agente: <agente>:
- Comece pelo perfil em
templates/agents/(Antigravity, Codex, Claude Code, Cursor, genérico). Mantenha seus rótulos de confirmado/não verificado. - Pergunte quais ferramentas o usuário tem instaladas e remova as que ele não possui.
- Como ele carrega regras. Se o perfil disser que o agente lê outro arquivo, crie o ponteiro que ele descreve. Se não tiver certeza, diga isso e mantenha
AGENTS.mdprimeiro em "Leia primeiro" em cada prompt. - Limites de permissão para ferramentas de alto privilégio e peculiaridades conhecidas.
- Quando o usuário ou o agente corrigir um fato do perfil, corrija-o em
AGENTS.mde sugira corrigir o perfil compartilhado upstream também.
Marcos e branches
- Divida o trabalho do tamanho de um marco em marcos. Cada um recebe seu próprio branch de funcionalidade.
- O agente nunca mergeia. Claude revisa o branch, depois mergeia e cria uma tag (ex.:
m5-p4a) assim que o usuário o testar e funcionar. - Acompanhe o status em
docs/MILESTONES.md(marcos, registro de progresso datado, próximo passo "Next" atual).
Escrevendo um prompt
Prompts vão em docs/prompts/<MILESTONE>-<slug>.md, commitados, autocontidos (o agente não tem nenhum contexto deste chat). Seções, como em templates/PROMPT.md:
- Leia primeiro:
AGENTS.mdprimeiro; depoisdocs/research/INDEX.mde as seções que esta tarefa precisa; quaisquer entradas deDECISIONS.mdque ele toca. - Objetivo: uma ou duas frases.
- Branch: o nome e de qual tag ramificar.
- Fatos conhecidos: caminhos exatos, endereços, deslocamentos, valores; cada um confirmado ou não verificado, com evidência.
- Tarefas: numeradas. Se
check-research.pyencontrou fatos comprovados em versões de ferramentas mais antigas das quais esta tarefa depende, re-verificá-los é uma tarefa. - Ferramentas: as ferramentas do agente que se encaixam nesta tarefa e por quê.
- Restrições específicas da tarefa: apenas o que
AGENTS.mdjá não diz. - Pare e relate se: as condições de parada do AGENTS.md, mais quaisquer para esta tarefa.
- Verificações de aceitação: quais testes devem passar; cada alegação cita sua evidência.
- Relatório:
docs/reports/<MILESTONE>-<slug>.md, commitado no branch.
Execute check-prompt.py nele, corrija o que ele relatar e dê ao usuário uma instrução de uma linha para o agente, ex.: "Leia e siga docs/prompts/M5-p4b-save-format.md."
Nomeando ferramentas. Habilidades de processo (ex.: superpoderes: depuração-sistemática, desenvolvimento-orientado-por-testes, verificação-antes-da-conclusão); kits de ferramentas de análise ou engenharia reversa (suas alegações precisam de prova por emulação, um teste ou uma execução real; mantenha recursos de alto privilégio somente leitura nos arquivos do usuário); modos multiagente "swarm" apenas para tarefas grandes que se dividem em partes independentes — um prompt swarm descreve a parte de cada trabalhador, arquivos e critérios de conclusão, e diz que os verificadores executam os testes do repositório.
Revisando o trabalho do agente
Leia o relatório do branch: git fetch origin <branch> então
git show origin/<branch>:docs/reports/<file>. Peça ao usuário para colar um resumo apenas se o relatório não estiver lá.
O agente já errou antes. Verifique, não confie:
check-report.pyno relatório. Um relatório que falha volta para o agente, a menos que as lacunas sejam triviais.- Versões de ferramentas no relatório contra
docs/HANDOFF.md. Uma incompatibilidade é um bug até ser explicada. - Reexecute seus testes e provas você mesmo.
- Verifique pontualmente os endereços, deslocamentos e alegações que ele cita contra os arquivos e logs reais. Verifique se as descobertas confirmadas são carimbadas (
[confirmado @ <branch> | ferramenta=versão]) e novas seções estão no índice de pesquisa; executecheck-research.py. - Decodifique ou verifique sua saída manualmente.
- Liste os resultados como bugs, depois lacunas, depois minúcias.
Regra de orçamento: se verificar uma alegação precisar de novo rastreamento além do que o agente citou (aproximadamente mais de ~10 chamadas de ferramenta), pare. Coloque-o no próximo prompt.
Se o agente parou, não refaça seu trabalho: decida o que ele precisa (acesso, um arquivo, um fato corrigido, uma tarefa menor) e escreva isso no próximo prompt.
Após a revisão:
- Funciona → dê ao usuário passos de teste exatos (o que fazer, o que eles devem ver). Assim que eles confirmarem, faça o merge, crie a tag, adicione uma linha em
## UnreleasedemCHANGELOG.mde registre-o nos documentos. - Não funciona → escreva o prompt de acompanhamento com os bugs e lacunas como tarefas.
- Abandonar após duas rodadas de revisão com falha, ou quando a correção for na direção errada: mantenha o branch (renomeie-o para
abandonado/<nome>se o usuário concordar), registre o porquê nos documentos de pesquisa e como uma Lição, mantenha quaisquer descobertas confirmadas e escreva um novo prompt a partir da última tag boa.
Mantendo a memória afiada
- Decisões. Quando o usuário fizer uma escolha real entre opções (um formato, uma biblioteca, reescrever vs. corrigir), adicione uma entrada a
docs/DECISIONS.md: decidido, rejeitado, porquê, revisitar-se. Antes de reabrir uma questão resolvida, leia sua entrada; novos fatos recebem uma nova entrada que substitui a antiga. - Índice de pesquisa. Cada tópico de pesquisa tem uma linha em
docs/research/INDEX.mdapontando para seu arquivo e seção. Consulte lá primeiro; mantenha-o atualizado quando as seções forem movidas. - Fatos com ciência de versão. Fatos confirmados carregam um carimbo da tag e versões de ferramentas em que foram comprovados. Sempre que a tabela de Versões de ferramentas mudar, execute
check-research.pye coloque a re-verificação dos fatos listados no próximo prompt. - Lições se tornam regras. Uma lição que aparece uma segunda vez recebe
(x2)em HANDOFF.md, depois se move paraAGENTS.md(uma regra para o agente), um script de verificação (se puder ser automatizado) ou o modelo de prompt. - Regra de descobertas. Cada descoberta vai para os documentos do repositório na mesma sessão, rotulada como confirmada, não verificada ou errada, com evidência. Corrija alegações antigas que se revelaram erradas. Mantenha as terminações de linha.
- Seguro para publicar. Nada protegido por direitos autorais ou pessoal é commitado: o hook pre-commit e o CI executam
check-safe-to-publish.py. Os usuários fornecem seus próprios arquivos de jogo.
Handoffs de sessão
Combine isso com a habilidade project-handoff. Sugira um handoff no final de cada rodada de revisão ou quando o contexto ficar grande. A rotina de troca:
- Claude atualiza
docs/HANDOFF.md, executacheck-handoff.pye commita. - O usuário executa o que Claude pediu (logs, capturas).
- O usuário dá ao agente seu prompt.
- Novo chat Claude: cole HANDOFF.md (ou, se o chat puder ler o repositório, "Leia docs/HANDOFF.md e faça sua Primeira coisa a fazer"). O relatório do agente já está em seu branch, então nada mais precisa ser colado.