Multiagente e Orquestração|INEMA.CLUB-PRO

Aula 8 · 20 min

Projetar o time do seu loop

Um time de agentes cabe numa página: a decisão da aula 1 e, para cada papel, nível, ferramentas, o que escreve, isolamento, entrada, retorno, quem verifica e teto. Escrito assim, um script confere se falta campo ou se dois papéis gravam no mesmo lugar sem isolamento. Nesta aula você escreve o time.md do seu loop, confere e roda.

Começar a aula
Quadro escuro com fichas brancas sem texto presas em árvore, ligadas por fios, sob uma luminária.

Nesta aula você vai

  1. 1Os oito campos de cada papel
  2. 2Dono de arquivo: quem escreve onde, e isolado como
  3. 3Um conferidor que acusa campo faltando e colisão
  4. 4O mapa do curso e o seu plano com datas

Objetivo: escrever o time.md do seu loop (papel, nível, ferramentas, dono dos arquivos, isolamento, retorno, verificação, teto) e rodá-lo.

01Do pedido ao time

Cada etapa usa uma aula do curso. Clique para ver qual.

Clique em cada bloco do diagrama para ver o que ele faz.

Comece com o menor time que faz o trabalho. Papel novo só entra quando você souber dizer o que ele devolve e quem confere.

02O time.md e o conferidor

Copie o modelo, troque pelos papéis do seu loop e rode o conferidor. Nenhum modelo é chamado.

time.md · modelo com quatro papéis
# Time do loop — [nome do loop]

Decisão (aula 1): híbrido — planejar e revisar no centro; executar em paralelo só os itens independentes.

## papel: planejador
- nível: topo
- ferramentas: Read, Grep, Glob
- escreve em: nada
- isolamento: nenhum (só lê)
- entrada: goal.md
- retorno: plano em até 5 passos + critérios comando → saída (quem grava em plans/ é o orquestrador)
- verificado por: você (portão humano antes de executar)
- teto: 1 rodada

## papel: executor
- nível: executor
- ferramentas: Read, Write, Edit, Bash, Grep, Glob
- escreve em: src/ tests/novos/
- isolamento: worktree
- entrada: plano aprovado
- retorno: lista de arquivos mudados + saída dos testes
- verificado por: avaliador
- teto: 3 rodadas, 600 s cada

## papel: avaliador
- nível: menor
- ferramentas: Read, Bash, Grep, Glob
- escreve em: nada
- isolamento: sandbox read-only
- entrada: goal.md + diff + saída dos testes
- retorno: OK/FALHA por critério + APROVADO ou FALTA
- verificado por: script verificar.mjs
- teto: 1 rodada por entrega

## papel: revisor-codex
- nível: executor
- ferramentas: codex exec -s read-only
- escreve em: nada
- isolamento: sandbox read-only
- entrada: mesmo briefing + diff real
- retorno: até 6 linhas, última APROVADO ou FALTA
- verificado por: você reconcilia (aceito, rejeitado com evidência, em aberto)
- teto: 2 rodadas
confere-time.py · salve ao lado do time.md
# confere-time.py — confere o time.md: todo papel tem os 8 campos, e nenhum
# arquivo tem dois donos sem isolamento (a colisão das aulas 5 e 6).
# Uso: python3 confere-time.py time.md
import re, sys

CAMPOS = ["nível", "ferramentas", "escreve em", "isolamento", "entrada",
          "retorno", "verificado por", "teto"]
NIVEIS = {"menor", "executor", "topo", "super"}
texto = open(sys.argv[1], encoding="utf-8").read()
papeis = re.findall(r"^## papel: *(.+?)\n(.*?)(?=^## |\Z)", texto, re.M | re.S)
problemas = 0
donos = {}
for nome, corpo in papeis:
    campos = dict(re.findall(r"^- ([^:]+): *(.+)$", corpo, re.M))
    faltam = [c for c in CAMPOS if not campos.get(c, "").strip()]
    if faltam:
        print(f"{nome}: falta {', '.join(faltam)}"); problemas += 1
    if campos.get("nível") and campos["nível"] not in NIVEIS:
        print(f"{nome}: nível '{campos['nível']}' não é menor/executor/topo/super"); problemas += 1
    escreve = campos.get("escreve em", "nada")
    if escreve != "nada" and campos.get("isolamento", "nenhum").startswith("nenhum"):
        for alvo in escreve.split():
            donos.setdefault(alvo, []).append(nome)
    if escreve != "nada" and "ferramentas" in campos and not re.search(r"Write|Edit|Bash|workspace-write", campos["ferramentas"]):
        print(f"{nome}: escreve em {escreve}, mas as ferramentas só leem"); problemas += 1
for alvo, quem in donos.items():
    if len(quem) > 1:
        print(f"colisão: {alvo} tem {len(quem)} donos sem isolamento ({', '.join(quem)})"); problemas += 1
print(f"papéis: {len(papeis)} · problemas: {problemas}")
sys.exit(1 if problemas or not papeis else 0)
Terminal · conferir
cd ~/treino-multi
python3 confere-time.py time.md; echo "saída: $?"
Exemplo do repositório
papéis: 4 · problemas: 0
saída: 0

O modelo passa. O planejador escreve "nada": quem grava o plano em disco é o orquestrador. Na primeira versão do modelo, o planejador dizia "escreve em: plans/" com ferramentas só de leitura, e o conferidor acusou a contradição.

03Prática final

O seu time no papel, conferido, e uma rodada de verdade.

E17 · O time.md do seu loop

30 min

Rode a matriz (aula 1) para o loop que você quer montar. Escreva o time.md com os papéis que a decisão pede, troque [nome do loop] e rode o conferidor.

Pronto quando: python3 confere-time.py time.md; echo "saída: $?" → papéis: N · problemas: 0 e saída: 0, com N igual ao número de papéis que você escreveu.

E18 · Uma rodada do time

45 min

Escolha uma tarefa pequena do seu projeto. Escreva o goal com 2 ou 3 critérios e faça commit dele. O executor roda pelo gera-avalia.sh num worktree (git worktree add) e o revisor Codex lê o diff pela ponte. Reconcilie os achados no revisao.md.

Pronto quando: ./gera-avalia.sh goal.md "[pedido]" termina em → APROVADO e saída: 0; tail -1 revisao-codex.txt | grep -cE '^-? ?(APROVADO|FALTA:)' → 1; grep -cE "^(aceito|rejeitado|aberto):" revisao.md é igual ao número de achados.

04O mapa do curso

Quatro entregas, na ordem. Clique num exercício para ver o "pronto quando".

Dia 1Decidir

aula 1

2 exercícios

decisao.md com 3 tarefas suas e nenhum aviso.

Ver a aula
Dias 1 e 2Delegar e conferir

aulas 2, 3 e 4

2 exercícios

Subagente de leitura, fan-out com teto e laço gerador × avaliador aprovando.

Ver a aula
Dia 3Isolar

aulas 5 e 6

3 exercícios

Gravação perdida provada, worktree e sandbox por papel, fila travada com flock.

Ver a aula
Dias 4 e 5Seu time

aulas 7 e 8

2 exercícios

time.md conferido e uma rodada real com revisão cruzada reconciliada.

Ver a aula
Ao final do cursoUm time de agentes do tamanho do trabalho, escrito numa página, conferido por script e rodado uma vez de verdade.
18 exercícios
Clique num exercício para ver o que fazer e o "pronto quando".
  1. 1/5

    Decidir

    A matriz antes de qualquer agente. Se tudo der "direto", o resto do curso vira reserva para quando precisar.

  2. 2/5

    Delegar e conferir

    Requer o dia 1. Cada peça primeiro com agente falso, depois uma chamada real pequena.

  3. 3/5

    Isolar

    Requer os dias 1 e 2. Tudo sem cota: repositório descartável, codex sandbox, claude falso no PATH.

  4. 4/5

    Seu time

    Requer tudo antes. A revisão do Codex num dia; a rodada do time, no seguinte.

  5. 5/5

    O curso inteiro

    Decidir, delegar e conferir, isolar e montar o seu time. Só passe para a próxima entrega quando o "pronto quando" da anterior for verdade.

Ordem obrigatória: time sem isolamento repete a gravação perdida, e time sem avaliador volta a confiar no "pronto" do gerador.

05Gere o seu plano com datas

Escolha o início e quanto tempo você tem por semana. O plano lista os 18 exercícios na ordem.

06Teste da aula

Pergunta 1 de 4

A matriz da aula 1 deu "direto" para o seu loop. Como fica o time.md?competência

07Em três frases

Uma páginaDecisão e, por papel, nível, ferramentas, onde escreve, isolamento, entrada, retorno, verificação e teto.
Conferido por scriptCampo faltando, nível sem sentido e dois donos sem isolamento aparecem antes de rodar.
Rodado uma vezExecutor num worktree, avaliador por código, revisão cruzada reconciliada.

Continue por aqui

Aula anteriorVoltar ao início do curso