Spec-Driven Laravel

Skill de Spec-Driven Development (SDD) adaptada para projetos Laravel, integrada aos recursos do Laravel Boost (guidelines + MCP server).

Adaptação da skill tlc-spec-driven v3.3.0 de Felipe Rodrigues (@felipfr), publicada pelo Tech Leads Club sob licença CC-BY-4.0 — com exemplos, convenções e ferramentas ajustados para o ecossistema Laravel: Pest/PHPUnit, Pint, Larastan, artisan e as tools MCP do Boost.

O que ela faz

Planeja e implementa features em 4 fases adaptativas:

┌──────────┐   ┌──────────┐   ┌─────────┐   ┌─────────┐
│ SPECIFY  │ → │  DESIGN  │ → │  TASKS  │ → │ EXECUTE │
└──────────┘   └──────────┘   └─────────┘   └─────────┘
 obrigatória    opcional*      opcional*     obrigatória

* A skill pula automaticamente quando o escopo não precisa

A profundidade se ajusta à complexidade — uma correção pequena vira uma spec de uma linha e implementação direta; uma feature multi-componente ganha spec formal com requisitos rastreáveis, design de arquitetura, quebra em tarefas atômicas e validação independente.

Requisitos

• Claude Code (ou outro agente que suporte Agent Skills)
• Python 3 — para os scripts de validação determinística (opcional, mas recomendado; sem ele os gates rodam por leitura manual)
• Laravel Boost instalado no projeto (recomendado): composer require --dev laravel/boost && php artisan boost:install

Instalação

Copie a pasta para o diretório de skills:

# Global (todos os projetos)
cp -r spec-driven-laravel ~/.claude/skills/

# Ou por projeto
cp -r spec-driven-laravel <seu-projeto>/.claude/skills/

Como usar

A skill dispara por gatilhos naturais na conversa. Fluxo típico de uma feature:

1. Especificar

"Especifique a feature de assinaturas: o usuário assina um plano mensal, pode cancelar a qualquer momento e mantém acesso até o fim do período pago."

A skill faz perguntas para fechar ambiguidades (só as que o código não responde), escreve critérios de aceite em notação EARS (WHEN... THEN... SHALL...) e grava em .specs/features/assinaturas/spec.md. Você aprova antes de seguir.

2. Design (features maiores)

"Crie o design"

Arquitetura, componentes (actions, controllers, models, jobs), modelos de dados (migrations + casts + relationships), riscos e o que reutilizar do código existente. Usa o database-schema do Boost para nunca inventar schema.

3. Tarefas (features maiores)

"Quebre em tasks"

Tarefas atômicas (uma migration + model, uma action, um endpoint...) com dependências, matriz de cobertura de testes e comandos de gate (php artisan test, Pint, Larastan) extraídos do seu projeto — nunca inventados.

4. Executar

"Implemente" (ou "implemente a T3")

Para cada tarefa: escreve os testes derivados da spec → implementa o mínimo para passar → roda o gate (a suíte decide, não a auto-avaliação) → um commit atômico em Conventional Commits. Ao final da última tarefa, um Verificador independente (autor ≠ verificador) confere cada critério de aceite com evidência arquivo:linha e injeta mutações para provar que os testes detectam regressões.

Outros comandos úteis

Você diz	O que acontece
"Registre essa decisão"	Grava decisão de arquitetura em .specs/STATE.md (log AD-NNN)
"Pausar trabalho"	Snapshot do estado atual para retomar depois
"Retomar trabalho"	Lê o snapshot, reconcilia com o git e propõe o próximo passo
"Valide" / "UAT"	Validação da feature, com walkthrough interativo se for UI

Estrutura gerada no projeto

.specs/
├── STATE.md            # Memória: decisões (AD-NNN) + snapshot de pausa
├── LESSONS.md          # Lições aprendidas com falhas de verificação
└── features/
    └── [feature]/
        ├── spec.md         # Requisitos com IDs rastreáveis
        ├── context.md      # Decisões de áreas ambíguas (quando houver)
        ├── design.md       # Arquitetura (features maiores)
        ├── tasks.md        # Tarefas atômicas (features maiores)
        └── validation.md   # Relatório do Verificador (PASS/FAIL + evidências)

Integração com Laravel Boost

A skill usa as tools MCP do Boost em todas as fases:

• application-info — pacotes e versões instalados (nunca projeta para pacote que não existe)
• database-schema / database-query — schema e dados reais (nunca chuta estrutura de tabela)
• search-docs — documentação na versão exata dos seus pacotes (Laravel, Livewire, Inertia, Pest...)
• tinker — testa comportamento em runtime durante design e debug
• last-error / read-log-entries / browser-logs — diagnóstico quando um gate falha
• get-absolute-url — links clicáveis durante o UAT

As guidelines do Boost (injetadas automaticamente no contexto) valem como convenção do projeto — a skill as segue sem repeti-las.

Dica: quando usar

Esta skill paga seu custo em features médias e grandes — multi-componente, domínio ambíguo, várias sessões de trabalho. Para o dia a dia (feature pequena, bug fix com teste), um fluxo leve sem specs formais resolve melhor. Se a skill dimensionar como "Small", ela mesma pula a burocracia — mas você também pode simplesmente não invocá-la.

Licença e Atribuição

Esta skill é uma obra derivada de tlc-spec-driven v3.3.0, criada por Felipe Rodrigues (@felipfr) e publicada pelo Tech Leads Club, licenciada sob CC-BY-4.0.

Modificações desta adaptação: exemplos de código convertidos para Laravel (Eloquent, migrations, Form Requests, Pest/PHPUnit), integração com as tools MCP e guidelines do Laravel Boost, comandos de gate do ecossistema PHP (artisan, Pint, Larastan, Infection), terminologia de testes ajustada (feature tests) e este README em português.

Esta adaptação é distribuída sob a mesma licença CC-BY-4.0. Ao reutilizá-la, mantenha a atribuição ao autor original, ao Tech Leads Club e a esta adaptação.