Personas de agentes
Cria ficheiros de persona reutilizáveis que definem o papel, o foco e o acesso a tools de um subagent. Define o que um subagent procura, como formata os seus resultados e o que não pode fazer.
As personas de agentes são ficheiros markdown que configuram o papel e o comportamento de um subagent lançado. Enquanto um modo personalizado determina como a tarefa principal funciona, uma persona determina como um subagent auxiliar trabalha. Controla a identidade, a checklist, o formato de saída e as restrições do subagent.
Como as personas funcionam
Quando Bob lança um subagent, verifica em .bob/agents/ se existe um ficheiro de persona cuja descrição corresponde à tarefa. Se for encontrado, a persona é carregada como o modo do subagent: o corpo do papel é injetado no system prompt do subagent e sobrepõe-se às suas instruções base.
As personas não são carregadas automaticamente na conversa principal. Só têm efeito quando um subagent é lançado, seja por iniciativa própria de Bob seja quando pedes a Bob que delegue uma tarefa específica.
Formato do ficheiro de persona
Os ficheiros de persona usam front matter YAML seguido de um corpo de papel em formato livre:
---
name: code-reviewer
description: Reviews code for correctness, readability, and maintainability. Read-only.
tools:
- read
---
You are a senior software engineer conducting a structured code review.
Review each file against this checklist:
1. Correctness: logic errors, missing null checks, unhandled edge cases
2. Readability: long methods, deep nesting, unclear naming
3. Maintainability: tight coupling, missing abstraction, duplicated logic
Report findings in a table with columns: Severity, File, Lines, Description.
Use severity levels: HIGH, MEDIUM, LOW.
Do not suggest fixes. Describe issues only.Campos do front matter
| Campo | Obrigatório | Tipo | Propósito |
|---|---|---|---|
name | Sim | string | Identificador usado nos logs. Deve corresponder ao nome do ficheiro sem .md. |
description | Sim | string | Bob usa isto para associar a persona a uma tarefa. Escreve como uma declaração de missão de uma linha. |
tools | Não | list | Limita os grupos de tools que o subagent pode usar. Omite para herdar os valores predefinidos. |
Grupos de tools
O campo tools aceita os mesmos grupos que os modos personalizados: read, edit, command, browser, mcp.
Para personas de só leitura como revisores, planeadores e resumidores, define tools: [read] para evitar edições acidentais.
O campo tools é um limite máximo, não uma concessão. Definir tools: [edit] numa persona não tem efeito se a tarefa ativa não tiver permissões de edição ativadas. Uma persona só pode restringir o acesso a tools, nunca expandi-lo para além do que a tarefa permite.
Localização dos ficheiros
| Localização | Âmbito | Caso de uso |
|---|---|---|
<projeto>/.bob/agents/ | Apenas este projeto | Personas partilhadas pela equipa incluídas no repositório |
~/.bob/agents/ | Todos os projetos nesta máquina | Personas pessoais que se aplicam a todos os repositórios |
Se ambas as localizações contiverem uma persona com o mesmo nome, o ficheiro ao nível do projeto tem precedência.
O diretório .bob/ pode conter personas juntamente com o resto da tua configuração:
Criar a tua primeira persona
Cria o diretório agents na raiz do teu projeto:
mkdir -p .bob/agentsCria um ficheiro de persona. O nome do ficheiro (sem .md) deve corresponder ao campo name no front matter.
touch .bob/agents/code-reviewer.mdAdiciona o front matter e o corpo do papel. Consulta Formato do ficheiro de persona acima para a estrutura.
Faz commit do ficheiro no teu repositório para que a tua equipa partilhe as mesmas personas.
Personas de exemplo
code-reviewer.md
Analisa ficheiros fonte para verificar correção, legibilidade e manutenibilidade. Produz uma tabela de resultados ordenada por gravidade e não sugere correções.
---
name: code-reviewer
description: Reviews code for correctness, readability, and maintainability. Read-only.
tools:
- read
---
You are a senior software engineer conducting a structured code review.
Review each file against this checklist:
1. Correctness: logic errors, missing null checks, unhandled edge cases
2. Readability: long methods, deep nesting, unclear naming
3. Maintainability: tight coupling, missing abstraction, duplicated logic
Report findings in a table with columns: Severity, File, Lines, Description.
Use severity levels: HIGH, MEDIUM, LOW.
Do not suggest fixes. Describe issues only.
If a file has no findings, list it explicitly as clean.pr-summarizer.md
Lê um conjunto de ficheiros alterados e produz uma descrição estruturada de pull request que cobre o que mudou, a intenção provável e as áreas a que o revisor deve prestar atenção.
---
name: pr-summarizer
description: Reads changed files and produces a structured pull request description. Read-only.
tools:
- read
---
You are a developer writing a pull request description for a teammate.
Read the provided files and produce a PR description with these sections:
**Summary**: One or two sentences describing what this change does.
**Why**: The likely motivation, inferred from the code changes.
**What changed**: A bullet list of the key changes, grouped by area if there are several.
**Reviewer notes**: Anything the reviewer should pay particular attention to, including edge cases, intentional trade-offs, or areas of uncertainty.
Write in plain, direct language. Do not pad the description.
Do not list every file changed. Focus on what matters to the reviewer.Usar uma persona
Faz referência a uma persona pelo nome quando pedes a Bob que delegue uma tarefa:
Use the code-reviewer persona to review the files in src/auth/.Spawn a subagent using the pr-summarizer persona.
Read the changed files in this branch and produce a PR description.Bob carregará a persona correspondente de .bob/agents/ e aplicá-la-á ao subagent lançado.
Personas inline
Para uma tarefa pontual, podes descrever o papel diretamente no teu prompt sem criar um ficheiro:
Spawn an Explore subagent with this role:
You are a naming auditor. Read all files under src/ and flag variable and
function names that use abbreviations or are misleading. Return a table:
File, Line, Current Name, Issue.Os papéis inline funcionam tão bem quanto as personas baseadas em ficheiros para uma única tarefa. Os ficheiros de persona valem a pena criar quando queres reutilizar o mesmo papel em várias tarefas ou partilhá-lo com a tua equipa.
Passar o histórico de conversa
Por defeito, um subagent recebe apenas a descrição da tarefa. Não vê os turnos anteriores da conversa. Isto mantém o seu contexto pequeno e focado.
Quando um subagent precisa de respeitar decisões ou restrições anteriores da conversa, formula o teu prompt com referência ao contexto anterior:
Use the code-reviewer persona to review src/payments/.
Take into account what we discussed about the error handling approach.Bob infere fork_context: true a partir de frases como "what we discussed" ou "our earlier decision", e passa o histórico de conversa para o subagent.
Passar o histórico de conversa copia toda a tua conversa para o context window do subagent. Numa conversa longa, isso adiciona um custo significativo em tokens. Prefere o comportamento predefinido (sem contexto forkado) a menos que o subagent precise realmente do contexto anterior para fazer o seu trabalho.
Personas, modos e regras
| Mecanismo | Âmbito | O que controla | Quando usar |
|---|---|---|---|
| Modo | Tarefa inteira | Limite de tools e definição de papel para a tarefa principal | Quando o agente principal precisa de uma postura diferente, como só leitura, escritor de docs ou revisor de segurança |
| Regra | Tarefa ou modo | Instruções permanentes carregadas no system prompt | Convenções da equipa, padrões de formatação, barreiras que se aplicam em todas as situações |
| Persona | Um subagent | Papel, foco, formato de saída e restrições de tools para um subagent lançado | Quando um assistente precisa de foco no domínio: rever código, resumir alterações, planear testes |
Modos personalizados
Adapte o comportamento do Bob criando modos personalizados com funções especializadas, restrições de ferramentas e workflows de equipe. Configure globalmente ou por projeto usando o formato YAML.
Regras personalizadas
Regras personalizadas influenciam como Bob responde às suas solicitações, alinhando a saída com suas preferências específicas e requisitos do projeto. Configure regras personalizadas para controlar o estilo de codificação, a abordagem de documentação e os processos de tomada de decisão do Bob.