Papéis

Para que serve

Um papel descreve uma responsabilidade: analisar, implementar, revisar, verificar. Ele não depende da ferramenta. O tipo de CLI (Claude Code, Codex, Gemini) diz como o agente é iniciado; o papel diz o que ele deve fazer naquela etapa. "Revisor" não instala agente nenhum, e "Codex" não diz qual é a responsabilidade dele. Quando uma etapa tem papel, o PrumoGrid prepara um arquivo com a descrição do papel e as regras que valem só para ele, e a instrução entregue ao agente começa com "Seu papel nesta etapa é: …", pedindo que ele leia esse arquivo antes de executar. Assim a instrução da etapa fica curta, porque o resto já está no papel.

Quando usar e quando não usar

Use um papel quando o mesmo tipo de trabalho se repete com as mesmas orientações. Uma revisão que sempre grava os achados em REVISAO.md, uma análise de segurança que nunca altera código, uma correção que sempre vem com teste. Também ajuda a ler um fluxo de várias etapas: os cartões mostram "Claude Code · analista", "Codex CLI · implementador", "Claude Code · revisor", e você entende a sequência sem abrir cada instrução.

Não crie um papel para uma tarefa que só vai acontecer uma vez; escreva o pedido na própria etapa. Também não conte com o papel para coisas que ele não faz:

• Ele não escolhe o terminal de outro agente. Para devolver os achados do revisor ao implementador, crie a etapa seguinte e, em Onde esta etapa roda, escolha No terminal: com o nome do terminal dele (só aparecem terminais vivos do projeto). Peça ao revisor um arquivo, como REVISAO.md, e mande o implementador ler esse arquivo: a conversa de um agente não passa para o outro.
• Ser revisor não liga a aprovação humana. Quem faz a etapa esperar por você é a condição Com sua aprovação.
• Ter um papel não comprova que o agente seguiu as orientações. Para conferir, use uma verificação.

Os quatro papéis de fábrica

O PrumoGrid já vem com quatro papéis. Eles aparecem em Ferramentas → Regras e papéis…, na seção Definir papéis, e podem ser editados.

Passo a passo

O exemplo cria um papel seguranca para a loja-api. Ele procura segredos no código e entradas sem validação, anota os achados num arquivo e não mexe no código.

Criar o papel

1. Abra Ferramentas → Regras e papéis… e clique em Definir papéis. A lista mostra os quatro papéis de fábrica.
2. Clique em + Novo papel.
3. Em nome do papel, escreva seguranca. Prefira nomes curtos, em minúsculas e sem acento: é assim que o papel aparece nas regras e no arquivo do agente.
4. Em descrição, escreva o que se espera de quem ocupa o papel, por exemplo: Procura segredos no código e entradas sem validação. Relata em SEGURANCA.md e não altera código.
5. Clique em Criar papel. O aviso diz Papel "seguranca" criado. e o papel entra na lista.

Dar ao papel uma regra só dele

1. No papel seguranca, clique em Regra deste papel. Abre a tela de nova regra já valendo só para quem estiver nesse papel.
2. Escreva a orientação, por exemplo Cite arquivo e linha em cada achado.
3. Clique em Salvar e entregar. A regra aparece com a linha vale só para quem estiver no papel seguranca, seguida de onde ela mora (só nesta máquina ou no repositório).

Usar o papel numa etapa

1. Feche a tela de regras e clique em Nova etapa, o botão laranja do topo.
2. Em O que precisa ser feito?, escreva só o pedido: Analise a pasta src com o seu papel.
3. Em Executa, escolha Claude Code.
4. Abra Mais opções e, em Papel (regras), escolha seguranca. O resumo da seção passa a dizer papel: seguranca · pronta quando o agente avisar, e a linha O agente vai ler: mostra o que será entregue.
5. Clique em Criar etapa. Se for a primeira etapa do projeto, o PrumoGrid pergunta antes de gravar o CLAUDE.md (veja Gravação nos projetos).
6. Quando o agente terminar, rode no PowerShell do projeto:

git status --short

O esperado é ?? SEGURANCA.md, além dos arquivos que o próprio PrumoGrid grava (CLAUDE.md e .terminal-grid/), e nada dentro de src. Abra o SEGURANCA.md e confira se cada achado traz arquivo e linha, como a regra do papel pede.

O que aparece na tela

Ampliar captura ↗

Cada papel da lista tem Editar, Regra deste papel e Excluir. Na Nova etapa, Sem papel adicional entrega só as regras do projeto. No Fluxo, o cartão da etapa mostra o agente e o papel, como Claude Code · analista.

Papéis no Fluxo

No fim da cadeia do Fluxo aparece um botão para cada papel, além de Configurar papéis…. Clicar em um deles, por exemplo implementador, abre a Nova etapa já com esse papel e encadeada depois da última etapa, como planejada. Você escreve a instrução e cria a etapa.

Para trocar o papel de uma etapa que já existe, use Outras ações → Papel e sequência no cartão. Ali você muda o papel, a Posição no projeto e a marcação Esta etapa é o final do fluxo, e confirma em Salvar alterações. O terminal continua aberto e o agente não reinicia. Uma etapa que já começou continua no terminal em que foi entregue; mudar o papel dela não transfere o trabalho. Etapas de rotina ou de grupos paralelos são reordenadas no editor completo do Fluxo.

Pasta de skills

Ao editar um papel, o campo Pasta de skills (opcional) aceita um caminho relativo ao projeto ou absoluto. O agente recebe a orientação de ler os SKILL.md dessa pasta antes de começar. O PrumoGrid não comprova que as skills foram carregadas; se isso importa, peça na instrução que o agente diga quais leu.

Dicas

• Escreva descrições curtas, com o que o papel faz e o que ele não faz ("não altera código"). A tarefa de cada vez fica na etapa.
• Peça a cada papel um arquivo de saída com nome fixo (ANALISE.md, REVISAO.md, SEGURANCA.md). Fica fácil para a etapa seguinte ler e para você conferir no git status.
• Para orientações que valem para todos os agentes do projeto, use uma regra do projeto em Regras. Deixe para o papel só o que é específico dele.

Limites conhecidos

• Até 32 papéis por perfil. O nome tem até 48 caracteres e a descrição, até 200.
• Os papéis ficam no perfil desta máquina e valem para todos os projetos. A regra de um papel pode ficar no repositório ou só nesta máquina, e a tela mostra qual.
• O registro precisa de pelo menos um papel: o último não pode ser excluído, só editado.
• Excluir um papel não apaga as etapas que o citam; elas mostram o identificador antigo até serem editadas.
• Os campos de tipo de CLI preferido, memória e CPU sugeridas do papel são só sugestões. Cadastrar o papel não aplica limite nenhum.