Guia de Iniciação às Skills do mattpocock: faça a IA aprender TDD e uma depuração estruturada

Visão geral do projeto

mattpocock/skills é um pacote de “habilidades” de metodologia de engenharia para ferramentas de programação por IA. O ponto de partida é bem simples: ferramentas de programação por IA são rápidas, mas isso não significa que sejam ferramentas de programação por IA confiáveis.

Em muitas práticas, Matt Pocock identificou quatro padrões de falha frequentes na programação com IA:

• Desalinhamento de requisitos: você acha que a IA entendeu, mas ela se desvia
• Saída excessivamente redundante: a IA usa 20 palavras para dizer algo que 1 palavra resolveria
• O código não funciona: sem ciclo de feedback, a IA escreve no escuro como uma caixa-preta
• Arquitetura que apodrece rápido: a IA acelera o desenvolvimento, mas acelera também a entropia do software

Esses quatro problemas não são bugs das ferramentas; são a ausência de metodologia. mattpocock/skills resolve isso diretamente: comprime décadas de experiência de engenharia em um conjunto de Skills combináveis, para que a IA — em qualquer modelo — siga a mesma disciplina de engenharia.

Dificuldade / Duração / Benefícios

Dificuldade: nível iniciante — não é necessário ter experiência com TDD; basta saber usar a linha de comando e uma ferramenta de programação por IA
Duração: cerca de 30 minutos para percorrer todo o fluxo
Benefícios: criar um fluxo completo de trabalho de alinhamento de requisitos → TDD → depuração estruturada → reflexão sobre arquitetura

Perfil do público-alvo

• Desenvolvedores backend / full-stack com 1–5 anos de experiência
• Já usando Claude Code, Codex ou ferramentas similares de programação por IA
• Sentem que o código gerado por IA “até funciona, mas é instável” e querem estabelecer um ritmo de desenvolvimento controlável
• Têm interesse em TDD, mas nunca encontraram uma boa porta de entrada

Dependências e ambiente

Árvore completa de estrutura do projeto

skills/
├── CLAUDE.md                          # Descrição das normas do diretório de skills
├── README.md                          # Visão geral e documentação de uso
├── skills/
│   ├── engineering/
│   │   ├── diagnose/
│   │   │   └── SKILL.md               # Fluxo de depuração estruturada
│   │   ├── grill-with-docs/
│   │   │   └── SKILL.md               # Entrevista em profundidade com base em documentação
│   │   ├── improve-codebase-architecture/
│   │   │   └── SKILL.md               # Diagnóstico de melhoria de arquitetura
│   │   ├── setup-matt-pocock-skills/
│   │   │   └── SKILL.md               # Ponto de entrada para iniciar a configuração
│   │   ├── tdd/
│   │   │   ├── SKILL.md               # Fluxo em fatias verticais para TDD
│   │   │   ├── tests.md               # Exemplos de testes bons / ruins
│     │   │   ├── mocking.md             # Boas práticas de Mock
│   │   │   ├── refactoring.md         # Decidir quando refatorar
│   │   │   ├── deep-modules.md        # Princípios de design de módulos profundos
│   │   │   └── interface-design.md    # Design de interfaces testáveis
│   │   ├── to-issues/
│   │   │   └── SKILL.md               # Quebrar requisitos em GitHub Issues
│   │   ├── to-prd/
│   │   │   └── SKILL.md               # Geração de PRD
│   │   ├── triage/
│   │   │   └── SKILL.md               # Máquina de estados para triagem de Issues
│   │   └── zoom-out/
│   │       └── SKILL.md               # Leitura de perspectiva global do código
│   ├── productivity/
│   │   ├── caveman/
│   │   │   └── SKILL.md               # Compressão de comunicação: economiza 75% de tokens
│   │   ├── grill-me/
│   │   │   └── SKILL.md               # Entrevista em profundidade sobre requisitos
│   │   └── write-a-skill/
│   │       └── SKILL.md               # Guia para escrever uma Skill personalizada
│   └── misc/
│       ├── git-guardrails-claude-code/
│       │   └── SKILL.md               # Barreiras de segurança do Git
│       └── scaffold-exercises/
│           └── SKILL.md               # Scaffold do diretório de exercícios
└── .claude-plugin/
    └── plugin.json                    # Metadados do plugin

Passo a passo

Passo 1: instalar as mattpocock Skills

Em qualquer ferramenta de programação por IA que suporte Skills, execute o comando abaixo para concluir a instalação:

npx skills@latest add mattpocock/skills

O script de instalação vai guiá-lo para escolher quais Skills ativar e a quais ferramentas de IA essas Skills estarão vinculadas. Etapa-chave: confirme a seleção de /setup-matt-pocock-skills, que é o ponto de entrada para inicializar todas as Skills que vêm depois.

Passo 2: inicializar a configuração

Após a instalação, execute no seu ambiente de programação por IA:

/setup-matt-pocock-skills

Essa Skill vai perguntar, em sequência:

1. Issue Tracker: escolha qual ferramenta você usa para gerenciar Issues (GitHub / Linear / arquivo local)
2. Rótulos (Triage Labels): quais termos usar ao etiquetar uma Issue (a Skill /triage será usada)
3. Caminho de salvamento de documentos: onde salvar os ADRs e os documentos gerados

Ao finalizar, será criado um CONTEXT.md na raiz do projeto, como um “dicionário de linguagem compartilhada” entre a IA e você. Esse arquivo é extremamente importante: ele padroniza como os termos são usados no projeto; a partir dele, todas as nomenclaturas e anotações serão baseadas nele.

Passo 3: alinhar requisitos com /grill-me

Quando você tiver um novo requisito ou proposta de design para entregar à IA, não saia implementando direto. Primeiro execute:

/grill-me

A IA vai fazer perguntas uma por uma, esmiuçando cada ramificação da árvore de decisões. Por exemplo, se você planeja “adicionar a funcionalidade de reembolso ao módulo de pagamentos”, a IA vai aprofundar:

• O reembolso é total ou parcial?
• Quais são as condições para disparar o reembolso (o usuário solicita / o risco ativa automaticamente / o suporte manualmente)?
• Como tratar o estoque após o reembolso?
• O registro de reembolsos deve ser persistido?

Cada pergunta vem acompanhada de uma recomendação de resposta; você só precisa confirmar ou corrigir. Esse processo funciona como uma entrevista estruturada: garante que a IA realmente entenda o que você quer fazer, em vez de se desviar pelo sentido literal.

Passo 4: usar /tdd para testes em fatias verticais

Depois do alinhamento de requisitos, chegamos à fase de desenvolvimento. Aqui está a parte mais central do mattpocock/skills — é proibido fazer fatias horizontais.

O que é fatia horizontal? Primeiro escrever todos os testes, depois escrever todo o código. É uma das principais armadilhas do TDD mal interpretado; a IA é especialmente propensa a fazer isso e, como resultado, os testes “testam comportamentos imaginados”, e não os comportamentos reais.

A abordagem correta é: fazer apenas uma fatia vertical de cada vez.

RED:   Escreva um teste, descrevendo o primeiro comportamento → o teste falha
GREEN: Escreva o código mínimo para passar no teste → o teste passa
REFACTOR: refatorar (opcional)

Repita esse ciclo. Depois que a IA escreve um teste, ela já “viu” aquela implementação; portanto, o que ela testa são comportamentos reais, não os previstos.

Vamos ver um exemplo concreto: suponha que precisamos implementar uma funcionalidade de checkout no carrinho.

// Primeira rodada: só testar “o carrinho consegue adicionar itens”
import { describe, it, expect } from 'vitest';
import { Cart } from './cart';

describe('Cart', () => {
  it('allows adding an item', () => {
    const cart = new Cart();
    cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
    expect(cart.items).toHaveLength(1);
  });
});

// cart.ts — implementação mínima para passar no teste
export interface CartItem {
  id: string;
  name: string;
  price: number;
}

export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }
}

// Segunda rodada: testar “o carrinho consegue calcular o preço total”
it('calculates total price', () => {
  const cart = new Cart();
  cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
  cart.addItem({ id: 'book-2', name: 'React 实战', price: 79 });
  expect(cart.totalPrice()).toBe(138);
});

// cart.ts — adicionar o método totalPrice
export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }

  totalPrice(): number {
    return this.items.reduce((sum, item) => sum + item.price, 0);
  }
}

Cada rodada é: teste falha → código mínimo passa → próxima rodada. Esse é o ritmo central das fatias verticais.

Passo 5: usar /diagnose para depuração estruturada

Quando o código der problema, não peça à IA “me ajude a corrigir um bug” diretamente. Primeiro, estabeleça um ciclo de feedback executando:

/diagnose

O /diagnose força a IA a seguir o ciclo de depuração de seis fases:

Por que esse fluxo é importante? Porque a forma mais comum que a IA “faz depuração” é: “tentar corrigir chutando, checar o resultado; se não der, chutar de novo”. Sem ciclo de feedback, isso equivale a jogar dardos no escuro. O /diagnose transforma a depuração em uma disciplina de engenharia, não em algo místico.

Um cenário típico — suponha que sua API de pagamentos comece a retornar erro 500 de repente:

// Fase 1: construir um ciclo de feedback — escrever um teste que localiza a falha na API
import { describe, it, expect } from 'vitest';
import { createHonoServer } from './server';
import fetch from 'node-fetch';

describe('Payment API', () => {
  it('returns 200 for valid checkout', async () => {
    const app = createHonoServer();
    const response = await fetch('http://localhost:3000/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ id: 'book-1', quantity: 1 }],
        userId: 'user-123',
      }),
    });
    expect(response.status).toBe(200); // atualmente falha; na prática retorna 500
  });
});

A fase 3 vai gerar uma lista de hipóteses:

1. Se for “timeout do serviço de estoque causando exceção não tratada”, então fazer mock do serviço de estoque retornando sucesso elimina o 500
2. Se for “transação do banco não commitada”, então checar se o transaction.commit() foi chamado identifica o problema
3. Se for “erro ao analisar o formato da resposta do gateway de pagamento”, então validar o mock dos dados do gateway reproduz o problema

A IA valida uma hipótese por vez, em vez de empilhar todas as mudanças juntas.

Passo 6: usar /write-a-skill para criar uma Skill personalizada

Quando você acumula um conjunto de fluxos de trabalho próprios em um projeto, pode empacotá-los como uma Skill para que a IA chame quando precisar nesse projeto:

/write-a-skill

A IA vai perguntar, em sequência:

1. Este Skill cobre qual domínio?
2. Quais são os cenários de uso específicos?
3. Precisa incluir scripts ou apenas instruções?
4. Há algum material de referência?

Depois, gera a estrutura padrão:

my-custom-skill/
├── SKILL.md              # Arquivo principal de instruções (obrigatório)
├── REFERENCE.md          # Documentação detalhada (se passar de 100 linhas, dividir)
├── EXAMPLES.md           # Exemplos de uso
└── scripts/
    └── helper.ts         # Script de ferramenta (opcional)

O campo de description de SKILL.md é a única porta de entrada que a IA tem para perceber essa Skill; a formatação tem requisitos estritos:

---
name: my-custom-skill
description: Gere clientes de API com tipos seguros a partir de um JSON Schema e injete dados de Mock.
              Use when user mentions "API client", "generate types", or "mock data".
---

A primeira frase do description diz “o que faz”; a segunda frase diz “em que cenário deve ser acionado”, usando palavras de gatilho para guiar a IA a carregar automaticamente.

Solução de problemas comuns

1. A IA não executa testes e já sai escrevendo código

Efeito: você chama /tdd, mas a IA pula direto para a implementação, pulando a fase RED.

Diagnóstico:

• Confirme que CONTEXT.md já definiu o framework de testes do projeto e as convenções de teste
• Ao iniciar o /tdd, deixe claro: “escreva apenas um teste; não escreva nenhum outro código”
• Se a IA ainda pular, digite manualmente na conversa “primeiro escreva um teste falho” para trazê-la de volta para o RED

Causa raiz: entendimento literal da IA do conceito de TDD — ela interpreta “escreveu testes” como se fosse TDD, sem entender que “testes falhos” em si é um sinal.

---

2. Armadilha de fatia horizontal — escrever todos os testes de uma vez

Efeito: a IA gera de uma vez 10 arquivos de testes no /tdd e, depois, escreve de uma vez toda a implementação.

Diagnóstico:

• Intervenção direta: diga à IA “escreva apenas o primeiro teste e implemente-o”
• Adicione um aviso de antipadrão em CONTEXT.md: “proibido fazer fatias horizontais; faça apenas uma fatia vertical por vez”

Causa raiz: a IA gosta da ilusão de “resolver tudo de uma vez”; fatias horizontais fazem parecer que está completo, mas a entrega fica frágil.

---

3. Ciclo de depuração sem sinal de feedback

Efeito: você chama /diagnose, mas a IA apenas fica alterando código repetidamente, sem criar um sinal de falha reprodutível.

Diagnóstico:

• Se a Fase 1 não passar, não avance para a Fase 2. Diga explicitamente à IA: “ainda não há um sinal reprodutível de falha; continue construindo o ciclo de feedback”
• Tente construir um sinal ponta a ponta com node-fetch + requests HTTP reais, em vez de mockar todo o módulo

Causa raiz: o ciclo de feedback é a essência da depuração; sem ele, todas as ações seguintes viram movimentos no escuro.

---

4. Descrição da Skill falha — a Skill não é disparada automaticamente

Efeito: você escreveu uma Skill personalizada, mas a IA não a carrega.

Diagnóstico:

• Verifique se a Skill foi registrada no plugin.json
• Confirme que a description inclui palavras de gatilho (termos que o usuário realmente diria)
• Confirme que o name e description do SKILL.md seguem o formato exigido (YAML frontmatter)

Causa raiz: o carregamento de Skills depende da correspondência de palavras-chave na description; se a descrição não for precisa, não dispara.

---

5. A entrevista do /grill-me vira um reporte unilateral

Efeito: quando executa /grill-me, a IA só recebe as suas informações, sem perguntar ativamente.

Diagnóstico:

• Só quando a IA estiver perguntando é que ela explica que entrou no modo de entrevista — continue respondendo, não interrompa
• Se a IA ficar em silêncio por mais de 3 rodadas, diga manualmente: “continue perguntando, tenho mais informações”
• A causa geralmente é que a IA acha que “entendeu”, mas na prática só entendeu literalmente

Causa raiz: a IA tende a convergir rapidamente para um estado de “parece que entendeu”, em vez de enumerar todas as ramificações.

---

6. CONTEXT.md grande demais causa explosão de tokens

Efeito: conforme o projeto avança, o CONTEXT.md fica cada vez maior; a IA começa a apresentar estouro de contexto ou respostas mais lentas.

Diagnóstico:

• Reestruture periodicamente o CONTEXT.md: mantenha “termos gerais já estáveis” e mova “registros temporários de decisão” para o diretório docs/adr/
• /improve-codebase-architecture pode ajudar a identificar o que deve ser extraído do CONTEXT.md

Causa raiz: o CONTEXT.md cresce dinamicamente; sem manutenção, vira um segundo monorepo.

Leitura complementar / Direções avançadas

Extensão de metodologia: Matt Pocock é um defensor de type gymnastics em TypeScript; o curso Total TypeScript dele é uma excelente complementação para entender desenvolvimento orientado a tipos.

De TDD à melhoria de arquitetura: depois que sua base de código passa por algumas rodadas de refatoração com TDD, você pode usar /improve-codebase-architecture para fazer um diagnóstico de arquitetura. Ele usa a linguagem de domínio do CONTEXT.md e os registros de decisão em docs/adr/ para identificar “módulos rasos” (interfaces complexas, mas poucas funcionalidades) e oportunidades de refatoração.

Ecossistema de Skills personalizadas: a filosofia de design de mattpocock/skills é “pequenas e combináveis”. Você não precisa instalar todas as Skills que ele oferece — pode instalar apenas /tdd e /diagnose, introduzindo gradualmente no desenvolvimento diário. Na comunidade, existem outros desenvolvedores que construíram conjuntos de Skills com base nesse framework; vale a pena acompanhar.