rbikbov/frontend-starter

Processo de desenvolvimento de funcionalidades com agente: PRD com Non-Goals → especificação compacta → tarefas, uma por commit → pesquisa somente leitura → tracer bullet → build com teste primeiro → revisão independente por subagente → verificação no navegador. Use quando solicitarem uma funcionalidade, tela, cenário de usuário ou mudança significativa de comportamento; quando for necessário escrever um PRD, especificação ou dividir o trabalho em tarefas; quando o trabalho exigir mais de um commit. Não use para corrigir erros de digitação ou ajustes de uma única linha.

O que é frontend-starter?

Este skill define um workflow estruturado para desenvolvimento de features front-end com agentes de IA. O principal princípio é minimizar decisões autônomas do agente para aumentar a estabilidade dos resultados. Cada fase do processo gera um artefato na pasta `docs/features/<slug>/` e possui um checkpoint de validação ("portão"), sendo que em fases marcadas, a progressão depende de aprovação humana. O fluxo inclui 9 fases: Preparação, PRD, Especificação, Tarefas, Pesquisa, Tracer bullet, Build, Revisão e Verificação no navegador. O skill suporta ferramentas como Next.js, Playwright e sistemas de revisão por subagentes. É ideal para tarefas complexas que exigem mais de um commit, evitando uso em correções triviais. O workflow garante que cada commit seja autossuficiente e que a especificação viva junto com o código, atualizada em cada mudança de comportamento.

Funciona com✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/rbikbov/frontend-starter/tree/HEAD/.claude/skills/feature-workflow

Documentação

Processo de feature

Princípio fundamental: quanto menos decisões o agente tomar sozinho, mais estável o resultado. Cada fase termina com um artefato em docs/features/<slug>/ e uma verificação ("portão"). Onde indicado, a transição só ocorre após confirmação humana.

Como escrever o código — fsd-frontend; verificação de lixo — anti-slop-review; entrada e sessão — frontend-auth-session.

1. Fases

#	Fase	Artefato	Aprova	Portão
0	Preparação	branch	—	Árvore de trabalho limpa; após instalação de dependências e migrações — `/clear`
1	PRD	`prd.md`	humano	Non-Goals preenchidos; critérios verificáveis; nenhuma solução técnica
2	Especificação	`spec.md`, até 150 linhas	humano	Cobre todos os critérios do PRD e nada além
3	Tarefas	`tasks.md`	humano	Uma tarefa — um commit; a primeira — tracer bullet
4	Pesquisa	registro em `tasks.md`	—	Somente leitura; encontrado o que reutilizar
5	Tracer bullet	commit	—	Um cenário percorre todo o fluxo e é visto no navegador
6	Build	commit por tarefa	—	Teste primeiro para lógica; `pnpm check` verde
7	Revisão	relatório `reviewer`	humano por achados	Achados confirmados corrigidos
8	Navegador	e2e no caminho crítico	—	Cenários do PRD passam sem erros no console

Tarefa pequena (um commit, sem novo comportamento para o usuário) pula as fases 1–3, mas os Non-Goals ainda são registrados na descrição da tarefa. A omissão de fase é comunicada em voz alta, não ocorre silenciosamente.

2. PRD

Template — docs/features/_template/prd.md.

O agente elabora um rascunho a partir da solicitação e pergunta apenas o que é indispensável para continuar. O restante são suposições em "Perguntas em aberto", que o humano confirma ao aprovar.
Non-Goals são obrigatórios. Liste o que o agente teria vontade de fazer "de quebra": responsivo para novos tamanhos, animações, i18n, cache, painel administrativo, refatoração de código vizinho. Sem essa lista, a feature cresce.
Critérios de prontidão verificáveis: "Dado / Quando / Então", não "confortável" e "rápido".
Nenhuma biblioteca, arquivo ou esquema: é questão de "o quê e por quê", não "como".

3. Especificação

Template — docs/features/_template/spec.md.

Até 150 linhas. Redigida pelo agente, aprovada pelo humano. Uma especificação longa gerada é pior que nenhuma: ela entope o contexto e dilui as decisões.
Antes de escrever — uma breve revisão somente leitura das camadas afetadas: o que já existe, o que reutilizar.
Contém: onde o código vive (camadas, slices), contratos de dados (schemas zod, mapeamento DTO), API (entrada, saída, erros → kind), estados de UI, casos limite, cenários de aceitação com nível de teste.
A especificação vive junto com o código. Comportamento alterado — corrige-se spec.md no mesmo commit. Código que diverge da especificação é defeito de um dos dois.

4. Tarefas

Template — docs/features/_template/tasks.md.

Uma tarefa — um commit, após o qual o projeto compila e as verificações passam. Se o agente entrar num beco sem saída, reverter para o commit anterior é mais barato que discutir com o modelo.
A tarefa cabe em uma única sessão; cada uma tem "pronto quando".
A primeira tarefa é o tracer bullet; em seguida, estados, casos limite, polimento.

5. Pesquisa (somente leitura)

Antes de cada tarefa, sem alterar arquivos:

AGENTS.md das pastas afetadas;
código existente que resolve algo similar (rg por nomes e contratos);
contratos e tipos dos quais a tarefa depende.

Se o encontrado for necessário depois — 2–3 linhas no registro tasks.md.

6. Tracer bullet

Um cenário de ponta a ponta: rota → página → feature ou entidade → request() → route handler ou backend → resultado na tela.

É código de produção, não protótipo: camadas corretas, contratos reais da especificação.
Conscientemente sem: validação detalhada, polimento de estados de carregamento e erro, estilos, casos limite.
Backend não está pronto — handler MSW ou route handler que retorna dados conforme o contrato da especificação; isso é anotado em tasks.md.
Verificação — no navegador: o cenário passa e não há erros no console.

7. Build

Lógica — teste primeiro: funções puras, stores, mapeamento de respostas, hooks com ramificações. O teste deve falhar pelo motivo esperado, depois o código. Teste escrito depois do código tende a verificar o que o código faz, não o que é exigido.
Layout e estilos — sem teste antecipado: são verificados pelo navegador (fase 8), o caminho crítico é coberto por e2e.
Após a tarefa: pnpm check, commit (lint-staged verificará os arquivos alterados).
Parada: três tentativas frustradas de corrigir o mesmo problema — pare. Descreva ao humano o que tentou e qual a hipótese. Não ajuste testes para se adequar ao código, não desative regras de linter, não enfraqueça tipos.
Tudo que está fora da tarefa vai para o registro "depois", não neste commit.

8. Revisão

Subagente reviewer (.claude/agents/reviewer.md) com contexto limpo: passe o caminho para prd.md e spec.md e o intervalo de commits; o diff ele lê sozinho. O autor do código enxerga pior seus próprios erros: em seu contexto estão os argumentos de por que a solução está correta.
Achados confirmados são corrigidos; os controversos, o humano decide.
Segurança também é verificada pelo humano: login, sessões, redirecionamentos, cookies, entrada do usuário em HTML. Verificações verdes não garantem isso: na prática, um redirecionamento aberto passou nos testes, e uma página de erro ilegível passou pelo linter.

9. Navegador

Next.js: skill next-dev-loop com agent-browser, se instalado; senão, Playwright ou Chrome DevTools MCP.
Execute os cenários do PRD, incluindo os negativos: dados vazios, erro de rede, reenvio. Observe o console e os status das requisições.
Para UI — tema claro e escuro, largura de telefone.
Caminho crítico — teste e2e em e2e/.
Pronto quando cada critério do PRD estiver verificado; na mensagem final — lista de critérios e como cada um foi verificado.

10. Contexto

O estado do trabalho reside em docs/features/<slug>/, não na conversa: comece uma nova sessão lendo prd.md, spec.md, tasks.md.
Após etapas ruidosas (instalação, migrações, logs longos) — /clear.
Experimentos paralelos — em git worktree, não na branch de trabalho.

11. O que não fazer

Perguntas de esclarecimento infinitas: pergunte apenas o que bloqueia; o restante são suposições no PRD.
Orquestradores com muitos agentes: basta um executor e um revisor.
Especificações e documentação que ninguém aprovou nem lê.
Omissão silenciosa de fases e "aproveitei e corrigi".