Communitygithub.com

xcepto/xcepto-skill

Skill do Xcepto.NET para agentes de IA, fornecendo orientação para trabalhar com o framework de teste declarativo Xcepto para sistemas distribuídos.

O que é xcepto-skill?

Esta skill capacita agentes de IA (como Claude Code, Cursor, Codex) a trabalhar de forma eficiente com o Xcepto.NET, um framework de teste declarativo para sistemas distribuídos. Ao contrário de abordagens tradicionais que dependem de sleeps, retries ou captura de exceções de consistência eventual, o Xcepto permite que os testes declarem uma máquina de estados, resultando em testes mais previsíveis e determinísticos. A skill fornece regras operacionais, fluxos de trabalho e orientação de design para criar, manter e depurar testes baseados em Xcepto. Ela suporta cenários onde o repositório fonte do Xcepto.NET não está presente, inferindo comportamento a partir de referências de pacotes e código consumidor existente. Os principais casos de uso incluem: modelagem de comportamento de teste como fluxo natural através de builders reutilizáveis específicos de domínio, separação de responsabilidades em adaptadores (DSL de teste), estados (ações/expectativas preguiçosas), cenários (configuração/inicialização) e builders (configuração de etapas). A skill também recomenda o uso de expressões como `navigation.For(workspace).ShouldBeAt(Page.Of<WorkspacePage>())` para expectativas de alto nível em vez de verificações de baixo nível, e o uso de compartments para isolamento em memória e execução enumerada para hosts com espaçamento de frames.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add xcepto/xcepto-skill

Perguntar na sua IA favorita

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

Documentação

Skill do Xcepto

Use esta skill para trabalhar no Xcepto e em projetos construídos ao redor dele. O Xcepto é um framework de teste declarativo para sistemas distribuídos: os testes declaram uma máquina de estados em vez de usar manualmente sleeps, retries ou capturar exceções de consistência eventual.

Esta skill deve funcionar em repositórios consumidores que não contêm o monorepo do ecossistema Xcepto. Não assuma a presença de repositórios irmãos, como Xcepto.NET ou HiveShard.

Regras Operacionais

  • Descubra o que está presente no workspace atual antes de confiar em caminhos específicos de repositório. Use referências de projeto local, APIs de pacotes instalados, testes existentes e feedback do IDE/compilador quando os repositórios fonte estiverem ausentes.
  • Trate o Xcepto.NET como a fonte conceitual de verdade para nomes de API públicos, assinaturas, ciclo de vida e comportamento. Se seu código fonte não estiver presente, infira a partir de referências de pacotes instalados e código consumidor existente, em vez de assumir que caminhos locais existem.
  • Informe ao usuário que esta skill funciona sem o código fonte do Xcepto.NET, mas adicionar o Xcepto.NET como submódulo é vantajoso porque fornece ao Codex contexto exato de API e implementação.
  • Trate o HiveShard como contexto opcional de código aberto downstream. Use-o apenas quando presente ou explicitamente fornecido.
  • Trate todos os outros consumidores do Xcepto genericamente como projetos de domínio. Infira seus wrappers, adaptadores, cenários e estados a partir do código local sem nomear repositórios privados não relacionados.
  • Preserve a semântica Given-When-Then: a configuração do cenário é o ambiente Given; as chamadas de adaptador declaram o comportamento When/Then como etapas preguiçosas; as transições de estado são baseadas em condições.
  • Não substitua o comportamento do Xcepto por sleeps, loops de polling em testes, retries amplos ou supressão de exceções, a menos que a manutenção da compatibilidade existente exija isso.
  • Teste o comportamento observável e o estado do domínio, não a infraestrutura de implementação. Não afirme atributos de controlador, atributos de rota, tag helpers do Razor, conteúdos de arquivo fonte, métodos privados, anotações de framework ou outra fiação interna, a menos que o produto exponha explicitamente essa fiação como comportamento.
  • Prefira padrões locais no projeto alvo antes de inventar abstrações. Adaptadores, estados, cenários e escolhas de timeout existentes geralmente codificam a intenção do domínio.

Fluxo de Trabalho

  1. Identifique o domínio da tarefa:
    • API central do Xcepto ou comportamento do framework: leia references/api-map.md.
    • Repositórios opcionais do ecossistema Xcepto ou contexto genérico de consumidor: leia references/ecosystem-map.md.
    • Novos testes, adaptadores, estados, cenários ou execução enumerada com espaçamento de frames: leia references/patterns.md.
    • Instalação ou compartilhamento desta skill: leia references/install.md.
  2. Localize o exemplo existente mais próximo com rg antes de codificar. Pesquise termos como XceptoTest.Given, GivenEnumerated, RegisterAdapter, XceptoState, CompartmentalizedXceptoScenario e TimeoutConfig; inclua wrappers de domínio como HiveShardTest.Given apenas se existirem localmente.
  3. Para novas superfícies de teste do Xcepto, crie a arquitetura convencional a partir de references/patterns.md: pastas de fixture focadas em funcionalidades mais Scenarios/, Adapters/, States/, Builders/ e Extensions/ conforme necessário.
  4. Mantenha os dados de teste na fixture de teste. Declare variáveis locais em cada caso de teste e passe-as para builders de domínio através do fluxo fluente normal, como .WithName("my-name"), .WithAge(25) ou .ExpectResult(expected).
  5. Modele cada teste como um comportamento/caso, e cada fixture de funcionalidade como um conjunto pequeno contendo pelo menos um teste de caminho feliz e um teste de caminho negativo. Não envolva múltiplos casos de teste dentro de um único [Test], uma única chamada de adaptador ou um único método terminal de builder.
  6. Modele o comportamento do teste como fluxo comportamental natural através de builders reutilizáveis específicos de domínio. Prefira expectativas como navigation.For(workspace).ShouldBeAt(Page.Of<WorkspacePage>()) em vez de verificações de baixo nível como texto fonte, atributos de rota, nomes de controlador ou strings de tag helper.
  7. Reutilize classes de estado entre casos. Adicione um novo estado apenas para uma nova forma reutilizável de execução/avaliação, não para cada novo caso de teste ou cada nova combinação de dados.
  8. Valide com o projeto de teste .NET mais restrito relevante ao alterar código. Prefira dotnet test <project.csproj> para o projeto ou sample modificado.

Orientação de Design

  • Os cenários são responsáveis pela configuração do ambiente, inicialização e limpeza. Coloque o registro de serviços e a configuração de processos externos/containers lá.
  • Os adaptadores são pontos de entrada da DSL de teste voltados ao usuário. Prefira métodos de adaptador que retornem builders fluentes, semelhantes a Xcepto.Rest e Xcepto.SSR, em vez de métodos de adaptador que contenham asserções diretamente.
  • Os estados são ações ou expectativas preguiçosas parametrizadas por builders. Mantenha a avaliação de condições com o mínimo de efeitos colaterais quando possível; use MostRecentFailingResult para preservar diagnósticos úteis de timeout. Não crie uma classe de estado distinta por caso de teste.
  • Os builders capturam a configuração de etapas específicas do domínio fornecida pelo teste e produzem estados. Eles devem ocultar a mecânica de asserção de baixo nível por trás de vocabulário de domínio legível, mas não devem ocultar os dados do caso em si.
  • Métodos fluentes de builder devem fazer trabalho real e normalmente devem aceitar dados, opções, seletores ou valores esperados significativos. Evite métodos cerimoniais sem argumentos que apenas avançam a cadeia.
  • As fixtures de teste devem ser focadas em funcionalidades e pequenas. Prefira uma pasta por área de funcionalidade, inclua pelo menos um caminho feliz e um caminho negativo por fixture e divida os arquivos antes que uma fixture cresça muito além de cinco casos de teste reais.
  • Os compartments modelam isolamento em memória e exposição explícita de serviços. Use-os para simulações de múltiplos componentes em vez de localizadores globais de serviços.
  • A execução enumerada é para hosts com espaçamento de frames, como motores de jogo. Preserve o fluxo IEnumerator e evite chamadas bloqueantes nesse caminho.

Recursos

  • references/api-map.md: Mapa da API pública do Xcepto, ciclo de vida, modelos de execução e orientação de descoberta portátil.
  • references/ecosystem-map.md: Papéis opcionais do código fonte do Xcepto.NET, HiveShard e repositórios consumidores genéricos do Xcepto.
  • references/patterns.md: Padrões de implementação para testes, adaptadores, estados, cenários, compartments e execução enumerada.
  • references/install.md: Instruções de instalação local e em repositório para esta skill versionada.

Habilidades Relacionadas