Claude Workflow Kit

Um kit operacional para usar Claude Code com contexto, agentes, comandos, workflows, specs, skills, revisão e execução assistida por IA.

Este projeto não é um boilerplate de aplicação. Ele define uma disciplina operacional de IA para estruturar como o Claude Code entende contexto, especifica requisitos, planeja, implementa, testa, revisa e entrega mudanças em projetos de software.

Relação com /init

Este kit não substitui o comando /init do Claude Code. Ele complementa o bootstrap nativo com uma camada de método, governança e execução.

O /init dá consciência do projeto.
O Claude Workflow Kit dá disciplina operacional e fluxo orientado por specs.

Use os dois em conjunto:

1. Rode /init para o Claude entender o projeto real, se desejar.
2. Instale o Claude Workflow Kit para adicionar agentes, comandos, workflows e critérios de qualidade.
3. Cole o prompt de instalação gerado no Claude Code.
4. O prompt reconcilia automaticamente o CLAUDE.md existente com a disciplina operacional do kit.

Em outras palavras: /init descobre o contexto; o Claude Workflow Kit padroniza como a IA deve trabalhar dentro desse contexto, sem exigir uma etapa manual separada de reconciliação.

Quickstart

Projeto existente

Use este fluxo quando o projeto já tem código, README, dependências ou estrutura inicial.

cd meu-projeto
curl -fsSL https://raw.githubusercontent.com/reluviari/claude-workflow-kit/master/scripts/install.sh | bash -s -- existing
claude

Depois, cole no Claude Code o conteúdo gerado em:

.claude-workflow-kit/install-claude-workflow-kit.md

O Claude deve analisar a estrutura atual, detectar a stack, identificar comandos reais de build/test/lint, avaliar sinais de SOLID e Clean Architecture, reconciliar automaticamente CLAUDE.md existente com a disciplina operacional do kit, sugerir melhorias arquiteturais e criar o workspace adaptado ao projeto.

Projeto vazio

Use este fluxo quando o projeto ainda não tem estrutura, stack ou código inicial.

mkdir meu-projeto
cd meu-projeto
curl -fsSL https://raw.githubusercontent.com/reluviari/claude-workflow-kit/master/scripts/install.sh | bash -s -- empty
claude

Depois, cole no Claude Code o conteúdo gerado em:

.claude-workflow-kit/install-claude-workflow-kit.md

O Claude deve perguntar apenas o contexto mínimo necessário, criar ou reconciliar CLAUDE.md automaticamente e gerar a estrutura operacional do projeto sem implementar código de aplicação.

Bootstrap SSD opcional

Se quiser que o prompt de instalação também pergunte sobre SSD — Spec-Driven Development — como fluxo padrão para features, bugfixes e melhorias não triviais, use --ssd:

curl -fsSL https://raw.githubusercontent.com/reluviari/claude-workflow-kit/master/scripts/install.sh | bash -s -- existing --ssd

Ou use variável de ambiente:

curl -fsSL https://raw.githubusercontent.com/reluviari/claude-workflow-kit/master/scripts/install.sh | CWK_BOOTSTRAP_SSD=1 bash -s -- existing

--ssd e CWK_BOOTSTRAP_SSD=1 apenas adicionam instruções ao prompt gerado. O instalador continua sem rodar Claude, sem criar código de aplicação e sem gerar specs automaticamente pelo shell. O Claude só oferece o bootstrap SSD depois de concluir e validar a instalação.

Instalação versionada

Por padrão, o instalador usa a branch master. Para fixar uma branch ou tag, defina CWK_VERSION:

curl -fsSL https://raw.githubusercontent.com/reluviari/claude-workflow-kit/master/scripts/install.sh | CWK_VERSION=v0.2.0 bash -s -- existing

CWK_VERSION aceita tags como v0.2.0 e branches como master.

O que o kit cria

Depois da instalação e adaptação pelo Claude Code, o projeto deve ficar assim:

meu-projeto/
│
├── CLAUDE.md
│
├── README_SUGGESTED_CLAUDE.md
│
├── .claude/
│   ├── agents/
│   │   ├── architect.md
│   │   ├── backend-engineer.md
│   │   ├── frontend-engineer.md
│   │   ├── qa-engineer.md
│   │   ├── code-reviewer.md
│   │   ├── devops-engineer.md
│   │   ├── security-reviewer.md
│   │   ├── product-analyst.md
│   │   └── documentation-writer.md
│   │
│   ├── commands/
│   │   ├── plan.md
│   │   ├── spec.md
│   │   ├── implement.md
│   │   ├── implement-spec.md
│   │   ├── validate-spec.md
│   │   ├── review.md
│   │   ├── test.md
│   │   ├── refactor.md
│   │   ├── commit.md
│   │   └── update-context.md
│   │
│   ├── workflows/
│   │   ├── feature-development.md
│   │   ├── bugfix.md
│   │   ├── refactor.md
│   │   ├── technical-design.md
│   │   ├── spec-driven-development.md
│   │   └── release-review.md
│   │
│   └── skills/
│       ├── spec-from-request.md
│       ├── acceptance-criteria.md
│       ├── risk-review.md
│       ├── validation-plan.md
│       ├── spec-gap-analysis.md
│       └── spec-traceability.md
│
└── docs/
    └── claude/
        ├── PROJECT_CONTEXT.md
        ├── ARCHITECTURE.md
        ├── DECISIONS.md
        ├── TESTING_STRATEGY.md
        ├── DELIVERY_PROCESS.md
        └── specs/
            ├── feature-spec.md
            ├── bugfix-spec.md
            └── technical-design-spec.md

A documentação gerada pelo kit fica em docs/claude/ para não misturar com a documentação própria do projeto. Os itens relacionados a specs são detalhados em Spec-Driven AI Development.

O arquivo README_SUGGESTED_CLAUDE.md é uma proposta separada de README de produto e engenharia. Ele não substitui automaticamente o README.md existente, deve ser adaptado ao produto e stack reais, e seu conteúdo não deve mencionar AI, Claude ou assistência automatizada.

O script de instalação prepara os arquivos fonte em .claude-workflow-kit/, gera o prompt temporário em .claude-workflow-kit/install-claude-workflow-kit.md, mas não cria código de aplicação, não instala dependências e não roda Claude automaticamente. A adaptação feita pelo Claude Code não deve deixar prompts/ nem .claude/worktrees/ como artefatos finais do kit. Como .claude-workflow-kit/ ainda é necessário para executar o prompt, ele só deve ser removido depois da instalação; ao final, o Claude Code pergunta se o usuário deseja excluí-lo.

Como o Claude usa estes arquivos

O kit separa contexto, comandos, agentes, workflows, skills, specs e documentação. Nem tudo é carregado automaticamente em toda pergunta.

Local	Tipo	Uso automático?	Quando é usado
CLAUDE.md	contexto persistente do projeto	sim, no início da sessão	orienta regras, padrões, comandos e critérios de trabalho
.claude/commands/	slash commands	sob demanda	quando o usuário chama /plan, /implement, /review, /test, /commit ou outro comando
.claude/agents/	subagentes especializados	sob demanda	quando o usuário pede ou quando o Claude delega uma tarefa compatível
.claude/workflows/	biblioteca de processos do kit	não automaticamente	quando CLAUDE.md, um comando, um agente ou o usuário referencia o workflow
.claude/skills/	capacidades reutilizáveis	sob demanda	quando comandos, workflows, agentes ou o usuário precisam aplicar uma habilidade específica
docs/claude/	documentação operacional consultável	não automaticamente	quando importada, lida por comando/agente ou solicitada pelo usuário
docs/claude/specs/	contratos e critérios de aceite	não automaticamente	antes de planejar, implementar, revisar ou validar trabalho não trivial

Em resumo:

CLAUDE.md              → orienta sempre
.claude/commands/     → comandos invocados sob demanda
.claude/agents/       → especialistas delegados sob demanda
.claude/workflows/    → processos consultados quando referenciados
.claude/skills/       → capacidades reutilizáveis consultadas sob demanda
docs/claude/          → contexto operacional consultável
docs/claude/specs/    → contratos consultados para trabalho não trivial

Detalhes importantes:

• CLAUDE.md não executa ações sozinho; ele define como o Claude deve trabalhar no projeto.
• .claude/commands/ entra no contexto quando um comando é invocado.
• .claude/agents/ define agentes do projeto instalado. Neste repositório, kit/agents/ contém templates de distribuição; por isso /agents pode não listar nada se o kit não foi instalado/adaptado neste próprio projeto.
• .claude/workflows/ não é um diretório mágico carregado automaticamente; workflows precisam ser referenciados por CLAUDE.md, comandos, agentes ou pelo usuário.
• .claude/skills/ descreve métodos reutilizáveis. Skills não são comandos nem agentes.
• docs/claude/ guarda contexto operacional separado da documentação própria do produto.
• docs/claude/specs/ guarda contratos duráveis para trabalho não trivial.

Como pensar neste kit

A ideia é simples:

Contexto → Planejamento → Execução → Teste → Revisão → Documentação → Entrega

O Claude Code continua sendo uma IA. O kit reduz improviso, aumenta contexto e cria um método repetível.

Contratos operacionais dos prompts

Os comandos, agentes, workflows, skills e specs do kit seguem contratos explícitos para reduzir improviso e tornar o comportamento mais verificável.

Tipo	Estrutura esperada
Comandos	objetivo; quando usar; entradas esperadas; regras; fluxo de execução; validação; condições de parada; formato de saída
Workflows	objetivo; quando usar; contexto obrigatório; regras; fluxo; validação; condições de parada; saída esperada
Agentes	objetivo; quando usar; entradas; o que inspecionar; regras; fluxo; validação; condições de parada; saída esperada
Skills	objetivo; quando usar; entradas; regras; procedimento; validação; condições de parada; saída esperada
Specs	status; objetivo; contexto; escopo; não escopo; requisitos; critérios de aceite; restrições; áreas afetadas; plano de validação; riscos e mitigação; perguntas abertas

Esse formato ajuda o Claude Code a continuar trabalhando com evidência, parar antes de ações arriscadas e entregar respostas consistentes entre projetos.

Spec-Driven AI Development

Para trabalho não trivial, o fluxo recomendado é orientar a IA por specs em vez de prompts informais. A spec funciona como contrato de escopo, critérios de aceite, restrições, riscos e validação.

Pedido → /spec → aprovação da spec → /implement-spec → /validate-spec → /review

Nesse modelo, o desenvolvedor atua como arquiteto e editor do contrato. O Claude Code usa agentes, comandos, workflows e skills para executar contra esse contrato sem desviar de escopo.

Use SSD para:

• feature nova;
• bugfix com risco de regressão;
• melhoria com impacto em comportamento;
• decisão técnica durável;
• mudança que precisa de critérios de aceite claros;
• trabalho que deve manter rastreabilidade entre pedido, implementação e validação.

Fluxo recomendado:

1. Explicar a feature, bug ou decisão técnica.
2. Rodar /spec.
3. Revisar e aprovar a spec.
4. Rodar /implement-spec.
5. Rodar /validate-spec.
6. Rodar /review.
7. Rodar /commit, somente se quiser criar commit.

O workflow spec-driven-development formaliza esse ciclo. As skills spec-gap-analysis e spec-traceability ajudam a encontrar lacunas e mapear requisitos para evidência de implementação e validação.

Quando o bootstrap SSD opcional é solicitado com --ssd ou CWK_BOOTSTRAP_SSD=1, o Claude deve concluir a instalação primeiro e só então oferecer a criação ou adaptação de uma spec inicial em docs/claude/specs/. Ele deve usar apenas evidência do repositório e contexto fornecido pelo usuário, sem inventar produto, arquitetura, comandos ou infraestrutura.

Specs ambíguas, sem aprovação ou sem critérios testáveis são condição de parada. Implementação só deve começar depois da spec estar aprovada ou depois de autorização explícita do usuário.

Como usar depois da instalação

Para trabalho não trivial, use o fluxo SSD descrito acima.

Para mudanças simples, use o fluxo geral:

1. Explicar a feature ou problema.
2. Rodar /plan.
3. Revisar o plano.
4. Autorizar implementação.
5. Rodar /implement.
6. Rodar /test.
7. Rodar /review.
8. Rodar /commit.

Conteúdo do kit

Documentação base

• CLAUDE.md;
• README_SUGGESTED_CLAUDE.md como proposta separada de README de produto/engenharia;
• documentos operacionais gerados em docs/claude/, como PROJECT_CONTEXT.md;
• DEFINITION_OF_READY.md;
• DEFINITION_OF_DONE.md;
• ENGINEERING_PRINCIPLES.md;
• REVIEW_CHECKLIST.md.

Agentes incluídos

• arquitetura;
• backend;
• frontend;
• QA;
• code review;
• DevOps;
• segurança;
• produto;
• documentação.

Comandos incluídos

• planejar;
• criar/refinar specs;
• implementar;
• implementar contra spec;
• validar contra spec;
• revisar;
• testar;
• refatorar;
• gerar commit;
• atualizar contexto.

Workflows incluídos

• desenvolvimento de feature;
• correção de bug;
• refatoração;
• design técnico;
• spec-driven development;
• revisão de release.

Skills incluídas

• transformar pedido em spec;
• definir critérios de aceite;
• revisar riscos;
• planejar validação;
• analisar lacunas de spec;
• mapear rastreabilidade entre spec, implementação e validação.

Specs incluídas

• contrato de feature;
• contrato de bugfix;
• contrato de design técnico.

Stacks com notas iniciais

• genérico;
• Next.js;
• React/Vite;
• Node/NestJS;
• Python/FastAPI;
• Rails.

Princípios

• Entender antes de alterar.
• Especificar antes de implementar quando requisitos forem não triviais.
• Manter critérios de aceite testáveis.
• Manter rastreabilidade entre requisito, implementação e validação.
• Tratar specs ambíguas como condição de parada.
• Planejar antes de implementar.
• Implementar em passos pequenos.
• Evitar refatoração fora de escopo.
• Preservar padrões existentes.
• Avaliar aderência a SOLID e Clean Architecture quando analisar projetos existentes.
• Sugerir melhorias arquiteturais sem refatorar fora de escopo.
• Rodar testes quando possível.
• Revisar antes de concluir.
• Documentar decisões importantes.
• Não inventar regra de negócio.
• Não adicionar dependências sem justificativa.

Regra principal

A instalação do Claude Workflow Kit não deve criar features.

Ela deve criar apenas a estrutura de trabalho para o Claude Code operar melhor dentro do projeto.

Instalação manual

Se não quiser usar o instalador via curl, clone este repositório e rode o instalador localmente a partir da raiz do projeto alvo.

Projeto existente:

cd meu-projeto
/path/to/claude-workflow-kit/scripts/install.sh existing
claude

Projeto existente com bootstrap SSD opcional:

cd meu-projeto
/path/to/claude-workflow-kit/scripts/install.sh existing --ssd
claude

Projeto vazio:

mkdir meu-projeto
cd meu-projeto
/path/to/claude-workflow-kit/scripts/install.sh empty
claude

Depois, cole no Claude Code o conteúdo de:

.claude-workflow-kit/install-claude-workflow-kit.md

Para mantenedores

Validar o kit

Antes de abrir PR ou gerar release, rode a validação estrutural:

bash scripts/validate-kit.sh

Ela verifica:

• estrutura obrigatória do repositório;
• se comandos, agentes, workflows, skills, specs e stack notes mantêm os contratos esperados;
• restrições críticas dos prompts de instalação;
• sintaxe dos scripts shell.

O mesmo check roda no GitHub Actions em push e pull_request.

Gerar ZIP de distribuição

O ZIP é um artefato de release, não o fluxo principal de instalação.

./scripts/build-zip.sh

O arquivo será criado em:

zip/claude-workflow-kit.zip

Estrutura deste repositório

claude-workflow-kit/
│
├── README.md
├── LICENSE
├── CHANGELOG.md
│
├── .github/
│   └── workflows/
│       └── validate.yml
│
├── kit/
│   ├── base/
│   ├── agents/
│   ├── commands/
│   ├── workflows/
│   ├── skills/
│   ├── specs/
│   ├── stacks/
│   └── prompts/
│
└── scripts/
    ├── install.sh
    ├── build-zip.sh
    └── validate-kit.sh

Quando usar

Use este kit para:

• projeto novo;
• projeto legado;
• MVP;
• SaaS;
• API;
• frontend;
• monorepo;
• backend;
• sistema interno;
• ferramenta de dados;
• produto com IA;
• projeto pessoal;
• projeto profissional.

Quando não usar

Não use este kit esperando que ele crie uma aplicação pronta.

Ele não substitui arquitetura, produto, engenharia ou revisão humana.

Ele organiza o trabalho da IA dentro do projeto.

Licença

MIT.