Communitygithub.com

strandic/skills

Habilidades da Strandic para construir software com agentes de IA, de forma deliberada. Instale via npx skills add strandic/skills ou pelo marketplace do Claude Code.

O que é skills?

Este skill define um método estruturado para construir software com agentes de IA, organizado em uma sequência de **gates** (portões). Cada etapa do desenvolvimento produz um artefato pequeno e específico, e então para em um gate que _você_ — o humano — deve liberar explicitamente antes que a próxima etapa comece. O agente nunca avança um gate por conta própria, evitando geração de código 'slop' e garantindo que cada decisão seja revisada antes de prosseguir. O método é mais adequado para mudanças estruturais de médio porte, onde um design errado seria caro, mas a mudança é pequena o suficiente para não ser sufocada pelos gates. Os passos vão desde pesquisa e planejamento (etapa 0) até a verificação em dados reais (etapa 7), com ênfase em artefatos verificáveis (código, tipos, assinaturas, marcadores TODO, relatórios) em vez de prosa descritiva. O skill é instalado via `npx skills add strandic/skills` ou pelo marketplace do Claude Code, e funciona como um guia processual que o agente segue para garantir qualidade e rastreabilidade.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add strandic/skills

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Construa um recurso como uma sequência de portões. Cada etapa produz um pequeno artefato e, em seguida, para em um portão que você — o humano — libera antes que a próxima etapa comece. O agente nunca avança um portão sozinho. Um agente que auto-certifica suas etapas colapsa todo o método de volta à geração de 'slop' comum; os portões são o método.

O planejamento só termina quando a implementação se torna mecânica — o recurso construtível apenas a partir dos artefatos, sem precisar ir a nenhum outro lugar. Se não for possível, um artefato anterior estava errado: volte e corrija-o antes de prosseguir.

Como executar

Uma etapa por turno. Produza o artefato da etapa, apresente-o e pare no portão. Não comece a próxima etapa até ouvir um prosseguir explícito. Se você não ouviu, você ainda está na etapa atual.

Isso merece os portões?

Faça uma triagem antes de começar — o método é ajustado para mudanças médias e estruturais:

  • Pule — uma correção de uma linha, uma edição mecânica, um ajuste na documentação. Diga isso e pare; os portões não valerão seu custo.
  • Decomponha primeiro — um marco, uma épica ou um objetivo vago. O método se encaixa em uma mudança estrutural média, não em um programa de trabalho. Divida-o e, em seguida, execute o método em um único filho. Pesquisa onde o design é a entrega não se qualifica — você não pode planejar mecanicamente o que ainda está descobrindo.
  • Execute — um design errado seria caro, mas a mudança é pequena o suficiente para que os portões não a sufoquem.

Defina o lar do artefato

Antes da etapa 0, decida onde os artefatos da etapa viverão neste repositório (ex.: docs/handoffs/<recurso>/) e nomeie-o — sem nome, eles improvisam sua própria localização. Vincule seu rastreador à palavra do revisor: uma etapa é concluída quando o humano libera seu portão, nunca quando o artefato meramente aparece.

As etapas

  • 0 — pesquisa e planejamento. Leia o código e as restrições. Produza: escopo, posicionamento do módulo, estratégia de teste, as perguntas em aberto para o humano e a pergunta de estilo — o estilo do artefato corresponde ao estilo da casa? Designs errados morrem mais baratos aqui. Portão.
  • 1 — estruturas de dados. Os tipos e nada mais. Portão.
  • 2 — interfaces. Assinaturas e nada mais — uma função pura por unidade de comportamento onde o domínio permitir. Cada parâmetro que é um identificador de tempo de execução — um recurso vivo que a assinatura recebe em vez de construir — deve nomear quem constrói a instância real no ambiente real, ou ser sinalizado como uma junta aberta: uma dependência injetada é lida como limpa precisamente porque adia essa pergunta, então nenhuma dependência não fornecida chega a uma etapa posterior sem ser sinalizada. Portão.
  • 3 — tarefas pendentes. Coloque um marcador literal (um comentário TODO) no código-fonte em cada local onde o código mudará — enumerados, não descritos. Uma lista em um documento de planejamento não satisfaz esta etapa: os marcadores vivem no código para que a etapa 4 possa implementar diretamente sobre eles, e sua ausência é pesquisável com grep. Cada local, ou a etapa não está concluída. Portão.
  • 4 — reconhecimento: simular, executar, reverter, relatar. Implemente sobre as tarefas pendentes, execute contra dados reais, então reverta tudo e mantenha apenas um relatório de onde o plano quebrou. A saída é informação, não código, e o relatório recebe o mesmo portão que qualquer artefato. Teste a técnica, não apenas o design: leve o mecanismo real da simulação para o relatório — um plano pode nomear uma técnica plausível, mas errada, que ainda se encaixa nas interfaces, então apenas uma tentativa real revela o mecanismo que é o mais simples e correto. Execute o caminho inteiro, não uma cesta de testes: inicie a execução real na entrada verdadeira e use o componente real em cada salto — um intermediário fornecido manualmente não é um atalho, mas uma bandeira vermelha marcando uma junta não testada, e um conjunto de testes direcionados só pode desconfirmar os riscos que você pensou em listar, enquanto uma execução ponta a ponta não pede permissão às suas suposições. Uma parte reutilizada como está em um novo tempo de execução ou contexto é um alvo de reconhecimento, não uma garantia — "inalterado" vale apenas no ambiente para o qual foi construído. O reconhecimento é executado em dados reais e vazamentos de dados reais: o relatório carrega agregados e estrutura, nunca identidades ou conteúdo real. Portão.
  • 5 — invariantes. Você os declara; o agente apenas conecta e os aplica — a autoria não pode ser delegada, porque um invariante é uma decisão pré-acordada sobre uma disputa futura. Dê à aplicação a mesma passagem adversarial que as regras que ela policia: uma verificação que pode gerar falso positivo corrói a lei que aplica. Portão.
  • 6 — implementar. Mecânico se as etapas anteriores fizeram seu trabalho — digitar, não decidir. Uma decisão de design surgindo aqui é um defeito em um artefato anterior: pare e volte. Antes de implementar, coloque a bifurcação frio/quente para o humano como uma decisão de portão necessária — nunca presuma: frio entrega a etapa 6 para um novo contexto (uma nova sessão ou um subagente) carregando apenas os artefatos da etapa + verificações invariantes, para que os artefatos sozinhos conduzam a construção e o método em si seja validado; quente implementa no contexto atual, adequado quando você só quer entregar. Concluído quando os invariantes da etapa 5 são válidos. Portão.
  • 7 — estado final em dados reais. Entregue apenas quando todos os três forem válidos: os invariantes são válidos em produção, o recurso faz algo real que nenhuma ferramenta existente poderia fazer, e existe um artefato de cobertura (um runbook ou lista de verificação de entrega lida neste portão). Fixtures codificam sua imaginação; dados reais codificam a realidade. Portão.

Entregáveis

Entregue a cada portão algo inspecionável — um diff, um grep, um arquivo — não prosa que apenas descreve o trabalho; um artefato verificável torna sua própria ausência óbvia. A forma do artefato difere por etapa, então não padronize cada etapa como um documento de planejamento:

0 um plano · 1 os tipos · 2 as assinaturas · 3 marcadores TODO no código-fonte (pesquisáveis com grep) · 4 um relatório, código revertido · 5 o invariante + sua verificação no código · 6 a implementação · 7 comportamento ao vivo + um runbook.

Uma etapa cujo artefato vive no código (3, 4, 6) não é satisfeita por um documento sobre ele. Se você não consegue apontar para o entregável e verificá-lo, a etapa não está concluída.

Modos de falha

  • Portão carimbado — um portão revisado sem atenção dá a sensação de propriedade sem a substância. A densidade do portão deve seguir a irreversibilidade: colapse portões sobre artefatos baratos e refazíveis, mas nunca colapse pesquisa (0), reconhecimento (4) ou o estado final (7).
  • Correndo para o diff — correndo em direção à etapa 6 enquanto uma etapa anterior está aberta. Ver uma etapa posterior não é licença para começar; cada etapa produz apenas seu próprio artefato.
  • Auto-certificação — o agente declarando um portão liberado. Apenas o humano libera um portão.
  • Confiar na metade entregue — reutilizar uma parte que já existe e passou seus próprios testes, em um novo tempo de execução ou contexto, sem testar novamente a junção. "Já funciona" era verdade em algum outro lugar; a junta onde você a conecta é nova e não pertence a nenhum dos lados, então é exatamente aí que a lacuna não testada se esconde.

Habilidades Relacionadas