AGENTS.md

Orientação para agentes (IA) e contribuidores

Este ficheiro resume como trabalhar no repositório BulkSort de forma alinhada com o código e a documentação canónica.

Fonte de verdade

1. docs/architecture.md — comportamento e estrutura as-is; em caso de conflito com plan-desenvolvimento-unificado.md ou outro texto auxiliar, prevalece architecture.md + ADRs.
2. docs/adr/ — decisões estáveis (híbrido disco/Blob, diff local-first, IBlobContainer, semântica de linha).

Build e testes

dotnet build BulkSort.sln
dotnet test BulkSort.sln

Convenções de código

• Núcleo (BulkSortPipeline): sem referências a Azure.Storage.Blobs; I/O remoto só via IBlobContainer.
• Azure: implementações e extensões DI em BulkSortPipeline.Azure.
• Comentários XML e identificadores em inglês, alinhados ao código existente.
• Hot path de ordenação/merge: evitar alocações desnecessárias (Span, ArrayPool, comparer em bytes).

Alterações que exigem documentação

• Mudança de semântica de linha, comparer, dedupe ou defaults de ExternalSortOptions → atualizar docs/architecture.md e, se for decisão de desenho, novo ou alterado ADR.
• Novo backend de armazenamento → ADR ou secção em arquitetura + implementação de IBlobContainer.

Configuração local

• Não introduzir segredos em appsettings.json commitado; usar User Secrets ou env vars.
• BulkSortHost:Operation define Sort vs Diff; secção ExternalSort ajusta chunk, fan-in e diretório de merge local.

O que evitar

• Acoplar o núcleo ao SDK Azure.
• Documentar como “implementado” algo que o código ainda não faz (validar sempre contra docs/architecture.md e testes).