Agentes Personalizados

Problema: O comportamento padrão do Claude Code não corresponde à forma como a tua equipa trabalha de verdade. Talvez queiras um revisor que conheça o estilo da casa. Ou um especialista de deploy ligado à tua infraestrutura.

Ganho Rápido: Criar o teu primeiro slash command demora menos de dois minutos. Começa assim:

mkdir -p .claude/commands

Depois cria .claude/commands/code-review.md:

Review the recent code changes for quality and security:
 
1. Run git diff to see recent changes
2. Focus on modified files only
 
Review checklist:
 
- Code is readable and well-named
- No duplicated logic
- Proper error handling exists
- No exposed secrets or credentials
- Performance considerations addressed
 
Provide feedback by priority: Critical → Warnings → Suggestions

Depois invoca-o com /project:code-review dentro do Claude Code.

Como os Comandos Personalizados Mudam o Teu Workflow

Para entender: Um slash command personalizado é um prompt guardado e reutilizável. Chamas-o, Claude lê as instruções dentro, e o teu especialista está a trabalhar. Consultores especialistas a um keystroke de distância.

Também resolvem o problema de "qual era aquele prompt". Em vez de reescrever instruções longas em cada sessão, guardas-as num ficheiro. O ficheiro carrega a expertise acumulada da tua equipa.

Três formas de criar um agente personalizado:

1. Slash Commands (.claude/commands/): Executas manualmente com /project:command-name
2. Definições de Agente (.claude/agents/): Papéis de sub-agente definidos em YAML que ficam disponíveis e criam-se sozinhos durante a orquestração
3. Instruções CLAUDE.md: Comportamentos sempre ativos que moldam cada turno da conversa

Commands vs. Agents: Os dois resolvem trabalhos diferentes. Um slash command é um prompt guardado que executas a pedido para um workflow conhecido. Uma entrada em .claude/agents/ cria um sub-agente persistente que a ferramenta Task pode invocar sozinha. Commands parecem ferramentas numa bancada. Ficheiros de agente parecem colegas que já estão a trabalhar.

Ambos partilham o mesmo modelo de scoping:

Tudo no caminho do projeto é commitado no git e partilhado com toda a equipa. O caminho do utilizador fica no teu computador e segue-te de repositório em repositório.

Separação de Responsabilidades: O mesmo princípio que faz módulos pequenos baterem os grandes aplica-se aos prompts. Um command centrado numa única checklist de segurança apanha mais problemas do que um "revê este código" genérico alguma vez apanhará.

Criar Comandos Personalizados Eficazes

Começa simples: Encontra o único problema que continua a aparecer na tua vida. Escreve o command para isso.

Cria .claude/commands/security-audit.md:

You are a security expert. Scan this codebase for vulnerabilities.
 
Check for:
 
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication bypass issues
- Exposed API keys or secrets
- OWASP Top 10 violations
 
For each finding, provide:
 
1. Vulnerability description
2. Risk level (Critical/High/Medium/Low)
3. Specific fix recommendation
4. Code example of the fix
 
Start by searching for common vulnerability patterns in the codebase.

Corre /project:security-audit sempre que quiseres um scan de segurança.

Argumentos Dinâmicos: Um command pode ler argumentos através de $ARGUMENTS:

Cria .claude/commands/review-file.md:

Review this specific file for issues: $ARGUMENTS
 
Focus on: code quality, potential bugs, security concerns.

Invoca com /project:review-file src/auth/login.ts.

CLAUDE.md: Comportamento de Agente Sempre Ativo

Para regras que queres ativas em cada sessão, coloca-as no CLAUDE.md do teu projeto:

## Code Review Standards
 
When reviewing code, always check:
 
- All functions have error handling
- No console.log statements in production code
- API endpoints validate input parameters
- Database queries use parameterized statements
 
## Commit Message Format
 
Use conventional commits: type(scope): description
Types: feat, fix, docs, refactor, test, chore

Nada a invocar. Claude carrega o CLAUDE.md quando a sessão começa e aplica as regras a cada turno seguinte.

Commands de Projeto vs. de Utilizador:

• .claude/commands/ - Commitado no git para toda a equipa
• ~/.claude/commands/ - Privado apenas para a tua máquina

Definições Persistentes de Sub-Agente com .claude/agents/

Sub-agentes que o orchestrator deve criar sozinho vivem em .claude/agents/. Cada ficheiro é Markdown com um bloco YAML no topo. Identidade, capacidades e instruções ficam todas nesse bloco.

Ao contrário de um slash command que espera um keystroke, estas definições ficam em standby. A ferramenta Task vê-as durante a orquestração. No momento em que Claude decide que uma tarefa quer um especialista, cria o certo com o seu contexto e restrições já configurados.

Sintaxe do YAML Frontmatter

Cada ficheiro em .claude/agents/ começa com um cabeçalho YAML que diz ao Claude como o agente deve comportar-se. A referência de campos:

---
# Required
name: "security-auditor" # Agent identity (used in Task invocations)
 
# Optional
model: "claude-sonnet-4-5" # Override the default model
allowedTools: # Restrict which tools this agent can use
  - Read
  - Grep
  - Bash
description: "Scans code for vulnerabilities and OWASP violations"
---

Tudo abaixo do bloco YAML é Markdown simples, contendo o system prompt com que o agente corre. Estruturalmente, parece-se com um slash command. A diferença real é que o orchestrator consegue ver este ficheiro sozinho e criar o agente sem qualquer invocação manual.

Um Exemplo Da Prática

Aqui está um agente concreto, construído em torno de quality gates pré-commit. O ficheiro vai em .claude/agents/quality-engineer:

---
name: "quality-engineer"
allowedTools: ["Read", "Grep", "Bash"]
description: "Validates code against project standards before commits"
---
 
You are a quality engineer. Your job is to validate, never to modify.
 
## Validation Protocol
 
1. Read the files that changed (use git diff --name-only)
2. For each file, check:
   - Imports resolve correctly (grep for the import targets)
   - No console.log/print statements left in production code
   - Functions under 50 lines
   - All exported functions have JSDoc or docstring
3. Run the test suite: `npm test -- --bail`
4. Report pass/fail with specific line numbers for failures
 
Never edit files. Never suggest fixes. Only report what you find.

Quando o orchestrator deteta uma tarefa de validação, esta definição é usada automaticamente. Como allowedTools exclui Edit e Write, o agente fisicamente não consegue tocar na tua codebase. Inspeção é o único movimento que tem. Esse limite é a razão inteira pela qual o padrão se mantém.

Ficheiros nesta pasta também carregam o teu CLAUDE.md no arranque, por isso as convenções do projeto e os padrões de código chegam sem nenhuma ligação extra.

Para mais sobre como os sub-agentes se comportam, incluindo execuções paralelas, background via Ctrl+B e qualidade de invocação, o guia de fundamentos de agentes vai mais fundo.

Exemplos Comuns de Commands

Otimizador de Base de Dados (.claude/commands/db-optimize.md):

You are a database performance expert.
 
Analyze the database queries in this codebase:
 
1. Find slow or inefficient queries
2. Check for missing indexes
3. Review schema design
 
For each issue, provide:
 
- The problematic query or schema
- Why it's a problem
- Optimized version with explanation

Escritor de Documentação (.claude/commands/write-docs.md):

Write documentation for: $ARGUMENTS
 
Include:
 
- Purpose and overview
- Setup instructions
- Usage examples
- Common troubleshooting
 
Target audience: developers new to this project.
Write in clear, concise language.

Erros Comuns ao Construir Agentes Personalizados

À superfície, um agente personalizado parece nada. Define o scope mal e o custo são tokens desperdiçados e resultados inconsistentes.

Erro 1: Scope demasiado amplo. Um agente instruído a varrer "esta codebase para todos os problemas" devolve observações superficiais espalhadas por tudo ao mesmo tempo. Aponta esse mesmo agente para SQL injection, restringe-o a ficheiros relacionados com base de dados, e vai expor bugs reais. Aperta o scope. Aprofunda a análise.

Erro 2: Formato de output solto. Deixa a forma do relatório em aberto e ele deriva de execução para execução. Uma passagem dá-te bullets. A seguinte dá prosa. Define-o claramente com algo inequívoco como: For each finding, provide: file path, line number, severity, and a one-line fix.

Erro 3: Acesso de escrita num revisor. Quando o trabalho do agente é inspeção, fixa o seu allowedTools em Read, Grep e Bash. No segundo em que dás a um revisor Edit, ele deriva para corrigir código em vez de reportar sobre ele. Isso apaga a razão pela qual o validator era separado.

Erro 4: Repetir regras do CLAUDE.md dentro dos commands. O CLAUDE.md já foi carregado quando um command corre. Reiterar essas regras em cada ficheiro de command apenas consome tokens de contexto. Um command deve estreitar o comportamento, não reiterar a base universal. Se "usar queries parametrizadas" está no CLAUDE.md, o teu command de base de dados não precisa dessa linha também.

Quando Usar Cada Abordagem

Escolher entre slash commands, ficheiros de agente, skills e CLAUDE.md resume-se a duas coisas. O que despoleta o comportamento e quanto tempo deve durar.

A linha prática é esta. Qualquer prompt detalhado que escreveste três vezes merece ser guardado como slash command. Qualquer especialista que o orchestrator deve invocar sozinho pertence a .claude/agents/. Tudo o resto vai para CLAUDE.md como comportamento universal, ou numa skill para conhecimento de domínio que carrega de forma lazy. O guia de skills cobre essa última via por completo.

Prompting para Papéis Especializados

Nem sempre precisas de um ficheiro guardado. Às vezes um prompt direto chega:

Act as a senior security engineer. Review the authentication
flow in src/auth/ for vulnerabilities. Be thorough and paranoid.

Suficiente para uma tarefa pontual. No momento em que notas que o escreveste duas vezes, eleva-o para um command guardado.

Próximas Ações

Altura de construir o teu primeiro especialista. Escolhe o ponto de dor mais ruidoso hoje:

• Qualidade de Código: Transforma as tuas regras internas num command de revisão, baseado no guia de fundamentos de agentes
• Foco em Segurança: Escreve um scanner de vulnerabilidades baseado nas notas de design de sub-agentes
• Workflow de Equipa: Define um padrão de colaboração usando o playbook de distribuição de tarefas

Commands guardados acumulam valor quanto mais tempo vives com eles. Faz push para o repositório. Passa-os à equipa. Cria uma biblioteca que capture a forma como o teu grupo realmente entrega código.