Como Domar Agentes de IA com o Kit de Ferramentas de Skills do Matt Pocock

Quando desenvolvedores começam a trabalhar de perto com Claude Code ou Codex, eles rapidamente encontram o mesmo problema. O agente concorda alegremente com a tarefa, sai para escrever código por cinco minutos e retorna com quinhentas linhas de espaguete quebrado. Parece familiar? Matt Pocock, o autor de Total TypeScript, decidiu enfrentar esse problema com disciplina de engenharia e montou um repositório de instruções práticas (skills) para agentes de IA. E o projeto vinvcn/mattpocock-skills-zh-CN adaptou todo esse kit de ferramentas para trabalhar com modelos de linguagem chineses e contextos mistos.

Não se trata de discussões abstratas sobre o futuro do desenvolvimento. É um conjunto de comandos e cenários concretos que fazem o modelo de linguagem agir como um desenvolvedor pleno ou sênior organizado, em vez de um gerador aleatório de funções.

Quatro cenários onde os agentes tipicamente falham

Matt identificou armadilhas típicas que desenvolvedores encontram ao entregar tarefas para a IA e escreveu um protocolo de trabalho separado para cada caso.

O agente faz algo completamente diferente do que foi solicitado

O problema de desenvolvimento mais comum é chamado de desalinhamento de expectativas. Uma pessoa pensa em uma arquitetura, o modelo preenche os detalhes ao seu gosto. Para fechar essa lacuna, o autor criou o comando /grill-me (e sua variante de engenharia /grill-with-docs).

Antes de tocar em qualquer código, o agente conduz uma interrogação formal. Ele faz uma série de perguntas direcionadas sobre casos extremos, estrutura de dados e requisitos de interface. O modelo não escreverá uma única linha até que a árvore de decisões convirja. Isso economiza horas de reescrever código.

O modelo desperdiça contexto com conversa desnecessária

Quando um agente entra em um projeto desconhecido, ele começa a inventar sua própria terminologia e gastar dezenas de tokens explicando coisas óbvias. A solução está em criar um documento com vocabulário de domínio unificado (no projeto é chamado de CONTEXT.md).

O comando /grill-with-docs não apenas pesquisa você, mas imediatamente registra a terminologia do projeto e decisões arquiteturais (ADRs). Uma vez que você e o agente compartilham uma linguagem comum, o diálogo diminui drasticamente, e as variáveis no código começam a ser nomeadas da mesma forma em todos os módulos.

O código gerado não executa

Quando um modelo escreve código sem feedback, ele trabalha às cegas. Ele precisa de testes. A skill /tdd força o agente a seguir estritamente o ciclo red-green-refactor. Primeiro o modelo escreve um teste de unidade falhando, então implementa exatamente o código necessário para passar no teste, e só então faz a limpeza.

Para bugs complexos existe um cenário separado /diagnosing-bugs. Ele guia o modelo através de um protocolo estrito: reproduzir o erro com um teste, reduzir a área de busca, formular uma hipótese, adicionar logging, corrigir o código e executar um teste de regressão.

A arquitetura se transforma em uma bagunça

A velocidade de geração de código alimenta o crescimento da entropia. Para evitar que o projeto se torne uma bola emaranhada de espaguete, o comando /improve-codebase-architecture é usado.

Ele escaneia o projeto, procura candidatos para módulos profundos (com interfaces públicas simples e lógica complexa oculta) e gera um relatório. Essencialmente, é uma auditoria regular de qualidade de código direto no terminal.

Por que localizar para chinês

O repositório original é escrito em inglês, mas a localização do vinvcn tem um propósito técnico interessante. Não é apenas sobre conveniência para desenvolvedores chineses.

Ao trabalhar com LLMs asiáticos como Qwen ou DeepSeek, prompts de sistema e instruções em chinês reduzem a perda de contexto. O modelo fica menos confuso com nuances de formulação. Enquanto isso, todos os identificadores, nomes de comandos, caminhos de arquivos e chaves de configuração permanecem em inglês. Nada quebra ao executar scripts.

Como funciona a arquitetura de skills

Todas as skills no repositório se encaixam em duas categorias:

1. Comandos acionados pelo usuário. Apenas humanos disparam esses manualmente via barra. Por exemplo, /ask-matt ajuda a selecionar a skill certa para a tarefa atual, /to-spec compila a discussão em um ticket e /wayfinder planeja uma funcionalidade importante várias sessões à frente.
2. Skills acionadas pelo modelo. Tanto o usuário quanto o agente podem acionar esses por conta própria quando veem uma subtarefa adequada. Isso inclui o ciclo TDD, resolução de conflitos git sem abortos forçados, code review e redação.

As skills são escritas como arquivos Markdown simples com instruções. São fáceis de ler e podem ser editados para corresponder às regras da sua equipe.

Configuração em poucos minutos

Você pode adicionar skills ao seu projeto usando o instalador skills.sh:

npx skills@latest add vinvcn/mattpocock-skills-zh-CN

O utilitário perguntará quais skills você quer copiar e em quais diretórios de agentes registrá-las. Certifique-se de selecionar /setup-matt-pocock-skills.

Após a instalação, execute a configuração inicial diretamente no diálogo do agente:

/setup-matt-pocock-skills

O agente esclarecerá onde você rastreia tarefas (GitHub Issues, Linear ou arquivos locais), quais labels você usa para triagem e qual pasta armazenar a documentação arquitetural.

Se você está trabalhando em Claude Code e não quer armazenar cópias de arquivos em cada repositório, pode conectar skills como um plugin:

claude plugin marketplace add vinvcn/mattpocock-skills-zh-CN
claude plugin install mattpocock-skills@mattpocock

Neste modo, as skills serão atualizadas centralmente quando novas versões forem lançadas.

Para quem é isso

Duas categorias de engenheiros devem olhar esse repositório.

Primeiro, aqueles que usam ativamente Claude Code, Codex ou OpenCodeInterpreter e estão cansados de lutar contra alucinações do modelo. A abordagem do Matt Pocock traz previsibilidade de volta ao desenvolvimento através de restrições estritas e ciclos de feedback curtos.

Segundo, é um excelente exemplo de como escrever instruções de sistema para assistentes de IA. Mesmo que você não precise da tradução em chinês, a estrutura de arquivos neste repositório oferece uma lição clara sobre como projetar skills para agentes. Tente incorporar um par de comandos como /grill-me no seu fluxo de trabalho diário, e você notará a diferença até o final do dia.