# Como configurar o Spec Kit no Claude Code em 2026: especificações em vez de prompts
> Como configurar o GitHub Spec Kit no Claude Code: 4 fases — Specify, Plan, Tasks e Implement. Veja como substituir a programação improvisada por um processo estruturado.
Source: https://ailoot.ai/blog/pt-pt/spec-kit-claude-code-spec-driven-development/
Canonical: https://ailoot.ai/blog/pt-pt/spec-kit-claude-code-spec-driven-development/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-219
Revision: sha256-f95ee707743df69cd9774ed01e28fea0c7ec77f4b4fd318e054d5efd7a53915d
Conclusão principal
O Spec Kit é uma ferramenta do GitHub que permite escrever uma especificação de tarefa em linguagem natural, após o que o Claude Code elabora um plano, divide-o em tarefas e escreve o código. Não é teoria: o Spec Kit obteve 107 000 estrelas no GitHub em 8 meses e a AWS utilizou uma abordagem baseada em especificações num projeto de descoberta de fármacos. Este guia abrange a instalação, os modelos, as 4 fases do fluxo de trabalho e uma verificação final, bem como a ligação ao seu CLAUDE.md.
[Documentação Ailoot](https://ailoot.ai/docs/) — materiais de referência sobre a utilização do serviço.
## O que aconteceu ao vibe coding em maio de 2026?
Conclusão principal
Ao longo de 8 meses, o GitHub Spec Kit reuniu 107 000 estrelas, e a AWS publicou um estudo de caso que indica uma poupança superior a 80 horas numa funcionalidade. A tendência da semana em maio: especificações como substituto da improvisação.
Um ano depois, a 4 de fevereiro de 2026, publicou um fio retrospetivo:
Na sua palestra no Sequoia Ascent 2026, foi ainda mais preciso: «O vibe coding eleva o patamar mínimo — aquilo que todos conseguem fazer em software. O agentic engineering preserva o patamar máximo — o nível de qualidade do desenvolvimento profissional.» No mesmo palco, deixou uma frase que entrou no vocabulário do setor: «Não podem introduzir vulnerabilidades por causa do vibe coding. Continuam a ser responsáveis pelo vosso software, como antes.»
Aconteceram duas coisas em paralelo. Em setembro de 2025, o GitHub publicou a ferramenta [Spec Kit](https://github.com/github/spec-kit) — que reuniu 107 000 estrelas em 8 meses. Em fevereiro de 2026, a AWS publicou [um estudo de caso detalhado sobre descoberta de fármacos](https://aws.amazon.com/blogs/industries/from-spec-to-production-a-three-week-drug-discovery-agent-using-kiro/) que indica «95% da lógica de negócio gerada a partir da especificação, poupando mais de 80 horas».
No final de maio de 2026, formou-se um consenso no espaço informativo de língua inglesa: o vibe coding, enquanto método de trabalho, é o nível de principiante. O passo seguinte é o Spec-Driven Development. Este guia explica como instalar e aplicar esta abordagem.
## O que são o Spec Kit e o Spec-Driven Development?
Conclusão principal
O Spec-Driven Development (SDD) inverte a abordagem habitual a um agente de IA. Antes, o código era a fonte de verdade e a especificação era documentação auxiliar. Agora, a especificação é a fonte de verdade e o código torna-se o passo final — a sua implementação. O Spec Kit é uma ferramenta CLI do GitHub que transforma 4 fases (Specify, Plan, Tasks, Implement) e uma verificação final, Converge, em comandos prontos a utilizar no Claude Code, Cursor, Copilot e mais de 30 outros agentes.
A ideia central da metodologia está resumida numa frase da documentação oficial do GitHub:
O Spec-Driven Development altera a hierarquia: as especificações não servem o código — o código serve as especificações. A especificação passa a ser o artefacto principal, e o código é a sua expressão numa linguagem e framework específicas.
— Documentação do GitHub Spec Kit, https://github.com/github/spec-kit/blob/main/spec-driven.md
Na prática, o processo desenvolve-se em 4 fases (o Spec Kit acrescenta mais uma, a fase zero — constitution, descrita abaixo):
1. **Specify** — escreva em linguagem natural uma especificação do que pretende. O QUE fazer e PORQUÊ. Não COMO.
2. **Plan** — o agente pega na especificação e elabora um plano técnico: que tecnologias utilizar, que arquitetura adotar e que componentes criar.
3. **Tasks** — o agente divide o plano em tarefas específicas e verificáveis, com dependências.
4. **Implement** — o agente (ou os seus subagentes) executa as tarefas e escreve o código.
Depois de Implement, a versão atual do Spec Kit inclui uma etapa de verificação chamada **Converge**: o agente compara o código concluído com a especificação, o plano e as tarefas e acrescenta a `tasks.md` tudo o que ficou por fazer. Repita Implement e Converge até Converge responder «Converged».
Cada fase corresponde a um ficheiro Markdown separado no repositório. No Claude Code, cada fase é um comando de barra separado: `/speckit-specify`, `/speckit-plan`, `/speckit-tasks`, `/speckit-implement`; a verificação é `/speckit-converge`. A documentação do Spec Kit escreve os mesmos comandos com um ponto (`/speckit.specify`), mas no Claude Code o Spec Kit é instalado como skills e os comandos são invocados com hífen. Se algo correr mal em qualquer etapa, edite o ficheiro Markdown e volte a executar a fase seguinte.
O Spec Kit é uma implementação específica do SDD. Em maio de 2026, já tinha mais de 30 integrações com diferentes agentes de IA. Num mesmo repositório, o Spec Kit funciona da mesma forma com Claude Code, Cursor, GitHub Copilot, Codex CLI, Windsurf, Qwen, Tabnine, Amazon Q, Gemini, Goose e mais uma dúzia de agentes.
| Fase do Spec Kit | Comando de barra | Artefacto no repositório |
|----|----|----|
| Constitution | `/speckit-constitution` | `.specify/memory/constitution.md` |
| Specify | `/speckit-specify` | `specs/###-feature/spec.md` |
| Clarify (opcional) | `/speckit-clarify` | alterações em `spec.md` |
| Plan | `/speckit-plan` | `specs/###-feature/plan.md` |
| Checklist (opcional) | `/speckit-checklist` | lista de verificação da qualidade dos requisitos |
| Tasks | `/speckit-tasks` | `specs/###-feature/tasks.md` |
| Analyze (opcional) | `/speckit-analyze` | relatório sobre a especificação, o plano e as tarefas |
| Implement | `/speckit-implement` | código no projeto |
| Converge | `/speckit-converge` | veredito «Converged» ou novas tarefas em `tasks.md` |
Assim, depois de uma execução, o repositório contém não só o código, mas também a sua especificação, o plano e as tarefas. Um mês depois, pode voltar ao projeto, ler `spec.md` e perceber o que foi feito e porquê. Já não é «vibe coding em que se esqueceu que o código existe» — é a memória de trabalho do projeto.
## Porque é que um vibe coder que não escreve código precisa disto?
Conclusão principal
O principal problema de um vibe coder é a imprevisibilidade. Hoje, o agente cria uma funcionalidade funcional em 20 minutos; amanhã, numa tarefa semelhante, produz código desorganizado. O Spec Kit elimina a origem desta imprevisibilidade — uma tarefa formulada de forma vaga. Quando escreve uma especificação com base num modelo, o agente trabalha de forma consistente porque dispõe de uma fonte de verdade inequívoca. Além disso, obtém um artefacto persistente no repositório ao qual pode voltar um mês depois.
O Spec Kit formaliza o planeamento em etapas separadas com 4 comandos de barra. A lógica: separar «pensar bem no assunto» de «implementá-lo», para que aconteçam em janelas de contexto diferentes. Cada etapa beneficia de um contexto limpo, sem a acumulação da fase anterior.
Três vantagens concretas para um vibe coder:
- **Previsibilidade.** Quando diz ao agente «cria um formulário de registo com confirmação por e-mail», ele adivinha por si só 10 detalhes — e falha em três deles relativamente ao que tinha em mente. Quando tem um `spec.md` com User Stories, Acceptance Scenarios e marcadores `[NEEDS CLARIFICATION]` para cada ponto incerto, não há nada para adivinhar.
- **Memória do projeto.** Um mês depois, não se lembrará do que discutiu com o agente no chat. Mas `spec.md`, `plan.md` e `tasks.md` estarão no repositório, na pasta `specs/###-feature/`, ao lado do código. Mostram não só o que foi feito, mas também porquê.
- **Escala.** Numa funcionalidade que envolve 1–2 ficheiros, a diferença quase não se nota. Numa funcionalidade que envolve 20 ficheiros e 5 entidades de dados, a diferença está entre «reescrever tudo ao fim de 4 horas» e «ter tudo integrado na branch principal ao fim de 4 horas». O AWS Kiro demonstrou uma automatização de 95% da lógica de negócio a partir de uma especificação no projeto TargetID.
A principal ilusão do vibe coding é parecer mais rápido no início. Meia hora e já há um protótipo. Mas, ao fim de uma semana, o protótipo avaria e é mais fácil deitar tudo fora. O Spec-Driven Development demora um pouco mais no início (uma hora em vez de meia hora), mas, uma semana depois, continua a trabalhar no mesmo repositório.
## Como instalar o Spec Kit no Claude Code (4 passos)
Conclusão principal
O Spec Kit é instalado através do uv, um gestor de pacotes Python da Astral. O comando propriamente dito ocupa uma linha. Depois da instalação, aceda ao seu repositório, execute `specify init` com a opção `--integration claude` (ou escolha Claude Code na lista de agentes) e obterá uma estrutura pronta, com modelos para constitution, spec, plan e tasks, além de um conjunto de comandos `/speckit-*` diretamente no Claude Code. A instalação demora 5 minutos se o uv já estiver instalado e 10 minutos se o instalar de raiz.
**Passo 1. Instale o uv.** Só precisa de o fazer uma vez; fica no seu sistema.
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
Confirme que o uv foi instalado:
```bash
uv --version
```
**Passo 2. Instale o Spec Kit.** Um comando:
```bash
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
```
Confirme:
```bash
specify --version
```
**Passo 3. Inicialize o repositório.** Aceda à pasta do projeto (ou crie uma nova) e execute:
```bash
specify init --here --integration claude
```
A opção `--integration claude` seleciona diretamente o Claude Code. Sem ela, o Spec Kit pede-lhe para escolher um agente numa lista interativa e pode também perguntar o tipo de script (no macOS e Linux, mantenha `sh`). Se a pasta não estiver vazia, o Spec Kit avisa que vai juntar os respetivos ficheiros aos seus: faça primeiro commit do seu trabalho e, em seguida, repita o comando com a opção `--force`.
Depois disso, surgirá o seguinte no repositório:
```
.specify/
memory/
constitution.md # project rules, filled in by /speckit-constitution
scripts/
templates/
spec-template.md
plan-template.md
tasks-template.md
.claude/
skills/
speckit-constitution/SKILL.md
speckit-specify/SKILL.md
speckit-clarify/SKILL.md
speckit-plan/SKILL.md
speckit-checklist/SKILL.md
speckit-tasks/SKILL.md
speckit-analyze/SKILL.md
speckit-implement/SKILL.md
speckit-converge/SKILL.md
speckit-taskstoissues/SKILL.md
```
**Passo 4. Abra o Claude Code e confirme os comandos de barra.** Execute isto na mesma pasta:
```bash
claude
```
Na sessão, escreva `/speckit` — os comandos `speckit-*` deverão surgir nas sugestões. Se não surgirem, reinicie o Claude Code para que volte a ler `.claude/skills/`. Se já tiver um `CLAUDE.md` na raiz do projeto, o Spec Kit não lhe toca — funciona em conjunto com ele, em `.specify/memory/constitution.md`.
O Spec Kit também funciona sem Claude Code (é compatível com mais de 30 agentes), mas este guia aborda especificamente a configuração com Claude. Se quiser instalar duas ferramentas de imediato, consulte os guias separados sobre [configurar o CLAUDE.md](https://ailoot.ai/blog/pt-pt/claude-md-template/) e o [Plan Mode no Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-plan-mode/).
O Spec Kit é a primeira peça de um «contrato de trabalho do agente». A configuração completa inclui as três: um clone de IA (a sua metodologia sob a forma de Skills e subagentes), um Second Brain (a estrutura `business/` à qual o agente regressa em cada utilização) e engenharia de contexto (Spec Kit, Plan Mode, /compact). Estes são os três pilares sem os quais a IA alucina.
## Como escrever a sua primeira especificação (Specify)
Conclusão principal
O Spec Kit pede-lhe que descreva uma funcionalidade livremente e, em seguida, expande essa descrição num ficheiro `spec.md` através de um modelo: User Stories com prioridades P1/P2/P3, Acceptance Scenarios no formato Given/When/Then, Functional Requirements (FR-001, FR-002, etc.) e Success Criteria com resultados mensuráveis. Sempre que o agente tiver dúvidas, insere um marcador `[NEEDS CLARIFICATION: ...]` — terá de responder a estas questões antes de avançar para Plan.
No Claude Code, escreva:
```
/speckit-specify
```
Em seguida, o agente pedirá uma descrição da funcionalidade. Nesta fase, use linguagem simples, sem jargão técnico:
```
Quero um formulário de registo na minha aplicação. O utilizador introduz um e-mail
e uma palavra-passe, recebe um e-mail de confirmação e, depois de confirmar,
acede ao painel. A confirmação expira após 48 horas. Se o email continuar
por confirmar, elimina a conta até 5 minutos após esse prazo; nunca
elimines uma conta confirmada.
```
Neste exemplo ilustrativo, a tolerância foi esclarecida como 5 minutos após as 48 horas. Num produto real, confirme-a antes de Plan; um prazo exato de 48 horas exige desenho e testes mais fortes. O agente criará `specs/001-registration/spec.md`. Abra-o e verá uma estrutura semelhante a esta:
```markdown
# Feature Specification: User Registration
**Feature Branch**: `001-registration`
**Created**: 2026-05-31
**Status**: Draft
**Input**: User Description: "I want a registration form..."
## User Scenarios & Testing *(mandatory)*
### Primary User Story
As a new user, I want to register an account with email confirmation,
so that I can access the dashboard with a verified identity.
### Acceptance Scenarios
1. **Given** I am on the registration page,
**When** I submit valid email and password,
**Then** I receive a confirmation email within 1 minute.
2. **Given** I clicked the confirmation link within 48 hours,
**When** I land on the dashboard,
**Then** I see my email confirmed in profile.
3. **Given** não confirmei no prazo de 48 horas,
**When** a limpeza corre nos 5 minutos seguintes,
**Then** a conta é eliminada e o email fica livre para novo registo.
4. **Given** a conta tem menos de 48 horas ou já está confirmada,
**When** a limpeza corre,
**Then** a conta não é eliminada.
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST accept registration via [NEEDS CLARIFICATION:
email/password only, or also SSO/OAuth?]
- **FR-002**: System MUST send confirmation email within 60 seconds
- **FR-003**: A confirmação MUST expirar às 48 horas; o sistema MUST
eliminar contas ainda não confirmadas até 5 minutos depois do prazo
e MUST NOT eliminar contas confirmadas
- **FR-004**: System MUST log all registration attempts for [NEEDS
CLARIFICATION: how long do we retain logs - 30 days, 90 days, forever?]
### Key Entities
- User: email, password_hash, email_verified_at, created_at, deleted_at
- ConfirmationToken: token, user_id, expires_at, used_at
## Success Criteria *(mandatory)*
- **SC-001**: 95% of confirmation emails delivered within 60 seconds (p95)
- **SC-002**: 0 eliminações acidentais de contas confirmadas
- **SC-004**: Nenhuma eliminação antes das 48 horas; todas as contas elegíveis
não confirmadas são eliminadas até às 48 horas e 5 minutos na carga testada
- **SC-003**: Registration completion rate > 60% (from form open to dashboard)
```
Preste atenção aos marcadores `[NEEDS CLARIFICATION: ...]`. O Spec Kit insere-os deliberadamente sempre que o agente não obteve uma resposta inequívoca a partir do seu texto. Antes de avançar para Plan, tem de responder-lhes manualmente em `spec.md` ou executar `/speckit-clarify`; o agente percorre os pontos pouco claros e coloca-lhe perguntas no diálogo.
No Spec Kit, o comando integrado `/speckit-clarify` substitui o «faz-me perguntas» dito em voz alta. O efeito é o mesmo: não avança para Plan até não haver marcadores `[NEEDS CLARIFICATION]` em `spec.md`.
Não deve haver tecnologias em `spec.md`. Nada de referências a React, Postgres, Prisma ou Redis. A especificação descreve o que o sistema faz do ponto de vista do utilizador e do negócio. A pilha tecnológica só surge na fase seguinte.
## O que faz o Claude na fase Plan?
Conclusão principal
O comando `/speckit-plan` recebe a especificação concluída e elabora um plano técnico: que tecnologias utilizar, que arquitetura adotar, que módulos e entidades de dados criar e que contratos de API definir. O plano é escrito em `specs/###-feature/plan.md`, os contratos são exportados para uma pasta `contracts/` separada e o modelo de dados vai para `data-model.md`. Nesta fase, o Claude já conhece a sua pilha tecnológica através do CLAUDE.md e da constitution, pelo que o plano se ajusta ao projeto existente em vez de sugerir «vamos reescrever tudo em Rust».
Quando `spec.md` estiver pronto, execute:
```
/speckit-plan
```
Se quiser, passe diretamente no comando algumas indicações tecnológicas:
```
/speckit-plan Next.js App Router, Prisma, PostgreSQL, Resend for email
```
O Claude lê três fontes: `spec.md`, `CLAUDE.md` (ou `memory/constitution.md`) e o código existente no repositório. O resultado é um `plan.md` com uma estrutura aproximada como esta:
```markdown
# Implementation Plan: User Registration
## Technical Context
- Framework: Next.js 14 App Router
- Database: PostgreSQL via Prisma
- Email: Resend (single transport)
- Validation: Zod schema in shared lib
- Auth: NextAuth.js with credentials provider
## Architecture Decisions
### 1. Token storage
Tokens stored in DB (table ConfirmationToken), not in JWT.
Reason: need server-side revoke on email re-register.
### 2. Email delivery
Async via cron `/api/cron/send-confirmation` triggered immediately
after registration. Retries handled by Resend.
### 3. Auto-delete cron
Executar `/api/cron/cleanup-unconfirmed` a cada minuto. Eliminar só linhas onde
created_at <= NOW() - INTERVAL '48 hours' AND email_verified_at IS NULL.
O exemplo esclarecido permite no máximo 5 minutos de atraso.
Verificar atraso do agendador e tempo de conclusão face a esse limite;
reportar a ultrapassagem como falha, não como limpeza diária bem-sucedida.
## Data Model
See data-model.md
## API Contracts
See contracts/
- POST /api/auth/register
- POST /api/auth/confirm
- GET /api/auth/resend-confirmation
## Implementation Phases
1. Database migration (Prisma schema + migration file)
2. API routes (3 endpoints)
3. UI: registration form + confirmation success page
4. Cron jobs (send + cleanup)
5. Email template
6. Integration tests
```
`data-model.md` descreverá as entidades e as respetivas relações. `contracts/` conterá esqueletos de contratos de API (em OpenAPI YAML ou como tipos TypeScript de pedido/resposta). Não é código — é uma intenção que o Claude converterá mais tarde em rotas reais.
A principal vantagem da fase Plan é o contexto limpo. O Claude não tenta manter simultaneamente na memória a especificação e a implementação. Primeiro reflete sobre o assunto, regista a decisão num ficheiro e só depois avança.
A seguir, há o comando opcional `/speckit-analyze`. É executado depois da fase Tasks e antes de Implement: analisa o conjunto `spec.md + plan.md + tasks.md` à procura de contradições e verifica se o plano e as tarefas abrangem todos os requisitos da especificação. Não altera ficheiros; limita-se a gerar um relatório. É, essencialmente, uma verificação formal antes da implementação.
## Como dividir o trabalho em tarefas (Tasks)
Conclusão principal
O comando `/speckit-tasks` divide o plano em tarefas concretas. Cada tarefa inclui dependências, uma estimativa e um marcador que indica «pode ser paralelizada» ou «estritamente sequencial». O resultado é `tasks.md`, onde as tarefas seguem o formato de lista de verificação `[ ] T-001: ...`. Pode depois entregá-las para implementação com `/speckit-implement` ou convertê-las em GitHub Issues com `/speckit-taskstoissues` — e distribuí-las por uma equipa ou por várias sessões paralelas do Claude Code.
Quando tiver `spec.md` e `plan.md`, execute:
```
/speckit-tasks
```
O Claude expande o plano para `tasks.md`:
```markdown
# Tasks: User Registration
## Phase 1: Database (no dependencies)
- [ ] T-001: Add User model to prisma/schema.prisma (parallel-safe)
- [ ] T-002: Add ConfirmationToken model to prisma/schema.prisma (after T-001)
- [ ] T-003: Generate migration `add-user-registration` (after T-002)
## Phase 2: API contracts (no dependencies)
- [ ] T-004: Create Zod schemas in shared/validation/auth.ts
- [ ] T-005: Define TypeScript types in shared/types/auth.ts (after T-004)
## Phase 3: Routes (depends on Phase 1+2)
- [ ] T-006: Implement POST /api/auth/register
- [ ] T-007: Implement POST /api/auth/confirm
- [ ] T-008: Implement GET /api/auth/resend-confirmation
## Phase 4: UI (parallel with Phase 3)
- [ ] T-009: Build /register page with form
- [ ] T-010: Build /register/confirm/[token] page
- [ ] T-011: Build /register/success page
## Phase 5: Cron + integration (depends on Phase 3+4)
- [ ] T-012: Cron /api/cron/send-confirmation
- [ ] T-013: Cron /api/cron/cleanup-unconfirmed
- [ ] T-014: Email template registration-confirmation.tsx
- [ ] T-015: Testes de integração (Playwright), incluindo limpeza imediatamente
antes das 48h, às 48h exatas, eliminação até 48h 5m, falha por atraso
e proteção de contas confirmadas
## Notes
- T-001, T-004, T-009-T-011 are parallel-safe (different files)
- T-002 conflicts with T-001 (same file: schema.prisma) - run sequentially
- T-006 needs T-003 (migration applied) and T-005 (types)
```
Repare nos marcadores `parallel-safe` e `after T-NNN`. Trata-se do grafo de dependências que permite executar várias fases em paralelo mais tarde. Todo o mecanismo de aceleração do Spec Kit assenta nesta estrutura: algumas tarefas podem ser entregues a cinco sessões diferentes do Claude Code em simultâneo, enquanto outras têm de ser estritamente sequenciais.
O Spec Kit faz isto automaticamente com um único comando, logo à partida.
O comando opcional `/speckit-taskstoissues` recebe `tasks.md` e cria GitHub Issues a partir da lista, cada uma com uma ligação para `spec.md`. É útil se trabalhar em equipa ou quiser acompanhar o progresso através do GitHub Projects.
## Como implementar com subagentes (Implement)
Conclusão principal
A fase final `/speckit-implement` inicia a implementação. O Claude percorre `tasks.md` de cima para baixo e assinala as tarefas com `[x]` à medida que as conclui. Pode executar várias sessões paralelas do Claude Code ao mesmo tempo — uma fase por sessão. Em cada sessão, o Claude lança subagentes para diferentes tipos de trabalho: um revisor de código, um testador de verificações e um redator de documentação para o README. Foi a isto que a Anthropic chamou «1000 subagentes paralelos» quando lançou o Opus 4.8 — no Spec Kit, é simplesmente um modo de trabalho, não um produto separado.
```
/speckit-implement
```
O Claude começa pela primeira tarefa em `tasks.md`. Cada tarefa segue um ciclo curto: ler os ficheiros relevantes, escrever um diff, executar os testes e assinalar `[x]`. Os subagentes são chamados automaticamente quando necessário: um para rever o código, outro para executar o linter e outro para procurar regressões.
E, separadamente, sobre as regras:
No Spec Kit, este ciclo é formalizado. Tem `spec.md` como fonte de verdade, `plan.md` para as decisões técnicas e `tasks.md` como lista de verificação. Se o Claude se desviar em qualquer etapa, volta à especificação e diz: «Isto não corresponde ao FR-003; refaz.» Sem prompts longos a dizer «lembra-te do que discutimos...» — todo o histórico está nos ficheiros.
Se tiver ligado os [Dynamic Workflows no Opus 4.8](https://ailoot.ai/blog/pt-pt/claude-code-dynamic-workflows/), pode colocar o Spec Kit em modo totalmente automático: basta um comando `/speckit-implement` e o Claude paraleliza o trabalho, consolida os resultados e verifica-os. O limite é de 1000 subagentes de cada vez. Para a maioria das funcionalidades, 10–30 são suficientes.
Quando todas as caixas `[x]` estiverem assinaladas e a verificação na secção seguinte devolver «Converged», reveja o PR (ou uma série de PR, se houver muitas tarefas) e faça merge. Os artefactos — `spec.md`, `plan.md`, `tasks.md` — permanecem no repositório como documentação da funcionalidade. Um ano depois, não terá de tentar reconstruir a lógica a partir do código.
## Como verificar se o agente não deixou nada passar (Converge)
Conclusão principal
Depois de Implement, a versão atual do Spec Kit inclui uma etapa de verificação chamada `/speckit-converge`. O agente compara o código concluído com `spec.md`, `plan.md` e `tasks.md`. Se tudo corresponder, responde «Converged» e não altera os ficheiros. Se encontrar omissões, acrescenta-as ao final de `tasks.md` como novas tarefas. Em seguida, execute novamente `/speckit-implement` e depois `/speckit-converge`, até obter «Converged».
```
/speckit-converge
```
Primeiro, o agente apresenta um resumo do que encontrou, com níveis de gravidade, e depois um de dois resultados. «Converged» significa que não há omissões, `tasks.md` permanece rigorosamente igual, byte a byte, e pode avançar para a revisão. «Tasks appended» significa que foram encontradas omissões, que foram acrescentadas à secção Convergence em `tasks.md`, e que o agente lhe diz quantas são.
O Converge não altera nem apaga código; a única escrita que efetua é a adição de novas tarefas a `tasks.md`. Por isso, pode executá-lo sem preocupação, mas apenas depois de `/speckit-implement` ter concluído as tarefas atuais de `tasks.md`. Cada passagem subsequente encontra menos omissões.
## Em que difere o Spec Kit do CLAUDE.md e do Plan Mode?
Conclusão principal
Esta é uma pergunta frequente quando se comparam estas ferramentas. A resposta breve: o CLAUDE.md é o «contrato de trabalho» do agente, uma fonte única de verdade para todo o projeto. O Plan Mode é um planeamento pontual antes de um pedido específico. O Spec Kit cobre todo o ciclo de vida de uma funcionalidade: da descrição à implementação, com artefactos no repositório. Não se substituem entre si; combinam-se num sistema de três camadas: contexto global (CLAUDE.md) → contexto do projeto (constitution do Spec Kit) → contexto da funcionalidade (spec.md + plan.md + tasks.md).
Compare-os segundo 5 características:
| Característica | CLAUDE.md | Plan Mode | Spec Kit |
|----|----|----|----|
| Quando é executado | Em todas as sessões | A pedido (Shift+Tab ou /plan) | Através do comando de barra /speckit-* |
| Duração | Projeto inteiro | Uma sessão | Uma funcionalidade |
| Onde se encontra | Raiz do repositório | No contexto do Claude | `specs/###-feature/*` |
| O que guarda | Stack, regras, glossário | Plano atual + observações | spec + plan + tasks + contracts |
| Modelo | Formato livre (regras do repositório) | Nenhum | Markdown estruturado |
| Melhor função | Regras e stack do projeto | Segunda verificação antes de uma alteração importante | Ciclo completo da funcionalidade: do QUÊ ao CÓDIGO |
Na terminologia do Spec Kit, trata-se de `.specify/memory/constitution.md`. Durante a inicialização, o Spec Kit pode usar o seu CLAUDE.md existente como base para a constitution ou criar um ficheiro separado ao lado dele. Normalmente, mantenho o CLAUDE.md como «contrato» global (stack, glossário, protocolo de implementação) e uso a constitution do Spec Kit para regras específicas da funcionalidade — por exemplo, «todos os formulários são validados através do Zod; não fazer verificações manuais».
A ligação ao Plan Mode é mais simples. O Plan Mode é um modo rápido de «planear antes de escrever código» numa única sessão. Funciona bem para pequenas alterações (corrigir um erro, refatorizar uma função). Para uma funcionalidade grande, o Plan Mode fica aquém porque a janela de contexto de uma sessão é demasiado pequena para um plano de 3000 linhas — como explico diretamente na sessão ao vivo:
O Spec Kit é uma ferramenta concreta de engenharia de contexto. Transfere a «toalha arquitetónica» do chat para ficheiros. O Spec.md permanece no repositório e todas as novas sessões do Claude voltam a lê-lo — não tem de se repetir.
Uma configuração para um projeto grande:
1. **CLAUDE.md** — stack, glossário e o que não fazer. Fica na raiz.
2. **.specify/memory/constitution.md** para o Spec Kit — regras específicas deste fluxo de trabalho.
3. **specs/001-feature-A/spec.md, plan.md, tasks.md** — primeira funcionalidade.
4. **specs/002-feature-B/spec.md, plan.md, tasks.md** — segunda funcionalidade.
5. No trabalho diário, use `/speckit-implement` (para tarefas prontas) ou `/plan` (uma verificação rápida antes de uma alteração).
## Que casos reais estão a funcionar?
Conclusão principal
A abordagem Spec Kit e SDD já produziu resultados mensuráveis em grandes empresas. AWS, num projeto de descoberta de fármacos: 95% da lógica de negócio gerada a partir de uma especificação, poupando mais de 80 horas numa funcionalidade. Rackspace Technology: 52 semanas de trabalho comprimidas em 3 semanas, aumento de eficiência de 90%. O próprio Spec Kit reuniu 107 000 estrelas no GitHub em 8 meses.
Casos concretos:
- **AWS Kiro — agente de descoberta de fármacos.** Numa [publicação do blog AWS Industries](https://aws.amazon.com/blogs/industries/from-spec-to-production-a-three-week-drug-discovery-agent-using-kiro/) datada de 18 de fevereiro de 2026, a equipa descreve o projeto TargetID. Três programadores, três semanas, um agente de descoberta de fármacos. Os números do artigo: o Kiro gerou mais de 95% do código da lógica de negócio, poupando mais de 80 horas de desenvolvimento. Além disso: «A documentação README escrita pelo Kiro poupou-nos cerca de 8 horas» e «40% menos ciclos iterativos de prompt e correção».
- **Rackspace Technology.** No mesmo artigo da AWS, a Rackspace afirma: «concluímos 52 semanas de trabalho estimado em apenas 3 semanas» e «a eficiência aumentou 90%». Já não se trata de uma pequena funcionalidade — é um projeto empresarial completo.
- **Crescimento do GitHub Spec Kit.** O Spec Kit reuniu 107 000 estrelas no GitHub em 8 meses. Este ritmo de crescimento é um sinal claro de que a abordagem está a ganhar quota de mercado.
Para o leitor, isto significa que a abordagem não é teórica: equipas experientes já a utilizam em produção.
## Quando é que o Spec Kit NÃO é adequado?
Conclusão principal
O Spec Kit não é adequado para todos os casos. Tem três contraexemplos claros: pequenas alterações (corrigir um erro, mudar o nome de uma variável), experiências e protótipos (em que não saber o que se pretende é, por si só, a essência do vibe coding) e código legado com estado complexo (em que a especificação fica desatualizada mais depressa do que se consegue terminá-la). Há críticas importantes a estes casos. Vale a pena conhecer os argumentos para não desperdiçar tempo com especificações que não ajudam.
**Não é adequado n.º 1 — pequenas alterações.** Se a tarefa é «mudar o nome de uma variável», «corrigir um erro tipográfico no texto» ou «adicionar um registo», percorrer Specify → Plan → Tasks demora mais do que a própria alteração. Para pequenas alterações, o Plan Mode ou um prompt direto no Claude Code é mais rápido.
**Não é adequado n.º 2 — experiências em direto.** Quando ainda não sabe o que pretende e precisa de «explorar» a interface ou montar rapidamente um protótipo para ver «se resulta», uma especificação não serve de nada. O valor está precisamente na improvisação. Ao nível de «brincar com uma ideia», a improvisação pode ser mais adequada do que uma especificação.
**Não é adequado n.º 3 — código legado com estado complexo.** Um contra-argumento forte: a realidade muda mais depressa do que as especificações. Tome-se como exemplo a faturação de subscrições: a equipa descreveu os ciclos de faturação e as regras fiscais, mas, uma semana depois, o departamento financeiro pediu IVA europeu — a especificação estava desatualizada antes do lançamento. Quando a lógica de negócio evolui rapidamente, manter as especificações torna-se um encargo.
Um risco adicional é a falsa sensação de controlo: as estruturas são elegantes, mas os agentes ignoram muitas vezes as instruções ou, pelo contrário, seguem os modelos demasiado à letra. O resultado é código estruturalmente correto, mas inadequado ao seu repositório específico — a especificação não garante que o agente a tenha entendido como pretendia.
Analistas do setor alertaram para o modelo em cascata: escrever uma especificação extensa antes do código é um caminho que já fez o setor naufragar uma vez, nos tempos dos requisitos de 200 páginas. Desde então, os engenheiros têm abordado esta metodologia com cautela, e essa cautela justifica-se.
**O que fazer.** Sugiro uma regra simples: compare o tamanho da funcionalidade com o tempo necessário para escrever a especificação. Se a implementação de uma funcionalidade demorar menos de 2 horas, não escreva uma especificação — o Plan Mode é mais rápido. Se a funcionalidade demorar uma semana, use definitivamente o Spec Kit; a poupança de tempo compensará cinco vezes a hora gasta na especificação. Entre 2 horas e uma semana, decida conforme o caso, embora eu, pessoalmente, escreva uma especificação até para funcionalidades de meio dia, porque o artefacto no repositório vale mais do que os 30 minutos poupados.
## E agora: como integrar o Spec Kit no seu projeto?
Conclusão principal
O primeiro passo mais simples é experimentar o Spec Kit numa funcionalidade pequena e nova, não num projeto existente inteiro. Instale-o, inicialize-o num repositório, execute `/speckit-specify` para uma funcionalidade e observe os artefactos. Dentro de uma ou duas semanas, terá uma noção de quando o usar e quando continuar com prompts rápidos. A metodologia completa combina CLAUDE.md + Spec Kit + Skills + subagentes.
Um plano concreto para os próximos 7 dias:
- **Dia 1.** Instale o uv e o Spec Kit (5–10 minutos). Confirme que os comandos `/speckit-*` surgiram no Claude Code. Não tente aplicá-los a um projeto existente — comece com um novo.
- **Dia 2.** Escolha uma funcionalidade real que planeia criar. Execute `/speckit-specify` com uma descrição livre. Abra `spec.md`, leia-o e responda a todos os marcadores `[NEEDS CLARIFICATION]`. Não avance precipitadamente para Plan.
- **Dia 3.** Execute `/speckit-plan` com indicações sobre a sua stack. Leia `plan.md`, sobretudo a secção Architecture Decisions. Se algo não lhe convier, edite-o manualmente.
- **Dias 4–5.** Execute `/speckit-tasks` e, em seguida, `/speckit-analyze` para voltar a verificar o conjunto da especificação, do plano e das tarefas; depois execute `/speckit-implement`. Observe como o Claude assinala `[x]` em `tasks.md`. Pode ficar bloqueado em algum ponto — é normal. Volte a `spec.md`, esclareça o requisito e reinicie `/speckit-implement` com uma tarefa específica. Quando as tarefas estiverem concluídas, execute `/speckit-converge` e repita a sequência Implement e Converge até obter a resposta «Converged».
- **Dias 6–7.** Reveja o PR (ou a série de PR). Faça merge. Leia `spec.md` e `plan.md` — serão a documentação da funcionalidade para o próximo ano.
Sugestões de leituras em paralelo:
- [Como configurar o CLAUDE.md em 2026](https://ailoot.ai/blog/pt-pt/claude-md-template/) — a base da constitution do Spec Kit.
- [Plan Mode no Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-plan-mode/) — uma alternativa rápida para tarefas pequenas.
- [Engenharia de contexto em 2026](https://ailoot.ai/blog/pt-pt/context-engineering/) — porque é que o Spec Kit funciona.
- [Skills, Subagents, MCP ou Plugins](https://ailoot.ai/blog/pt-pt/skills-subagents-mcp-plugins-claude-code/) — o que acrescentar ao Spec Kit para o seu fluxo de trabalho.
- [Dynamic Workflows no Claude Code](https://ailoot.ai/blog/pt-pt/claude-code-dynamic-workflows/) — como lançar muitos subagentes ao mesmo tempo durante a fase Implement.
### Fontes
- [GitHub Spec Kit — repositório](https://github.com/github/spec-kit)
- [GitHub Spec Kit — documentação oficial](https://github.github.com/spec-kit/)
- [Spec-Driven Development — texto oficial da metodologia](https://github.com/github/spec-kit/blob/main/spec-driven.md)
- [Modelo de especificação — GitHub](https://github.com/github/spec-kit/blob/main/templates/spec-template.md)
- [Blog AWS Industries — Da especificação à produção: agente Kiro de descoberta de fármacos (18 de fevereiro de 2026)](https://aws.amazon.com/blogs/industries/from-spec-to-production-a-three-week-drug-discovery-agent-using-kiro/)
- [Documentação do Claude Code — Subagents](https://code.claude.com/docs/en/sub-agents)
- [Documentação do Claude Code — Skills](https://code.claude.com/docs/en/skills)
- [Documentação do Claude Code — Commands](https://code.claude.com/docs/en/commands)
O fluxo de trabalho completo com contexto: clone de IA + Second Brain + engenharia de contexto.
Há mais materiais disponíveis em [Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### Porque não basta uma limpeza diária para eliminar às 48 horas?
Uma conta que atinge o prazo logo após a execução pode esperar quase outro dia. Esclareça a tolerância na especificação, escolha um horário compatível e teste o limiar de 48 horas e o atraso máximo.
### O que faço se plan.md contradizer spec.md?
Volte ao requisito e resolva antes de implementar. Atualize especificação, plano, tarefas e aceitação em conjunto e use Analyze e as verificações para confirmar o mesmo comportamento acordado.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.