Uso de "skills" e abordagem "spec-driven" com Claude Code

O Claude Code é um ambiente de codificação agentivo: ele não apenas responde perguntas, mas pode ler a base de código, editar arquivos, executar comandos e verificar resultados ao longo de um loop de trabalho que combina entendimento, ação e validação. Além disso, ele pode ser usado no terminal, IDE, desktop e navegador, com um mesmo conjunto de instruções e extensões compartilhadas entre esses ambientes.

Dentro desse modelo, duas ideias se destacam para ganhar consistência e escala: skills e uma forma de trabalhar orientada por especificações (spec-driven). As skills são extensões em Markdown que adicionam conhecimento, workflows reutilizáveis e comandos invocáveis ao Claude Code; já o spec-driven não aparece como um “recurso oficial” com esse nome, mas é uma estratégia de uso totalmente alinhada às práticas que a Anthropic recomenda: partir de uma especificação clara, decompor o trabalho, definir critérios de verificação e manter artefatos estruturados ao longo da execução.

O que são skills no Claude Code

No Claude Code, uma skill é uma capacidade modular definida em um arquivo SKILL.md. Esse arquivo pode conter frontmatter YAML com metadados — como nome, descrição, ferramentas permitidas e modo de invocação — seguido por instruções em Markdown que orientam o comportamento do agente quando a skill é acionada. O Claude pode carregar uma skill automaticamente quando ela parece relevante para a solicitação do usuário, ou o usuário pode chamá-la explicitamente por meio de um comando como /nome-da-skill.

As skills são importantes porque funcionam como uma camada entre o “conhecimento genérico” do modelo e as necessidades específicas do seu time ou projeto. Em vez de repetir o mesmo prompt toda vez — por exemplo, “revise este código considerando segurança, performance e compatibilidade” — você embute esse raciocínio em uma skill reutilizável. Isso reduz ambiguidade, melhora a repetibilidade e separa melhor o que é regra do projeto do que é tarefa pontual. A própria documentação do Claude Code posiciona as skills como a extensão mais flexível do ecossistema, ao lado de CLAUDE.md, hooks, subagentes e MCP.

Outro ponto forte é o controle fino de comportamento. Uma skill pode, por exemplo, ser marcada com disable-model-invocation: true para que só o usuário a execute manualmente, o que é útil em ações sensíveis como deploy ou criação de commit. Também pode usar allowed-tools para limitar as ferramentas liberadas durante sua execução, e context: fork para rodar em subagente isolado, preservando o contexto principal. Esse desenho ajuda a tornar o uso do Claude mais governável e mais previsível.

O papel do CLAUDE.md e da estrutura .claude/

Antes mesmo de falar em spec-driven, vale entender a arquitetura recomendada pelo Claude Code. O arquivo CLAUDE.md é carregado em toda sessão e serve para guardar convenções duradouras do projeto: comandos de build/test/lint, stack principal, padrões de exportação, formato das APIs e outras regras “sempre válidas”. Já a pasta .claude/ pode armazenar skills, regras por caminho, subagentes, configurações e memória adicional do agente. A recomendação explícita é: use CLAUDE.md para o que vale sempre; mova o que é específico de certas tarefas para skills ou regras mais localizadas.

Essa separação é crucial para manter o contexto sob controle. A própria Anthropic destaca que o context window é um recurso escasso: conforme a janela enche, o desempenho pode degradar, e o agente pode começar a perder instruções ou cometer mais erros. Por isso, um projeto bem estruturado no Claude Code tende a usar CLAUDE.md como camada base, skills como capacidades sob demanda e critérios de verificação claros para cada tarefa.

O que significa trabalhar de forma spec-driven com Claude Code

No contexto do Claude Code, “spec-driven” deve ser entendido menos como uma funcionalidade isolada e mais como uma disciplina de engenharia. Em vez de pedir “implementa isso aí”, você começa por uma especificação explícita: objetivo, requisitos, critérios de aceite, restrições técnicas, comandos de validação, arquivos afetados e, se possível, exemplos ou testes esperados. Essa abordagem conversa diretamente com o loop agentivo descrito pela Anthropic — reunir contexto, agir e verificar — porque fornece ao agente um norte claro para decidir o que ler, o que mudar e como provar que o trabalho foi concluído.

A Anthropic reforça em suas boas práticas que a alavanca mais forte para qualidade é dar ao Claude um jeito de verificar o próprio trabalho, incluindo testes, saídas esperadas e critérios objetivos de sucesso. Em outras palavras, uma boa especificação para Claude Code não descreve apenas “o que construir”, mas também “como saber que está certo”. Isso muda a relação com o agente: em vez de depender de inspeção manual a cada passo, você transforma a tarefa em algo mais verificável e iterável.

Essa lógica aparece também nos textos da Anthropic sobre agentes de longa duração. Em trabalhos mais complexos, eles relatam ganhos ao decompor uma especificação de produto em lista de tarefas e ao usar artefatos estruturados para fazer a passagem de contexto entre sessões. Ou seja: o “spec-driven” é, na prática, o uso de documentos e estruturas intermediárias para evitar que o agente tente fazer tudo de uma vez, perca coerência ou finalize cedo demais.

Por que combinar skills com spec-driven

A combinação é poderosa porque cada peça resolve um problema diferente. O spec-driven organiza o trabalho corrente: o que deve ser feito agora, quais critérios definem sucesso e quais restrições precisam ser respeitadas. Já as skills organizam o conhecimento e o método recorrente: como o seu time costuma quebrar requisitos em tarefas, como validar mudanças em API, como revisar segurança, como preparar uma PR ou como executar um deploy seguro.

Na prática, isso significa que a especificação vira a fonte da verdade daquela entrega, enquanto as skills viram os procedimentos operacionais padrão que o Claude aplica repetidamente. Essa separação evita dois extremos: um CLAUDE.md inchado com instruções demais e prompts gigantescos reescritos a cada demanda. Também melhora a capacidade do agente de atuar em paralelo ou em subagentes, porque cada unidade de trabalho pode carregar uma skill adequada sem poluir o contexto principal.

Estrutura recomendada para um projeto

Uma forma madura de organizar isso é manter três camadas bem distintas:

meu-projeto/
├─ CLAUDE.md
├─ docs/
│  └─ specs/
│     ├─ auth-refresh-token.md
│     └─ billing-retry-policy.md
└─ .claude/
   ├─ skills/
   │  ├─ implement-from-spec/
   │  │  └─ SKILL.md
   │  ├─ review-against-spec/
   │  │  └─ SKILL.md
   │  └─ open-pr-with-checklist/
   │     └─ SKILL.md
   ├─ rules/
   │  └─ testing.md
   └─ settings.json

Nessa organização, o CLAUDE.md guarda convenções permanentes; docs/specs/ concentra as especificações por funcionalidade; e .claude/skills/ encapsula workflows reutilizáveis. Isso segue a lógica do Claude Code para separar contexto persistente, conhecimento sob demanda e customizações do agente dentro da pasta .claude/.

Exemplo de skill para implementação a partir de especificação

Abaixo está um exemplo original de skill que você poderia usar para implementar uma feature a partir de uma spec:

---
name: implement-from-spec
description: Implementa uma funcionalidade a partir de uma especificação em docs/specs e valida com testes.
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Edit, Write, Bash
context: fork
---

Você vai implementar a funcionalidade descrita em $ARGUMENTS.

Passos obrigatórios:
1. Ler a especificação informada.
2. Identificar requisitos funcionais e não funcionais.
3. Mapear arquivos impactados.
4. Propor plano curto antes de editar.
5. Implementar em pequenos incrementos.
6. Executar testes e validações relevantes.
7. Comparar resultado final com os critérios de aceite da spec.
8. Gerar resumo com:
   - requisitos atendidos
   - pendências
   - riscos
   - testes executados

Essa skill traduz muito bem o espírito spec-driven: ela exige leitura da especificação, transforma requisitos em plano de ação, implementa de forma incremental e fecha com verificação contra critérios de aceite. O uso de context: fork também segue o padrão recomendado para tarefas mais estruturadas que se beneficiam de um subagente isolado.

Exemplo de fluxo operacional

Um fluxo de trabalho simples pode ser:

1. Registrar a convenção do projeto em CLAUDE.md (build, teste, lint, stack, padrões de PR).
2. Criar a spec em docs/specs/feature-x.md, incluindo problema, escopo, fora de escopo, critérios de aceite e validação esperada. Essa parte é uma prática de engenharia, mas ela se encaixa diretamente na recomendação de fornecer critérios de verificação claros ao Claude.
3. Executar uma skill como /implement-from-spec docs/specs/feature-x.md. Como skills podem ser invocadas por slash command e até executadas em subagentes, elas funcionam como um “modo de operação” repetível.
4. Rodar uma segunda skill de revisão, por exemplo /review-against-spec docs/specs/feature-x.md, para comparar a implementação final com a spec e levantar gaps. Isso reforça o princípio de verificação e fechamento por critérios objetivos.

Benefícios reais dessa abordagem

O primeiro benefício é consistência. Ao encapsular procedimentos em skills, você reduz a variação entre sessões e entre engenheiros. O segundo é governança: dá para controlar quem pode disparar certas ações, quais ferramentas ficam liberadas e quando uma skill deve rodar em contexto isolado. O terceiro é eficiência de contexto, já que o Claude não precisa carregar instruções detalhadas o tempo todo — basta saber que a skill existe e carregá-la quando necessário.

O quarto benefício é escalabilidade em tarefas longas. As publicações da Anthropic sobre agentes de longa duração mostram que decompor o trabalho, usar artefatos estruturados e manter handoffs claros entre etapas melhora muito a coerência em sessões extensas. Esse é exatamente o tipo de ganho que o spec-driven traz quando combinado com skills bem definidas.

Limites e cuidados

Mesmo com uma boa arquitetura, Claude Code continua sendo um agente probabilístico. A própria Anthropic destaca que contexto excessivo degrada performance e que tarefas vagas sem critérios de validação tendem a gerar saídas aparentemente boas, mas incorretas. Por isso, skills não devem virar depósito de instruções gigantes, e specs não devem ser documentos prolixos sem testes ou condições de aceite objetivas.

Outro cuidado é não transformar tudo em skill. A documentação é clara ao diferenciar funções: CLAUDE.md para convenções persistentes; skills para workflows e conhecimento reutilizável; hooks para automações determinísticas; MCP para integrações externas; subagentes para isolamento e paralelismo. Escolher a abstração errada gera mais complexidade, não mais produtividade.

Conclusão

Usar Claude Code com skills e uma abordagem spec-driven é, na prática, transformar um assistente de código em um sistema de trabalho mais confiável. As skills dão forma reutilizável ao seu método; as specs dão direção concreta para a execução; CLAUDE.md garante alinhamento de base; e os mecanismos de subagentes, ferramentas e validação completam o ciclo. O resultado é menos improviso, mais reprodutibilidade e maior capacidade de usar o agente em tarefas reais de engenharia de software.