sigmastudioz/agent-skills

Design Orientado a Domínio Liderado por Principal

Por Lex da SigmaStudioz.

Torne a propriedade de negócio óbvia a partir de caminhos, nomes, contratos e dependências. Otimize para comportamento correto, mudança legível, desempenho medido e evolução econômica. Aplique esta habilidade à alteração solicitada; não é autorização para redesenhar o projeto.

Execução automática

Aplique esta linha de base antes de planejar ou editar código de produção; não aguarde uma invocação da habilidade, frasse de ativação ou solicitação de arquitetura. Execute implementação autorizada, reutilização, correção de lacunas, verificação e transferências como parte da tarefa de codificação, em vez de apenas sugeri-los. Para tarefas apenas de revisão ou planejamento, aplique o mesmo raciocínio sem editar código. Mantenha o trabalho proporcional ao escopo e ao risco; o uso automático não autoriza alterações não relacionadas ou delegação.

Portabilidade e transferências de agente

Estas são instruções independentes de ferramenta para agentes que podem ler Markdown e inspecionar um projeto. Use ferramentas de pesquisa, construção, teste e tempo de execução disponíveis; nenhum fornecedor, plugin ou CLI específico é necessário. Respeite a hierarquia de instruções, permissões e escopo explícito da tarefa do host. Esta habilidade não habilita capacidades desativadas nem concede permissão para implantar, publicar ou fazer alterações destrutivas.

Quando a delegação já estiver autorizada, passe o caminho acessível da habilidade ou instruções relevantes, arquivos/módulos próprios, condições de aceitação e obrigações de rastreamento na atribuição. Não presuma que um agente filho herda a conversa, habilidades carregadas ou arquivos de instruções globais do pai. Exija evidências e arestas não resolvidas de volta de cada trabalhador; reconcilie rastreamentos entre limites de trabalhadores. Delege invariantes verificadas; rotule algoritmos propostos como suposições e desafie contradições. Se o filho não puder ler a habilidade, forneça seu conteúdo relevante dentro do contexto permitido. Não crie agentes apenas porque esta seção descreve transferências. Antes de adotar outro fluxo de trabalho, registre a contagem de colegas de equipe e funções autorizados pelo usuário. Cada agente de exploração, implementação e revisão consome esse orçamento; revisões de acompanhamento permanecem no coordenador quando ele estiver esgotado. Habilidades opcionais de fluxo de trabalho não podem expandir o limite do usuário. Trate briefs de tarefas e pseudocódigo como propostas: verifique independentemente seus algoritmos em relação ao contrato original. Corrija um plano falho em vez de preservá-lo como um requisito de implementação.

Contrato de transferência

Cada atribuição de agente autorizada ou transferência retomável deve identificar:

Campo	Contexto obrigatório
Objetivo e limites	Resultado do usuário, verificações de aceitação, ações autorizadas, exclusões
Localização	Raiz do workspace acessível, branch/worktree ou revisão real, caminhos de instrução/habilidade relevantes
Propriedade	Arquivos/módulos exatos que o agente possui; outros proprietários ativos e dependências de interface compartilhada
Arquitetura	Proprietário do domínio, pontos de entrada/contratos públicos, caminhos importantes de chamadores e consumidores
Estado atual	Trabalho implementado versus pendente, edições locais, decisões e por que, falhas conhecidas
Evidência	Comandos e resultados, caminhos/IDs do registro de rastreamento, revisão verificada, ambientes indisponíveis
Próxima ação	Próximo passo concreto, bloqueadores, entradas necessárias e formato de retorno esperado

Os hosts podem aplicar este contrato com o guardião de delegação. O guardião opcional do Claude fornece esta linha de base e verifica limites numéricos explícitos de agentes nas turnas nativas do usuário (Use N colegas/agentes/trabalhadores); histórico ausente deixa a aplicação para o coordenador. Ele não concede ferramentas nem garante correção semântica. Quando esse guardião estiver instalado, prefixe a atribuição com HANDOFF_JSON= e um objeto JSON contendo goal, limits, workspace, revision, owns, interfaces, state, evidence, next, return, trace, checks e baseline. return deve ser um objeto com paths, contracts, checks, gaps e remaining não vazios. trace nomeia caminhos e casos de falha a serem seguidos; checks nomeia verificações a serem executadas ou por que indisponíveis. baseline é o caminho acessível desta habilidade. Isso se aplica a atribuições de exploração e revisão também. Uma atribuição rejeitada deve ser corrigida antes de tentar novamente.

Use caminhos reais no host do agente receptor; inclua o conteúdo necessário quando os caminhos forem diferentes ou inacessíveis. Forneça comandos com seu diretório de trabalho e nomes de configuração não secretos obrigatórios. Nunca coloque credenciais ou cargas de tempo de execução privadas em notas de transferência. Um nome de branch sozinho não é prova de que um filho vê trabalho não commitado; estabeleça se o checkout é compartilhado ou isolado.

Para trabalho concorrente, concorde com contratos públicos e propriedade de arquivos antes de alterações sobrepostas. Diga aos agentes que eles não estão sozinhos: preserve as edições de outros e coordene arquivos compartilhados através do proprietário atribuído. Rebase ou reconcilie alterações isoladas antes de reivindicar integração; não descarte trabalho silenciosamente. Ao retornar, reporte caminhos alterados, mudanças de contrato público, verificações com resultados, IDs/lacunas e ações restantes. O coordenador reconcilia o registro de rastreamento e verifica as costuras entre agentes e consumidores afetados; várias verificações de trabalhadores bem-sucedidas não estabelecem um fluxo de trabalho integrado funcional.

Para interrupção ou perda de contexto, salve a transferência no registro de tarefa/rastreamento existente com um carimbo de data/hora e revisão de conteúdo, depois vincule esse registro. Ao retomar, inspecione o checkout e o diff atual antes de agir; revalide suposições desatualizadas. Não crie uma segunda fonte de verdade da tarefa.

A instalação local não implica instalação em nuvem, host remoto ou agente não relacionado. Estabeleça descoberta em cada host de execução; use uma instrução global nativa do host para rotear o trabalho relevante aqui. Se a descoberta ou acesso a arquivos estiver indisponível, reporte esse limite em vez de reivindicar aplicação global.

Contrato principal de engenharia

• Comece com capacidades de negócio, invariantes, fluxos de trabalho do usuário e restrições operacionais.
• Prefira alta coesão dentro de domínios e baixo acoplamento entre eles.
• Coloque código específico de domínio com seu proprietário; agrupe código por função dentro desse limite.
• Dê a cada regra de negócio e modelo de escrita autoritativa um proprietário claro.
• Reutilize implementações existentes antes de adicionar outra; evite duplicar conhecimento de negócio.
• Escolha a menor arquitetura que atenda às necessidades demonstradas e suporte a mudanças prováveis.
• Separe observações, suposições, decisões e evidências. Não invente requisitos ou benchmarks.
• Preserve o comportamento público funcional durante mudanças estruturais, a menos que uma mudança de comportamento seja solicitada.
• Melhore o caminho tocado e suas dependências necessárias. Não varra código não relacionado para a tarefa.

1. Estabeleça contexto antes de editar

Inspecione instruções aplicáveis do repositório, manifestos, exportações de pacotes, pontos de entrada, módulos de domínio existentes, migrações, testes e evidências de tempo de execução relevantes. Pesquise por comportamento equivalente e pacotes compartilhados existentes antes de criar arquivos. Use a linguagem e as ferramentas do repositório.

Rastreie um fluxo de trabalho relevante da entrada do usuário ou evento até autorização, serviço, regras de domínio, persistência, efeitos downstream e estado retornado ou exibido. Inclua caminhos de erro. Identifique consumidores e gravadores reais; um nome de diretório sozinho não estabelece propriedade.

Para trabalho de arquitetura substancial, estabeleça um quadro de decisão compacto:

Pergunta	Resposta obrigatória
Resultado de negócio	Qual fluxo de trabalho do usuário ou invariante muda?
Propriedade	Qual contexto limitado possui o significado e as gravações autoritativas?
Consumidores	Quais aplicativos, jobs, módulos ou sistemas externos precisam da capacidade?
Restrições	Compatibilidade, volume de dados, latência, locação, disponibilidade, custo, implantação?
Evidência atual	Caminhos, contratos, falhas, tempos ou comportamento de consulta relevantes?
Menor mudança	O que pode ser reutilizado, e qual limite realmente precisa mudar?
Conclusão	Condições de aceitação observáveis e verificação apropriada?

Pergunte apenas quando uma decisão de negócio não resolvida bloquear o trabalho correto; caso contrário, declare suposições.

2. Defina os limites do domínio

Um contexto limitado possui um vocabulário, regras e modelo de negócio coerentes. Um recurso, tabela, tela, camada de framework, implantação ou nome de equipe não é automaticamente um contexto limitado. Use nomes de capacidade de negócio como billing (faturamento), scheduling (agendamento), playback (reprodução) ou execution (execução).

• Separe contextos quando o mesmo termo tiver significados diferentes, invariantes, ciclos de vida ou proprietários.
• Mantenha entidades juntas quando sua invariante deve ser aplicada em uma operação atômica.
• Evite agregados superdimensionados: distinga invariantes atômicas verdadeiras de fluxos de trabalho entre contextos que precisam de consistência explícita, orquestração ou compensação em vez de uma transação compartilhada.
• Diferencie a diferenciação central de negócio das capacidades de suporte e commodity.
• Invista esforço de modelagem onde a complexidade ou o valor de negócio justificar; mantenha CRUD simples.
• Registre propriedade upstream/downstream e tradução em limites de contexto importantes.
• Consuma outro contexto através de sua API pública, porta ou contrato; não importe seus internos.
• Traduza modelos externos/de provedor no limite em vez de vazá-los para regras de negócio.
• Prefira um monolito modular até que implantação independente, escalonamento, isolamento de falhas ou propriedade justifiquem uma divisão em serviços. Um monorepo não implica microsserviços.

Se uma mudança abranger domínios, identifique o caso de uso orquestrador e a responsabilidade de cada domínio. Coloque a orquestração com o proprietário do fluxo de trabalho, não em um helper global ou componente de UI.

3. Estruture por domínio, depois por função

Escolha o escopo proprietário primeiro, depois a categoria funcional. Dentro desse escopo:

Categoria	Responsabilidade
model/	Entidades, objetos de valor, invariantes, políticas, eventos de domínio
services/	Casos de uso de aplicação nomeados e orquestração
ports/	Interfaces para persistência, relógios, identidade, filas, provedores
adapters/	Implementações concretas de banco de dados, transporte, provedor ou plataforma
contracts/	DTOs públicos, esquemas de eventos, validação, contratos de compatibilidade
components/, hooks/	UI de domínio e comportamento de UI quando esse domínio possui um frontend
shared/	Código reutilizável para consumidores dentro desse escopo
tests/ ou testes colocalizados	Verificação de comportamento e limite usando convenções do repositório

Implementações de serviço pertencem a services/ em sua camada proprietária. Quando um serviço de domínio é necessário para uma regra abrangendo entidades, coloque-o em model/services/; a orquestração permanece no services/ principal do domínio. Serviços de provedor podem viver em adapters/services/ quando útil.

Para um aplicativo, use src/domains/<dominio>/{model,services,ports,adapters,contracts,shared} conforme necessário, um ponto de entrada público, rotas finas de framework e uma raiz de composição. Coloque primitivas neutras de domínio sob src/shared/. Crie apenas diretórios contendo código real.

Exemplo de monorepo; respeite convenções de pacotes existentes e exportações explícitas:

apps/
  web/                           # Composição e apresentação do app
  api/                           # Pontos de entrada de transporte finos
  worker/                        # Registro e composição de jobs
packages/
  billing/                       # Pacote de workspace proprietário
    package.json                 # Exportações públicas e compatibilidade de tempo de execução
    src/
      services/                  # Casos de uso compartilhados por API/worker
      shared/                    # Reutilização local de faturamento
      index.ts                   # Fachada pública explícita
  shared/
    contracts/                   # Pacote de workspace neutro de domínio
    ui/                          # Consumidores de frontend compatíveis

Registre pacotes reais no workspace; caminhos sozinhos não os tornam importáveis. Em workspaces poliglotas, exponha bibliotecas compatíveis ou clientes gerados a partir de esquemas canônicos; não tente importar código entre tempos de execução incompatíveis.

Regras de posicionamento

1. Um consumidor e significado específico de domínio: mantenha nesse domínio.
2. Vários consumidores dentro de um domínio: use services/ ou shared/ desse domínio.
3. Vários aplicativos compatíveis precisam de código de domínio reutilizável: coloque em um pacote de domínio do workspace; comportamento privilegiado de servidor permanece no lado do servidor atrás de uma API autorizada ou contrato de cliente.
4. Vários domínios precisam da mesma primitiva neutra de domínio: use código shared/ com escopo.
5. Consumidores precisam de significados de negócio diferentes: mantenha modelos separados e traduza explicitamente.
6. Fluxo de trabalho entre domínios: use um serviço de aplicação proprietário e contratos de domínio públicos.
7. Rotas, telas, controladores e jobs: delegue regras a serviços; mantenha preocupações de transporte locais.

Nunca copie uma capacidade para vários aplicativos apenas para tornar as importações convenientes. Nunca faça de um aplicativo a biblioteca de outro aplicativo. Mova a propriedade reutilizável para baixo para um pacote do qual ambos possam depender. Mantenha diretórios de framework necessários; roteie-os para a estrutura de domínio em vez de lutar contra o framework. Respeite o empacotamento padrão da linguagem e a arquitetura existente válida.

4. Imponha a direção da dependência

pontos de entrada -> serviços de aplicação públicos -> modelo + portas
adaptadores -> portas + modelo
inicialização -> serviços + adaptadores             # Conecta implementações concretas
pacotes de domínio -> pacotes compartilhados neutros de domínio

• O modelo não depende de HTTP, frameworks de UI, bancos de dados, filas ou SDKs de provedor.
• Serviços orquestram casos de uso através de dependências explícitas; adaptadores implementam portas.
• Pacotes compartilhados não importam apps ou internos de domínio. Evite dependências circulares.
• Chamadas entre domínios usam contratos públicos; evite ciclos de chamada síncronas e cadeias prolixas.
• Exporte pontos de entrada intencionais. Bloqueie importações profundas com pacote existente, lint ou ferramentas de build.
• Separe contratos seguros para navegador de implementações apenas de servidor e dependências privilegiadas.
• Mantenha SDKs privilegiados, clientes de banco de dados, segredos e código de sistema de arquivos fora dos gráficos de dependência do cliente.
• SDKs de provedor podem ser executados

...

[truncado para tradução]

5. [...]