Personalizando agentes

Agentes de programação são extremamente inteligentes mesmo sem personalização. Eles têm grande domínio de práticas consolidadas de engenharia de software e geralmente tomam decisões corretas.

No entanto, eles não sabem como sua equipe prefere desenvolver software, quais ferramentas vocês preferem ou o contexto do seu negócio. É aí que entra a personalização. Você pode modificar os agentes para torná-los mais eficazes e gerar resultados de maior qualidade.

O Cherri Code oferece duas camadas de personalização que refletem a forma como você integraria um novo colega à equipe: regras para o que eles devem sempre saber e Skills para conhecimentos especializados que podem acessar quando relevante.

Regras: contexto estático

As regras são arquivos Markdown armazenados em .cursor/rules/ que o agente vê no início de cada conversa. Você pode considerá-las instruções sempre incluídas que orientam como o agente trabalha com seu código.

Um bom arquivo de regras é curto, específico e aponta para exemplos em vez de copiá-los:

# Comandos- `npm run build`: Compilar o projeto- `npm run typecheck`: Executar o verificador de tipos- `npm run test`: Executar testes (prefira arquivos de teste únicos para mais rapidez)# Estilo de código- Use módulos ES (import/export), não CommonJS (require)- Desestruture imports: `import { foo } from 'bar'`- Veja `components/Button.tsx` para a estrutura canônica de componente# Fluxo de trabalho- Sempre execute o verificador de tipos após fazer uma série de alterações no código- Rotas de API ficam em `app/api/` seguindo os padrões existentes

As regras são mais úteis para:

• Comandos de build e teste que o agente deve conhecer
• Convenções de código que o agente deve seguir
• Referências a exemplos oficiais na sua base de código
• Restrições de segurança (arquivos que não devem ser modificados, padrões a evitar)

O que evitar em regras

• Não copie guias de estilo inteiros. Use um linter. As regras devem complementar suas ferramentas, não substituí-las.
• Não documente todos os comandos. O agente já conhece ferramentas comuns. Adicione apenas comandos específicos do projeto.
• Comece pelo básico. As regras são incluídas em todas as conversas, então podem se acumular. Adicione regras apenas quando perceber que o agente comete o mesmo erro repetidamente e mantenha-as curtas.

Versione as regras no git para que toda a equipe possa se beneficiar do conhecimento compartilhado.

Skills: contexto dinâmico

As Skills ampliam o que seus agentes podem fazer com conhecimento especializado e fluxos de trabalho. Ao contrário das regras, as skills são carregadas dinamicamente. O agente decide quando usá-las com base na tarefa em questão.

As skills são definidas em um arquivo SKILL.md e podem incluir conhecimento de domínio, fluxos de trabalho personalizados, além de scripts e código que o agente pode executar.

---description: Fazer deploy em staging. Use quando o usuário pedir para fazer deploy, publicar ou dar push para staging.---# Fazer deploy em staging## Passos1. Execute `npm run build` e confirme que foi concluído com sucesso2. Execute `npm run test` e confirme que todos os testes passaram3. Execute `npm run deploy:staging`4. Verifique o deploy acessando https://staging.example.com/health5. Relate o status do deploy e a URL

A principal diferença entre regras e skills:

MCP: conexão com ferramentas externas

O MCP (Model Context Protocol) permite que o agente se conecte a ferramentas externas e acesse contexto relevante. Os servidores MCP expõem esse contexto e ações que o agente pode usar sob demanda.

Por exemplo, você pode conectar o agente a:

• Slack para ler mensagens e publicar atualizações
• Datadog para investigar logs de produção
• Sentry para consultar detalhes de erros e rastreamentos de pilha
• Bancos de dados para consultar dados diretamente
• Figma para obter tokens de design e especificações de componentes

Navegue pelo Marketplace para encontrar servidores para as ferramentas que você usa.

Ferramentas de CLI como recursos do agente

Além do MCP, o agente pode executar qualquer ferramenta de CLI instalada no seu terminal. Ferramentas como gh, aws, kubectl e docker funcionam sem configuração adicional. O agente pode executá-las diretamente.

Indique ao agente ferramentas úteis por meio de uma regra:

- Use `gh` para todas as operações no GitHub (issues, PRs, verificações de CI)- Use `aws s3` para operações de armazenamento de arquivos

Isso também é útil para depuração. Em vez de abrir o navegador para verificar o status da CI ou consultar uma issue, você pode pedir ao agente: "Verifique por que a CI falhou neste PR usando gh." Ele executa os comandos, lê a saída e toma as medidas necessárias com base nela.

Salvando fluxos de trabalho reutilizáveis

Você também pode invocar skills sob demanda usando / na entrada do agente. Isso transforma as skills em fluxos de trabalho reutilizáveis que podem ser acionados pelo nome, ideais para tarefas executadas várias vezes ao dia.

Por exemplo, uma skill /pr que faz commit, push e abre um pull request:

---description: Create a pull request for the current changes.---1. Look at the staged and unstaged changes with `git diff`2. Write a clear commit message based on what changed3. Commit and push to the current branch4. Use `gh pr create` to open a pull request with title/description5. Return the PR URL when done

Outros fluxos de trabalho que funcionam bem como skills:

• /fix-issue [number]: Consulte os detalhes da issue com gh issue view, encontre o código relevante, corrija o bug e abra uma PR
• /review: Execute os linters, verifique problemas comuns e resuma o que precisa de atenção
• /update-deps: Verifique dependências desatualizadas e atualize-as uma a uma, executando os testes após cada atualização

Adicione-as ao git para que toda a equipe possa executá-las.

Antes e depois

Veja como a personalização funciona na prática. Considere uma equipe que usa Next.js, Tailwind e Vitest:

Antes das regras: o agente usa jest para testes (por ser mais comum nos dados de treinamento), cria componentes com módulos CSS e coloca rotas de API em locais aleatórios.

Depois de adicionar três regras:

- Os testes usam Vitest, não Jest. Consulte `src/__tests__/example.test.ts` como referência de padrão.- Use classes utilitárias do Tailwind para estilização. Não use CSS modules nem styled-components.- As rotas de API ficam em `app/api/[resource]/route.ts`, seguindo os padrões existentes.

Agora, o agente segue automaticamente as convenções da equipe. Chega de corrigir os mesmos erros em todas as conversas.

Padrão comum de falha: regras excessivamente complexas

Pode ser tentador criar regras para tudo. Resista a essa tentação. Regras demais consomem contexto desnecessariamente e podem confundir o agente.

Mantenha suas regras simples e de alta qualidade. Elas devem ser um artefato compartilhado que sua equipe atualiza constantemente. Se você precisa de algo apenas ocasionalmente, coloque isso em uma habilidade.

O que vem a seguir

Você personalizou seu agente para seguir os padrões da sua equipe. No capítulo final, reunirá tudo em um exemplo completo que aplica tudo o que aprendeu neste curso.