Skip to content

AGENTS.md

Latest commit

 

History

History
106 lines (76 loc) · 12.1 KB

AGENTS.md

File metadata and controls

106 lines (76 loc) · 12.1 KB
Raw

Instruções para agentes

Estas instruções valem para todo o repositório SmartCommands. Instruções explícitas do usuário e arquivos AGENTS.md mais próximos do código em edição têm precedência.

Comunicação e escopo

  • Comunique-se em português do Brasil, preservando o idioma e o estilo já usados em código, nomes de API, mensagens e documentos.
  • Em pedidos de análise, diagnóstico ou revisão, não altere arquivos — implemente somente quando o usuário também pedir a implementação.
  • Não faça commit, push, publicação de pacote, alteração de versão ou de CI/CD sem pedido explícito.
  • Quando o pedido depender de uma decisão sobre contrato público, breaking change, arquitetura, persistência, segurança ou publicação, apresente a decisão antes de implementar.

Projetos e finalidade

A solução está em src/SmartCommands.sln. Os projetos se dividem em três grupos:

Grupo Projetos Finalidade
Bibliotecas publicáveis RoyalCode.SmartCommands, RoyalCode.SmartCommands.Generators, RoyalCode.SmartCommands.EntityFramework, RoyalCode.SmartCommands.WorkContext Pacotes NuGet que formam a entrega do repositório.
Testes e suporte RoyalCode.SmartCommands.Tests, RoyalCode.SmartCommands.Tests.Models, RoyalCode.SmartCommands.Demo.Tests Testes do runtime/generator, modelos e fixtures compartilhados, e testes de integração HTTP dos exemplos. Tests.Models não é biblioteca de produção.
Exemplos e demonstrações RoyalCode.SmartCommands.Demo e todos os RoyalCode.SmartCommands.Demo.* restantes Host demonstrativo e módulos verticais que exercitam formas de uso da biblioteca. Não são aplicações reais de produção nem modelos completos de requisitos não funcionais, segurança, observabilidade ou operação.

Alvos: bibliotecas runtime net8.0/net9.0/net10.0; testes e Demo net10.0; generator/analyzer netstandard2.0.

Arquitetura das bibliotecas publicáveis

RoyalCode.SmartCommands.Generators --(build/analyzer)--> código dos handlers, DI e endpoints

RoyalCode.SmartCommands.EntityFramework ---┐
RoyalCode.SmartCommands.WorkContext -------┴--> RoyalCode.SmartCommands
                                                 ├── RoyalCode.SmartProblems
                                                 └── RoyalCode.SmartValidations
  • RoyalCode.SmartCommands é o núcleo runtime: atributos públicos, contratos de accessors/repositórios, decorators e mediator. Não contém implementação concreta de EF Core ou WorkContext.
  • RoyalCode.SmartCommands.Generators é a camada de compilação: incremental generator/analyzer, diagnósticos, leitura dos atributos e emissão de handlers, registros de DI e mapeamentos HTTP. Generators/ contém transformação/modelos/emissão; Commands/ contém blocos usados para construir o fluxo gerado. O pacote é distribuído em analyzers/dotnet/cs e usa RoyalCode.Extensions.SourceGenerator como base.
  • RoyalCode.SmartCommands.EntityFramework adapta os contratos do núcleo diretamente ao EF Core. Organiza-se em Adapters/, Extensions/ para DI e Options/.
  • RoyalCode.SmartCommands.WorkContext adapta os mesmos contratos ao ecossistema WorkContext, incluindo repositórios, UnitOfWork e retry de concorrência. Organiza-se em Adapters/, Extensions/, Options/, Internals/ e contratos/factories de problemas de concorrência.
  • pack.targets centraliza metadados e empacotamento; Directory.Build.props centraliza TFMs e versões das dependências. Mudanças de API pública devem considerar os quatro pacotes e o comportamento do código gerado.

Documentação e referências de leitura

Antes de tarefas que envolvam arquitetura, comportamento ou uso das bibliotecas, leia o que for pertinente:

Em src/.docs/references/, os arquivos *.ai-rules.md são regras operacionais concisas; os arquivos *.md correspondentes são os guias conceituais completos, com contexto, exemplos e referência de API:

Os documentos em src/.docs/references/ são a documentação das bibliotecas consumidas: use-os para orientar o código, mas não os edite sem pedido explícito.

Ecossistema RoyalCode e fontes locais

As versões consumidas por NuGet são definidas em src/Directory.Build.props. No layout local padrão, os repositórios das dependências ficam como irmãos de SmartCommands sob a pasta RoyalCode/. Os caminhos abaixo servem para consultar a implementação ou realizar trabalho coordenado entre repositórios; os projetos desta solução continuam referenciando os pacotes NuGet, salvo mudança deliberada para investigação local.

Convenções de implementação

  • Documente APIs públicas e funcionalidade de domínio com XML documentation ao criar ou alterar seus contratos.
  • Para falhas esperadas de domínio, prefira Result, Result<T>, Problems e Problem em vez de exceções; valide com SmartValidations/Rules.Set<T>() e HasProblems.
  • Propague CancellationToken em fluxos assíncronos e evite async void.
  • Mudanças no generator devem manter saída determinística, cabeçalho // <auto-generated/>, #nullable enable e diagnósticos para entradas inválidas em vez de falhas do generator.
  • Prefira corrigir o código-fonte que gera os artefatos a editar artefatos gerados à mão; atualize snapshots/fixtures apenas com a mudança verificada.

Fluxo de trabalho

  • Mantenha os patches focados no pedido. Problemas fora do escopo podem ser relatados à parte, em vez de expandir a alteração.
  • Para executar planos em src/.ai/plans/, leia antes as decisões, dependências, invariantes, critérios de aceite e riscos. Atualize tarefas e resultados só depois da verificação correspondente.

Build e testes

A partir de src/, os comandos padrão são:

dotnet build SmartCommands.sln -c Release
dotnet test RoyalCode.SmartCommands.Tests/RoyalCode.SmartCommands.Tests.csproj -c Release
dotnet test RoyalCode.SmartCommands.Demo.Tests/RoyalCode.SmartCommands.Demo.Tests.csproj -c Release
  • Valide na proporção do risco: testes diretos para mudanças localizadas; suíte relevante completa para contratos públicos, generator ou mudanças transversais.
  • Não aceite warnings novos silenciosamente; compare com o baseline.
  • Relate exatamente quais verificações rodaram e seus resultados — não afirme que um teste passou sem tê-lo executado.

Critério de conclusão

  • O comportamento pedido está implementado (ou a análise está sustentada por evidências), com testes criados/atualizados quando o comportamento mudou.
  • As verificações relevantes passaram, ou os impedimentos e falhas remanescentes foram relatados com clareza.