Claude Code Skills: crie seus próprios fluxos de trabalho com IA · Lição 5 de 6

Lição 5: Estudo de caso: construindo uma Skill de code review

Objetivos de aprendizado:

Aprender a organizar um fluxo de trabalho com múltiplos passos

Entender como o padrão de checklist se aplica

Ganhar confiança no uso de arquivos de apoio

Construir uma Skill complexa pronta para uso real

Pré-requisitos: << Lição 4 | Próxima: Lição 6 >>

Por que code review é um bom estudo de caso

Code review é um fluxo de trabalho estruturado de manual:¹

Os passos são fixos: checar convenções, procurar problemas, propor mudanças
Os critérios são mensuráveis: cada item de checagem passa ou não passa
Repete o tempo todo: todo PR precisa de um
Combina com uma Skill: escreva os critérios de revisão do seu time em uma Skill e toda revisão mantém o mesmo padrão

Este estudo de caso mostra:

Como quebrar um fluxo de trabalho complexo em passos claros
Como organizar instruções em torno de um checklist
Como lidar com várias dimensões de saída ao mesmo tempo

Passo 1: defina o escopo da revisão

Antes de escrever qualquer coisa, decida o que essa Skill fica responsável por checar.

Nossa Skill de code review cobre três dimensões:

Convenções: nomenclatura, formatação, comentários
Problemas potenciais: tratamento de erros, casos-limite, risco de segurança
Manutenibilidade: código duplicado, tamanho das funções, complexidade lógica

O que ela deliberadamente não checa:

Se a lógica de negócio está de fato correta (isso exige conhecimento real dos requisitos)
Eficiência algorítmica (isso exige teste de performance)
Design de UI/UX (fora do escopo de code review)

Passo 2: crie a estrutura de diretórios

Desta vez vamos usar arquivos de apoio para organizar as regras de revisão:²

BASH

mkdir -p ~/.claude/skills/code-review
mkdir -p ~/.claude/skills/code-review/checklists

touch ~/.claude/skills/code-review/SKILL.md
touch ~/.claude/skills/code-review/checklists/naming.md
touch ~/.claude/skills/code-review/checklists/error-handling.md

Por que separar os arquivos:

O SKILL.md fica curto e guarda só o fluxo principal
As regras detalhadas de checagem ficam em arquivos separados, carregadas sob demanda²
Seu time pode manter cada checklist de forma independente, sem tocar no arquivo principal

Passo 3: escreva o SKILL.md principal

MARKDOWN

---
name: code-review
description: Revisa mudanças de código quanto a convenções de nomenclatura, tratamento de erros, bugs potenciais e problemas de manutenibilidade. Use para revisão de PR ou checagens gerais de qualidade de código
---

# Assistente de Code Review

Revise mudanças de código sistematicamente contra as convenções do time e a prática estabelecida.

## Formatos de entrada

Aceite qualquer um dos seguintes:

- Saída de git diff
- Um arquivo-fonte completo
- Um fragmento de código (uma função ou uma classe)
- Um link de PR (leia o conteúdo do PR com uma ferramenta antes)

## Fluxo de revisão

Execute a revisão nesta ordem:

### 1. Checagem de convenções

Consulte `checklists/naming.md` e percorra cada item:

- **Nomes de variáveis**: significativos e consistentes com a convenção do time (camelCase, snake_case e afins)
- **Nomes de funções**: começam com verbo, declaram a intenção com clareza
- **Nomes de classes**: substantivos, alinhados à responsabilidade única
- **Nomes de constantes**: tudo em maiúsculas, separado por underscore

**Critério:** todo nome deve dizer, a alguém que não conhece o código, para que ele serve

### 2. Checagem de tratamento de erros

Consulte `checklists/error-handling.md` e cheque:

- **Captura de exceções**: existe try/catch, e ele captura os tipos certos de exceção
- **Valores de retorno de erro**: a função trata e propaga erros corretamente
- **Casos-limite**: entrada vazia, null, undefined e arrays vazios estão tratados
- **Liberação de recursos**: arquivos, conexões e locks são liberados corretamente

**Critério:** tudo que pode falhar precisa de tratamento de erro

### 3. Checagem de problemas potenciais

- **Acesso a null/undefined**: isso pode chegar a uma propriedade ou método que não existe
- **Segurança de tipos**: existe risco de coerção implícita de tipo
- **Concorrência**: existe condição de corrida ou risco de deadlock
- **Brechas de segurança**: SQL injection, XSS, CSRF, segredos vazados

**Critério:** sinalize qualquer código que possa produzir erro em tempo de execução ou risco de segurança

### 4. Checagem de manutenibilidade

- **Tamanho da função**: sugira dividir qualquer coisa acima de 50 linhas
- **Duplicação**: sugira extrair lógica que apareça três ou mais vezes
- **Profundidade de aninhamento**: sugira refatorar acima de três níveis
- **Qualidade dos comentários**: a lógica complexa está explicada

**Critério:** outra pessoa desenvolvedora deve conseguir ler e alterar este código com facilidade

## Formato de saída

Relate a revisão nesta estrutura:

### ✅ Aprovado
- [item de checagem] - atende ao critério

### ⚠️ Vale uma olhada
- **Local**: `file:line`
- **Problema**: o que exatamente está errado
- **Impacto**: a que isso pode levar
- **Sugestão**: como melhorar

### 🔴 Precisa corrigir
- **Local**: `file:line`
- **Problema**: o que exatamente está errado
- **Risco**: por que isso não pode ir assim
- **Sugestão**: a correção concreta

### 📊 Avaliação geral
- Qualidade do código: forte / aceitável / precisa de trabalho
- Principais problemas: [as 2-3 questões mais importantes]
- Prioridade sugerida: [o que corrigir primeiro]

## Observações

- **Contexto faltando**: se o fragmento estiver incompleto, diga que você pode precisar de mais do código ao redor
- **Idiomas de framework**: algo que parece um problema pode ser um padrão específico do framework — marque como "precisa de confirmação"
- **Código de teste**: relaxe os critérios para testes onde fizer sentido (tamanho da função, por exemplo)
- **Nada encontrado**: se todas as checagens passarem, exiba "✅ Revisão aprovada, nenhum problema óbvio encontrado"

Passo 4: escreva os arquivos de apoio

checklists/naming.md:

MARKDOWN

# Checklist de convenções de nomenclatura

## Nomes de variáveis

**Bom:**
- `userCount`: claramente uma contagem de usuários
- `isAuthenticated`: booleanos começam com is/has/can
- `maxRetryAttempts`: declara tanto o significado quanto a unidade

**Ruim:**
- `x`, `temp`, `data`: genéricos demais
- `flag`, `status`: não dizem que estado guardam
- `getUserInfo2`: um sufixo numérico geralmente significa que existe uma duplicata

## Nomes de funções

**Bom:**
- `calculateTotalPrice()`: verbo mais substantivo, declara a ação e o objeto dela
- `validateUserInput()`: diz o que faz e sobre o que age
- `fetchUserProfile()`: `fetch` sinaliza que isto é assíncrono

**Ruim:**
- `process()`: genérico demais, processa o quê
- `doStuff()`: não expressa intenção nenhuma
- `handleData()`: tanto `handle` quanto `data` são amplos demais

## Nomes de classes

**Bom:**
- `UserRepository`: um substantivo que declara a responsabilidade (ler e gravar dados de usuário)
- `PaymentProcessor`: claramente a coisa que trata pagamentos
- `EmailValidator`: declara a responsabilidade de validar e-mail

**Ruim:**
- `Manager`, `Helper`, `Utility`: sufixos genéricos demais para significar qualquer coisa
- `DataClass`: não diz quais dados

checklists/error-handling.md:

MARKDOWN

# Checklist de tratamento de erros

## Cenários que você precisa checar

### 1. Chamadas a dependências externas
- Requisições de API (falha de rede, timeout, respostas 4xx/5xx)
- Consultas a banco de dados (falha de conexão, timeout de consulta, violação de restrição)
- Operações de arquivo (arquivo ausente, permissões insuficientes, disco cheio)

### 2. Entrada do usuário
- Entrada vazia, null, undefined
- Entrada malformada
- Valores fora do intervalo

### 3. Conversão de dados
- Parsing de JSON (entrada malformada)
- Conversão de tipo (falha de string para número)
- Parsing de data (formato de data inválido)

## Padrões de tratamento de erros

**Capturar e tratar:**
```javascript
try {
  const data = await fetchUser(id);
  return processData(data);
} catch (error) {
  logger.error('Failed to fetch user', { id, error });
  return null; // ou lance um erro customizado
}
```

**Checar antes de chamar:**
```javascript
if (!user) {
  throw new Error('User not found');
}
const profile = user.getProfile(); // seguro — user com certeza não é null
```

## Erros comuns

**Problema:** um bloco catch vazio
```javascript
try {
  riskyOperation();
} catch (e) {
  // nada acontece aqui — o erro é engolido
}
```

**Correção:** logue, no mínimo
```javascript
try {
  riskyOperation();
} catch (e) {
  logger.error('Operation failed', e);
  throw e; // ou retorne um status de erro
}
```

Passo 5: teste um caso bagunçado

Prepare um trecho com vários problemas dentro:

JAVASCRIPT

function process(data) {
  var result = [];
  for (var i = 0; i < data.length; i++) {
    var item = data[i];
    if (item.type == "A") {
      var x = item.value * 2;
      result.push(x);
    } else if (item.type == "B") {
      var y = item.value / 2;
      result.push(y);
    } else {
      result.push(item.value);
    }
  }
  return result;
}

Invoque a Skill:

A saída deve incluir:

⚠️ Nomenclatura: process, data, x e y são todos genéricos demais
⚠️ Usa var em vez de const/let
⚠️ Usa == em vez de ===
⚠️ Nunca checa se data é null ou se não é um array
⚠️ Nunca checa se item.value existe
Sugestão: a função pode ser dividida em funções puras menores

Passo 6: itere

O que a primeira execução costuma revelar:

Escapes (problemas reais que ela não pegou) → adicione regras de checagem
Saída longa demais → aperte o formato de saída para reportar só o que importa
Falsos positivos (código normal sinalizado como problema) → adicione uma categoria “precisa de confirmação”

Continue melhorando:

Depois de cada revisão, anote quais problemas escaparam
Atualize os checklists
Teste de novo
Em um mês, a Skill fica genuinamente precisa.³

Recapitulação

Code review é um encaixe natural para uma Skill: passos fixos, critérios mensuráveis, alta repetição
Organize o fluxo como um checklist: convenções, tratamento de erros, problemas potenciais, manutenibilidade
Arquivos de apoio mantêm a Skill sustentável: o arquivo principal fica curto, as regras detalhadas ficam por conta própria
Graduar a saída importa: aprovado, vale uma olhada, precisa corrigir — para quem revisa saber o que fazer primeiro
Continue iterando: adicione as checagens que faltaram depois de cada revisão, e em um mês ela estará precisa

Na próxima lição passamos aos padrões avançados: skills pessoais versus de projeto, controle de versão e colaboração em time.

Lição 6 >>

Blog de engenharia da Anthropic: Equipping agents for the real world with Agent Skills — https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills ↩
Documentação da plataforma da Anthropic: Agent Skills overview — https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview ↩ ↩²
Claude Code skills: fluxos de trabalho .NET e prompts reutilizáveis — https://codewithmukesh.com/blog/skills-claude-code/ ↩

Exercícios

Escolha um domínio que você conhece bem — código de frontend, design de API, consultas SQL, documentação — e construa uma Skill de revisão para ele.

Nível 1: Construa sua própria Skill de revisão

Requisitos:

Pelo menos 3 dimensões de revisão
3-5 itens concretos de checagem por dimensão
Um formato de saída claro (aprovado, vale uma olhada, precisa corrigir)
Teste em pelo menos 2 casos reais

Critérios de conclusão · marcado localmente

As dimensões são bem definidas e valem a checagemCada item de checagem é concreto o bastante para agir (não “cheque a qualidade do código”)O formato de saída torna a severidade óbvia de imediatoCódigo real ou documentos reais testados e resultados registrados

Pegue um trecho de código e revise-o duas vezes:

Nível 2: Compare uma revisão humana com a da Skill

Na mão, você mesmo
Com a Skill code-review

Compare o que cada uma encontrou e anote:

Quais problemas a Skill pegou que você deixou passar
Quais problemas você pegou que a Skill deixou passar
Quais dos achados dela foram falsos positivos (sinalizados como problemas, mas na verdade estão bem)

Critérios de conclusão · marcado localmente

O mesmo código passou pelos dois métodos de revisãoComparação lado a lado dos achados registradaAnálise de onde a Skill é forte e de onde ela fica devendoMudanças concretas propostas para a Skill

Lição 5: Estudo de caso: construindo uma Skill de code review

Por que code review é um bom estudo de caso

Passo 1: defina o escopo da revisão

Passo 2: crie a estrutura de diretórios

Passo 3: escreva o SKILL.md principal

Passo 4: escreva os arquivos de apoio

Passo 5: teste um caso bagunçado

Passo 6: itere

Recapitulação

Footnotes

Exercícios

Escolha um domínio que você conhece bem — código de frontend, design de API, consultas SQL, documentação — e construa uma Skill de revisão para ele.

Pegue um trecho de código e revise-o duas vezes: