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
Podes criar modos personalizados para adaptar o comportamento do Bob a tarefas ou fluxos de trabalho específicos. Os modos personalizados no Bob Shell funcionam de forma semelhante aos modos do Bob IDE.
Ignorar ficheiros
Controla quais ficheiros Bob Shell pode aceder criando um ficheiro `.bobignore` no teu projeto.