diff --git a/.agents/CONTEXT.md b/.agents/CONTEXT.md new file mode 100644 index 0000000..9ac31ca --- /dev/null +++ b/.agents/CONTEXT.md @@ -0,0 +1,51 @@ +# Context Engineering — QRCoder.Core + +## Estratégias de Carregamento + +| Tipo | Quando | Arquivos | +|------|--------|----------| +| **Always-on** | Sempre carregado | `AGENTS.md`, `.agents/RULES.md` | +| **Pattern-matched** | Por tipo de arquivo | `rules/*.instructions.md` (via `applyTo`) | +| **On-demand** | Quando solicitado | `.agents/skills/`, `docs/`, `.agents/MEMORY.md` | +| **Progressive disclosure** | Arquivos grandes | Headers → seções relevantes | + +## Hierarquia de Prioridade + +1. Instruções do usuário (chat/prompt) +2. `AGENTS.md` (SSoT) +3. Arquivo de plataforma (`CLAUDE.md`, `DEVIN.md`, `GEMINI.md`) +4. `.agents/RULES.md` +5. `rules/*.instructions.md` +6. `.agents/skills/` +7. `.agents/MEMORY.md` + +## Token Budget + +- Reservar 20% do contexto para output +- `AGENTS.md` ≤ 500 linhas +- Skills: carregar apenas as relevantes + +## Chunking + +- `QRCodeGenerator.cs`: arquivo grande — carregar por método/seção +- Testes: agrupar por renderizador + +## Mapa de Diretórios + +``` +Prioridade alta: + QRCoder.Core/Generators/ + QRCoder.Core/Renderers/ + QRCoder.Core/Abstractions/ + QRCoder.Core.Tests/ + +Prioridade média: + QRCoder.Core/Models/ + QRCoder.Core/Extensions/ + docs/ + +Prioridade baixa: + QRCoder.Core/Assets/ + Docs/ (SHFB generated) + .vscode/ +``` diff --git a/.agents/MEMORY.md b/.agents/MEMORY.md new file mode 100644 index 0000000..0feaf2a --- /dev/null +++ b/.agents/MEMORY.md @@ -0,0 +1,30 @@ +# QRCoder.Core Agent Memory + +Este arquivo é mantido automaticamente pelo agente AI para persistir aprendizados sobre o codebase. + +## Decisões Técnicas + +| Data | Decisão | Motivo | Alternativas Descartadas | +|------|---------|--------|--------------------------| +| 2026-05 | SkiaSharp como engine de renderização | Cross-platform (Win/Linux/Mac) | System.Drawing (não cross-platform) | +| 2026-05 | ObjectPool para QRCodeData | Performance em alta demanda | Criação por request | +| 2026-05 | Multi-TFM (netstandard2.1, net8.0, net10.0, net48) | Máxima compatibilidade | Apenas net8.0+ | + +## Débitos Técnicos + +| Item | Impacto | Prioridade | +|------|---------|-----------| +| Cobertura 78% (target 90%) | Qualidade | Média | +| PayloadGenerator sem testes completos | Risco de regressão | Média | + +## Lições Aprendidas + +| Contexto | Erro | Como Evitar | +|----------|------|-------------| +| Build net48 em Linux | Falha por falta de Windows Desktop | Usar `-f net10.0` para testes locais | +| SkiaSharp em CI | Falta de dependências nativas | Instalar libfontconfig1, libfreetype6, etc. | + +## Políticas de Limpeza + +- Fatos desatualizados devem ser removidos +- Memórias de branches deletadas devem ser descartadas diff --git a/.agents/README.md b/.agents/README.md new file mode 100644 index 0000000..2ef30ab --- /dev/null +++ b/.agents/README.md @@ -0,0 +1,50 @@ +# Infraestrutura de Agentes — QRCoder.Core + +## Diagrama de Arquivos + +``` +AGENTS.md ← SSoT (≤500 linhas) +CLAUDE.md ← Delta para Claude Code +DEVIN.md ← Delta para Devin +GEMINI.md ← Delta para Gemini CLI +.aiignore ← Ignore JetBrains AI +.claudeignore ← Ignore Claude Code +.cursorignore ← Ignore Cursor +.devinignore ← Ignore Devin +.geminiignore ← Ignore Gemini CLI +.windsurfignore ← Ignore Windsurf +.agents/ +├── CONTEXT.md ← Estratégias de contexto +├── RULES.md ← Guardrails +├── MEMORY.md ← Estado cross-session +├── TOOLS.md ← Ferramentas e CI/CD +├── WORKFLOWS.md ← Workflows de automação +├── README.md ← Este arquivo +└── skills/ + ├── qrcode-development/ ← Desenvolvimento de QR Code + └── qrcode-testing/ ← Testes de QR Code +rules/ +└── csharp-qrcoder.instructions.md ← Rules C# (applyTo: **/*.cs) +``` + +## Como Adicionar Nova Skill + +1. Criar diretório em `.agents/skills//` +2. Criar `SKILL.md` com frontmatter YAML +3. Documentar: What / When / Do NOT +4. Atualizar este README + +## Compatibilidade + +| Feature | Claude | Devin | Gemini | Cursor | Windsurf | +|---------|--------|-------|--------|--------|----------| +| AGENTS.md | Sim | Sim | Sim | Sim | Sim | +| Skills | Sim | Sim | Sim | Sim | Sim | +| Rules | Sim | Sim | Sim | Sim | Sim | +| Ignore | .claudeignore | .devinignore | .geminiignore | .cursorignore | .windsurfignore | + +## Referências + +- [AGENTS.md Spec](https://agents.md/) +- [Agent Skills Spec](https://agentskills.io/specification) +- [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/) diff --git a/.agents/RULES.md b/.agents/RULES.md new file mode 100644 index 0000000..02b0c81 --- /dev/null +++ b/.agents/RULES.md @@ -0,0 +1,51 @@ +# RULES.md — QRCoder.Core Guardrails + +## Hard Rules (bloqueio imediato) + +| # | Regra | Verificação | +|---|-------|-------------| +| H1 | Todos os testes devem passar antes do merge | CI: `dotnet test` | +| H2 | Cobertura de código não pode diminuir (baseline: 78%) | CI: coverlet | +| H3 | Compatibilidade cross-platform obrigatória (Win/Linux/Mac) | CI: ubuntu-latest | +| H4 | Manter suporte .NET Standard 2.1 | Build multi-TFM | +| H5 | Nunca commitar secrets | `.gitignore` | +| H6 | Não usar System.Drawing (deprecated, não cross-platform) | Code review | +| H7 | Não push direto em `main` | Branch protection | + +## Soft Rules (warning + confirmação) + +| # | Regra | Ação | +|---|-------|------| +| S1 | Alterar `QRCodeGenerator.cs` (engine central) | Testes extensivos | +| S2 | Adicionar dependência NuGet | Verificar compatibilidade multi-TFM | +| S3 | Alterar formato de saída de renderizadores | Backward compatibility | +| S4 | Modificar CI workflows | Requer revisão | +| S5 | Alterar versão do SkiaSharp | Testar em todas as plataformas | + +## Permissões por Ambiente + +| Ambiente | Read | Write | Execute | +|----------|------|-------|---------| +| **dev** | Livre | Livre | Sandbox | +| **CI** | Livre | Via PR | Automático | +| **NuGet** | — | — | Via release workflow | + +## Tool Permissions + +- **Read-only**: busca, navegação, análise de código +- **Write**: edição via PR +- **Execute**: build, test em sandbox +- **Publish**: apenas via CI/CD + +## Arquivos Imutáveis + +``` +bin/ +obj/ +Docs/ (SHFB generated) +.git/ +.vs/ +.vscode/ +packages/ +TestResults/ +``` diff --git a/.agents/TOOLS.md b/.agents/TOOLS.md new file mode 100644 index 0000000..2cbce6c --- /dev/null +++ b/.agents/TOOLS.md @@ -0,0 +1,45 @@ +# TOOLS.md — QRCoder.Core Ferramentas + +## Ferramentas de Build + +| Ferramenta | Comando | Categoria | +|-----------|---------|-----------| +| dotnet restore | `dotnet restore QRCoder.Core.sln` | Read-only | +| dotnet build | `dotnet build QRCoder.Core.sln --configuration Release` | Execute | +| dotnet test | `dotnet test QRCoder.Core.sln --collect:"XPlat Code Coverage"` | Execute | +| dotnet pack | `dotnet pack --configuration Release` | Execute | + +## Ferramentas de Qualidade + +| Ferramenta | Uso | Categoria | +|-----------|-----|-----------| +| SonarCloud | Análise de qualidade de código | Execute | +| Codecov | Relatório de cobertura | Execute | +| coverlet | Coleta de cobertura em testes | Execute | + +## Ferramentas de CI/CD + +| Workflow | Trigger | Descrição | +|---------|---------|-----------| +| `ci-build-test.yml` | push feature/*, PR main | Build + testes + cobertura | +| `publish-all.yml` | tag release | Publicação NuGet | +| `code-quality.yml` | PR | SonarCloud + Qodana | +| `security-scan.yml` | schedule/PR | Scan de segurança | +| `openhands-resolver.yml` | issue label | Auto-fix via OpenHands | +| `auto-pr-from-main.yml` | push main | Sync automático | + +## APIs Externas + +| API | Uso | Headers | +|-----|-----|---------| +| NuGet.org | Publicação de pacotes | API Key via CI secrets | +| SonarCloud | Qualidade | Token via CI secrets | +| Codecov | Cobertura | Token via CI secrets | +| GitHub API | CI/CD | GITHUB_TOKEN | + +## Dependências Nativas (Linux) + +```bash +sudo apt-get install -y libfontconfig1 libfreetype6 libx11-6 libxext6 libxrender1 libxtst6 +sudo apt-get install -y libglib2.0-0 libgl1-mesa-dev +``` diff --git a/.agents/WORKFLOWS.md b/.agents/WORKFLOWS.md new file mode 100644 index 0000000..b4ca3ef --- /dev/null +++ b/.agents/WORKFLOWS.md @@ -0,0 +1,85 @@ +# WORKFLOWS.md — QRCoder.Core Automação + +## Workflow: Novo Renderizador + +### Precondições +- Formato de saída definido +- Renderizador herda de `AbstractQRCode` + +### Passos +1. Criar classe em `QRCoder.Core/Renderers/` +2. Herdar de `AbstractQRCode` +3. Implementar método `GetGraphic()` +4. Criar testes em `QRCoder.Core.Tests/Renderers/` +5. Documentar em `docs/en-US/` e `docs/pt-BR/` +6. Atualizar README com novo formato +7. Criar PR + +### Critérios de Sucesso +- Testes passam em todos os TFMs +- Cross-platform (sem System.Drawing) +- Documentação bilíngue + +--- + +## Workflow: Novo Payload + +### Precondições +- Payload segue padrão da indústria (ex: vCard, WiFi QR) + +### Passos +1. Criar classe em `PayloadGenerator` +2. Implementar `ToString()` com formato padronizado +3. Criar testes unitários +4. Documentar exemplos de uso +5. Criar PR + +--- + +## Workflow: Bug Fix + +### Passos +1. Reproduzir com teste que falha +2. Implementar correção +3. Verificar que teste passa +4. Rodar suite completa: `dotnet test` +5. Criar PR + +--- + +## Verification Loop + +``` +Código → Build → Testes → Cobertura → CI → Review + ↑ | + └──── Ajustar (máx. 2x) ────────────────┘ +``` + +### Execução Local +```bash +dotnet restore QRCoder.Core.sln +dotnet build QRCoder.Core.sln --configuration Release +dotnet test QRCoder.Core.sln --configuration Release --collect:"XPlat Code Coverage" +``` + +--- + +## Workflow: Release + +### Passos +1. Atualizar versão em `QRCoder.Core.csproj` +2. Atualizar `CHANGELOG.md` +3. Criar tag de release +4. CI publica automaticamente no NuGet + +--- + +## Trigger Conditions + +| Evento | Workflow | +|--------|---------| +| Push em `feature/*`, `bug/*`, `hotfix/*` | `ci-build-test.yml` | +| PR para `main` | `ci-build-test.yml` + `code-quality.yml` | +| Tag de release | `publish-all.yml` | +| Push em `main` | `auto-pr-from-main.yml` | +| Schedule | `security-scan.yml` | diff --git a/.agents/skills/qrcode-development/SKILL.md b/.agents/skills/qrcode-development/SKILL.md new file mode 100644 index 0000000..72c6647 --- /dev/null +++ b/.agents/skills/qrcode-development/SKILL.md @@ -0,0 +1,51 @@ +--- +name: qrcode-development +description: > + What: Guia para desenvolvimento de renderizadores, payloads e funcionalidades do QRCoder.Core. + When: Ao criar novos renderizadores, adicionar payloads, modificar o QRCodeGenerator, ou trabalhar com SkiaSharp. + Do NOT: Não usar para testes (ver qrcode-testing), CI/CD, ou documentação isolada. +--- + +## Contexto + +QRCoder.Core é uma biblioteca cross-platform para geração de QR Codes. A arquitetura segue: +- `QRCodeGenerator` → engine central que gera `QRCodeData` (matriz de bits) +- `AbstractQRCode` → classe base para renderizadores +- Cada renderizador converte `QRCodeData` em um formato de saída específico + +## Atuação + +### Novo Renderizador +1. Criar classe em `QRCoder.Core/Renderers/` +2. Herdar de `AbstractQRCode` +3. Implementar `GetGraphic()` com parâmetros de customização +4. Manter compatibilidade cross-platform (sem System.Drawing) +5. Usar SkiaSharp para renderização gráfica se necessário + +### Novo Payload +1. Criar classe em `PayloadGenerator` (arquivo existente) +2. Implementar `ToString()` retornando string formatada +3. Seguir padrão da indústria (RFC, especificação oficial) +4. Adicionar validação de inputs + +### Performance +- Usar `ObjectPool` para reutilização de buffers +- Usar `Span` e `System.Buffers` para operações com arrays +- Evitar alocações em hot paths + +## Restrições + +- Não usar System.Drawing (não é cross-platform) +- Manter compatibilidade com .NET Standard 2.1 +- Não adicionar dependências nativas além do SkiaSharp +- XML documentation obrigatória em APIs públicas + +## Exemplos + +```csharp +// Gerar QR Code PNG +var generator = new QRCodeGenerator(); +var data = generator.CreateQrCode("Hello", QRCodeGenerator.ECCLevel.M); +var pngCode = new PngByteQRCode(data); +byte[] pngBytes = pngCode.GetGraphic(20); +``` diff --git a/.agents/skills/qrcode-testing/SKILL.md b/.agents/skills/qrcode-testing/SKILL.md new file mode 100644 index 0000000..f6d314f --- /dev/null +++ b/.agents/skills/qrcode-testing/SKILL.md @@ -0,0 +1,66 @@ +--- +name: qrcode-testing +description: > + What: Guia para testes unitários do QRCoder.Core usando xUnit, Shouldly e coverlet. + When: Ao escrever testes, aumentar cobertura, debugar falhas de teste, ou configurar test runners. + Do NOT: Não usar para desenvolvimento de features (ver qrcode-development) ou CI/CD. +--- + +## Contexto + +QRCoder.Core usa xUnit como framework de testes, Shouldly para assertions legíveis, e coverlet para cobertura de código. Os testes estão em `QRCoder.Core.Tests/`. + +## Atuação + +### Estrutura de Testes +``` +QRCoder.Core.Tests/ +├── Generators/ # Testes do QRCodeGenerator +├── Renderers/ # Testes por renderizador +├── Extensions/ # Testes de extensões +├── Models/ # Testes de modelos +├── Exceptions/ # Testes de exceções +├── Helpers/ # Utilitários de teste +└── assets/ # Arquivos de referência (imagens, SVGs) +``` + +### Padrões +- BDD em português: Dado/Quando/Então +- Uma assertion por teste quando possível +- Testes de renderização: comparar output com referência em `assets/` +- Testar todos os níveis ECC: L, M, Q, H + +### Comandos +```bash +# Todos os testes +dotnet test QRCoder.Core.sln --configuration Release + +# Com cobertura +dotnet test QRCoder.Core.sln --collect:"XPlat Code Coverage" + +# Apenas net10.0 (Linux) +dotnet test QRCoder.Core.Tests/ -f net10.0 + +# Teste específico +dotnet test --filter "FullyQualifiedName~QRCodeGeneratorTests" +``` + +## Restrições + +- Não modificar testes existentes para forçar passagem +- Testes `net48` não rodam em Linux (sem Windows Desktop) +- Cobertura não pode diminuir (baseline: 78%) +- Não commitar arquivos de TestResults + +## Exemplos + +```csharp +[Fact] +public void Dado_TextoValido_Quando_GerarQRCode_Entao_DeveRetornarDadosValidos() +{ + var generator = new QRCodeGenerator(); + var data = generator.CreateQrCode("Test", QRCodeGenerator.ECCLevel.M); + data.ShouldNotBeNull(); + data.ModuleMatrix.ShouldNotBeEmpty(); +} +``` diff --git a/.aiignore b/.aiignore new file mode 100644 index 0000000..6fd6c7c --- /dev/null +++ b/.aiignore @@ -0,0 +1,55 @@ +# Build outputs +bin/ +obj/ +out/ +dist/ +build/ + +# Dependencies +packages/ + +# Version control +.git/ + +# Secrets +.env +.env.* +*.key +*.pem + +# IDE +.vs/ +.idea/ +.vscode/ + +# Test artifacts +TestResults/ +coverage/ +*.coverage + +# Logs +*.log + +# Generated docs +Docs/ + +# Large binaries +*.dll +*.exe +*.so +*.dylib +*.nupkg +*.snupkg + +# Database files +*.db +*.sqlite + +# OS files +.DS_Store +Thumbs.db + +# Temporary +*.tmp +*.temp +*.cache diff --git a/.claudeignore b/.claudeignore new file mode 100644 index 0000000..6fd6c7c --- /dev/null +++ b/.claudeignore @@ -0,0 +1,55 @@ +# Build outputs +bin/ +obj/ +out/ +dist/ +build/ + +# Dependencies +packages/ + +# Version control +.git/ + +# Secrets +.env +.env.* +*.key +*.pem + +# IDE +.vs/ +.idea/ +.vscode/ + +# Test artifacts +TestResults/ +coverage/ +*.coverage + +# Logs +*.log + +# Generated docs +Docs/ + +# Large binaries +*.dll +*.exe +*.so +*.dylib +*.nupkg +*.snupkg + +# Database files +*.db +*.sqlite + +# OS files +.DS_Store +Thumbs.db + +# Temporary +*.tmp +*.temp +*.cache diff --git a/.cursorignore b/.cursorignore new file mode 100644 index 0000000..6fd6c7c --- /dev/null +++ b/.cursorignore @@ -0,0 +1,55 @@ +# Build outputs +bin/ +obj/ +out/ +dist/ +build/ + +# Dependencies +packages/ + +# Version control +.git/ + +# Secrets +.env +.env.* +*.key +*.pem + +# IDE +.vs/ +.idea/ +.vscode/ + +# Test artifacts +TestResults/ +coverage/ +*.coverage + +# Logs +*.log + +# Generated docs +Docs/ + +# Large binaries +*.dll +*.exe +*.so +*.dylib +*.nupkg +*.snupkg + +# Database files +*.db +*.sqlite + +# OS files +.DS_Store +Thumbs.db + +# Temporary +*.tmp +*.temp +*.cache diff --git a/.devinignore b/.devinignore new file mode 100644 index 0000000..6fd6c7c --- /dev/null +++ b/.devinignore @@ -0,0 +1,55 @@ +# Build outputs +bin/ +obj/ +out/ +dist/ +build/ + +# Dependencies +packages/ + +# Version control +.git/ + +# Secrets +.env +.env.* +*.key +*.pem + +# IDE +.vs/ +.idea/ +.vscode/ + +# Test artifacts +TestResults/ +coverage/ +*.coverage + +# Logs +*.log + +# Generated docs +Docs/ + +# Large binaries +*.dll +*.exe +*.so +*.dylib +*.nupkg +*.snupkg + +# Database files +*.db +*.sqlite + +# OS files +.DS_Store +Thumbs.db + +# Temporary +*.tmp +*.temp +*.cache diff --git a/.geminiignore b/.geminiignore new file mode 100644 index 0000000..6fd6c7c --- /dev/null +++ b/.geminiignore @@ -0,0 +1,55 @@ +# Build outputs +bin/ +obj/ +out/ +dist/ +build/ + +# Dependencies +packages/ + +# Version control +.git/ + +# Secrets +.env +.env.* +*.key +*.pem + +# IDE +.vs/ +.idea/ +.vscode/ + +# Test artifacts +TestResults/ +coverage/ +*.coverage + +# Logs +*.log + +# Generated docs +Docs/ + +# Large binaries +*.dll +*.exe +*.so +*.dylib +*.nupkg +*.snupkg + +# Database files +*.db +*.sqlite + +# OS files +.DS_Store +Thumbs.db + +# Temporary +*.tmp +*.temp +*.cache diff --git a/.windsurfignore b/.windsurfignore new file mode 100644 index 0000000..6fd6c7c --- /dev/null +++ b/.windsurfignore @@ -0,0 +1,55 @@ +# Build outputs +bin/ +obj/ +out/ +dist/ +build/ + +# Dependencies +packages/ + +# Version control +.git/ + +# Secrets +.env +.env.* +*.key +*.pem + +# IDE +.vs/ +.idea/ +.vscode/ + +# Test artifacts +TestResults/ +coverage/ +*.coverage + +# Logs +*.log + +# Generated docs +Docs/ + +# Large binaries +*.dll +*.exe +*.so +*.dylib +*.nupkg +*.snupkg + +# Database files +*.db +*.sqlite + +# OS files +.DS_Store +Thumbs.db + +# Temporary +*.tmp +*.temp +*.cache diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..66a270f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,142 @@ +# AGENTS.md — QRCoder.Core + +## Missão + +QRCoder.Core é uma biblioteca .NET cross-platform para geração e renderização de QR Codes usando SkiaSharp. Suporta múltiplos formatos de saída (PNG, SVG, PDF, ASCII, Base64, Postscript, ArtQR) e payloads padronizados (WiFi, vCard, Bitcoin, SEPA, etc.). Qualquer agente LLM que trabalhe neste repositório deve seguir as convenções aqui documentadas. + +## Stack Tecnológica + +| Camada | Tecnologia | Versão | +|--------|-----------|--------| +| Runtime | .NET | Standard 2.1 / 8.0 / 10.0 / FW 4.8 | +| Linguagem | C# | 10.0 | +| Renderização | SkiaSharp | 3.119.0 | +| Pool | Microsoft.Extensions.ObjectPool | 9.0.7 | +| Testes | xUnit + Shouldly + coverlet | — | +| CI/CD | GitHub Actions | — | +| Qualidade | SonarCloud + Codecov | — | +| Licença | MIT | — | + +## Estrutura do Projeto + +``` +QRCoder.Core/ # Biblioteca principal +├── Abstractions/ # Interfaces e classes base (AbstractQRCode) +├── Models/ # QRCodeData, módulos, masking +├── Generators/ # QRCodeGenerator (engine central) +├── Renderers/ # Renderizadores por formato +│ ├── QRCode.cs # SKBitmap (SkiaSharp) +│ ├── PngByteQRCode.cs # PNG puro (.NET) +│ ├── SvgQRCode.cs # SVG string +│ ├── PdfByteQRCode.cs # PDF byte array +│ ├── ASCIIQRCode.cs # ASCII art +│ ├── Base64QRCode.cs # Base64 image +│ ├── PostscriptQRCode.cs # Postscript/EPS +│ ├── ArtQRCode.cs # QR artístico +│ └── BitmapByteQRCode.cs # BMP bytes +├── Extensions/ # Métodos de extensão +├── Exceptions/ # Exceções tipadas +└── Assets/ # Ícones e recursos NuGet +QRCoder.Core.Tests/ # Testes unitários (300+) +├── Generators/ # Testes do QRCodeGenerator +├── Renderers/ # Testes por renderizador +├── Extensions/ # Testes de extensões +├── Models/ # Testes de modelos +├── Exceptions/ # Testes de exceções +├── Helpers/ # Utilitários de teste +└── assets/ # Arquivos de referência +docs/ # Documentação bilíngue +├── en-US/ # Guia de uso (inglês) +└── pt-BR/ # Guia de uso (português) +.agents/ # Infraestrutura de agentes +``` + +## Caminhos por Plataforma + +| Plataforma | Config Principal | Skills | Rules | +|-----------|-----------------|--------|-------| +| Todos | `AGENTS.md` | `.agents/skills/` | `.agents/RULES.md`, `rules/` | +| Claude Code | `CLAUDE.md` | auto-loaded | `.agents/RULES.md` | +| Devin | `DEVIN.md` | `.agents/skills/` | `.agents/RULES.md` | +| Gemini CLI | `GEMINI.md` | `.agents/skills/` | `.agents/RULES.md` | + +## Comandos de Build + +```bash +# Restaurar dependências +dotnet restore QRCoder.Core.sln + +# Build completo +dotnet build QRCoder.Core.sln --configuration Release + +# Testes com cobertura +dotnet test QRCoder.Core.sln --configuration Release \ + --collect:"XPlat Code Coverage" \ + --results-directory TestResults + +# Apenas testes .NET 10 +dotnet test QRCoder.Core.Tests/ -f net10.0 --configuration Release +``` + +## Padrões de Código + +### DO (Faça) +- Seguir Clean Architecture: Abstractions → Models → Generators → Renderers +- Documentação XML em todas as APIs públicas +- Testes para todo novo renderizador ou payload +- Manter compatibilidade cross-platform (SkiaSharp, sem System.Drawing) +- Documentação bilíngue (pt-BR + en-US) +- Usar `ObjectPool` para buffers de matriz reutilizáveis +- Usar `System.Buffers` e `System.Memory` para performance + +### DON'T (Não Faça) +- Não usar System.Drawing (incompatível cross-platform) +- Não reduzir cobertura de testes (78%+ baseline) +- Não quebrar compatibilidade com .NET Standard 2.1 +- Não commitar binários nativos (`.so`, `.dylib`, `.dll`) +- Não hardcodar caminhos de plataforma + +## Hard Rules + +1. **Testes obrigatórios**: CI falha se qualquer teste quebrar +2. **Cobertura mínima**: não pode diminuir em relação ao baseline (78%) +3. **Cross-platform**: deve funcionar em Windows, Linux e macOS +4. **Secrets**: nunca commitar `.env`, tokens ou API keys +5. **Compatibilidade**: manter suporte a .NET Standard 2.1 + +## Soft Rules + +1. Alterar `QRCodeGenerator.cs` → requer testes extensivos +2. Adicionar dependência NuGet → verificar compatibilidade multi-TFM +3. Alterar formatos de saída → manter backward compatibility +4. Modificar CI workflows → requer revisão + +## Agent Loop + +> Padrão: **ReAct** (Observe → Think → Act → Verify) + +``` +1. Receber tarefa +2. Carregar AGENTS.md + RULES.md +3. Analisar código relevante +4. Implementar alteração +5. Executar testes: dotnet test +6. Verificar cobertura +7. Criar PR +``` + +## Response Style + +- Idioma: Português (pt-BR) para docs; inglês para código +- Conciso e direto +- Commits: `feat:`, `fix:`, `test:`, `docs:`, `refactor:` + +## Referências + +- `.agents/CONTEXT.md` — Estratégias de contexto +- `.agents/RULES.md` — Guardrails +- `.agents/TOOLS.md` — Ferramentas +- `.agents/WORKFLOWS.md` — Automação +- `.agents/skills/` — Skills on-demand +- `rules/` — Rules por domínio +- `docs/` — Documentação bilíngue diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0d6cb89 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,19 @@ +# Claude Code Configuration — QRCoder.Core + +@import AGENTS.md + +## Delta Claude + +### Carregamento Automático +Claude Code carrega este arquivo automaticamente. O `@import` acima carrega o AGENTS.md como SSoT. + +### Memory +Claude Code mantém memória automática em `.agents/MEMORY.md`. + +### Skills +Skills em `.agents/skills/` — carregadas sob demanda pelo contexto. + +### Guardrails +- `.agents/RULES.md` — Hard/Soft rules +- `rules/*.instructions.md` — Rules por domínio +- `.claudeignore` — Arquivos a ignorar diff --git a/DEVIN.md b/DEVIN.md new file mode 100644 index 0000000..f5871b0 --- /dev/null +++ b/DEVIN.md @@ -0,0 +1,26 @@ +# Devin Configuration — QRCoder.Core + +> Referência principal: [AGENTS.md](AGENTS.md) + +## Delta Devin + +### Ambiente +- .NET 10.0 necessário (também builds para net8.0, netstandard2.1, net48) +- SkiaSharp requer dependências nativas Linux: `libfontconfig1 libfreetype6 libx11-6` + +### Comandos Rápidos +```bash +dotnet restore QRCoder.Core.sln +dotnet build QRCoder.Core.sln --configuration Release +dotnet test QRCoder.Core.sln --configuration Release --collect:"XPlat Code Coverage" +``` + +### PRs +- Branch: `devin/-` +- Target: `main` +- CI deve passar antes de notificar o usuário + +### Notas +- Testes `net48` não rodam em Linux (sem Windows Desktop) +- SkiaSharp precisa de `LD_LIBRARY_PATH` configurado em alguns ambientes +- Usar `dotnet test -f net10.0` para rodar apenas no TFM disponível diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..2abca04 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,22 @@ +# Gemini CLI Configuration — QRCoder.Core + +> Referência principal: [AGENTS.md](AGENTS.md) + +## Delta Gemini + +### Contexto +Gemini CLI carrega este arquivo automaticamente. O AGENTS.md contém todas as convenções. + +### Build +```bash +dotnet restore QRCoder.Core.sln +dotnet build QRCoder.Core.sln --configuration Release +dotnet test QRCoder.Core.sln --configuration Release --collect:"XPlat Code Coverage" +``` + +### Skills +Disponíveis em `.agents/skills/` — carregar conforme contexto. + +### Referências +- `.agents/RULES.md` — guardrails +- `.agents/TOOLS.md` — ferramentas diff --git a/rules/csharp-qrcoder.instructions.md b/rules/csharp-qrcoder.instructions.md new file mode 100644 index 0000000..6688a2a --- /dev/null +++ b/rules/csharp-qrcoder.instructions.md @@ -0,0 +1,46 @@ +--- +name: 'C# QRCoder.Core Standards' +description: 'Padrões de código C# para a biblioteca QRCoder.Core, incluindo SkiaSharp, renderizadores e performance' +applyTo: '**/*.cs' +--- + +# C# QRCoder.Core Standards + +## Arquitetura + +- `QRCodeGenerator` → gera `QRCodeData` (bit matrix) +- `AbstractQRCode` → base para renderizadores +- Cada renderizador em arquivo separado em `Renderers/` +- Interfaces em `Abstractions/` + +## SkiaSharp + +- Sempre fazer `Dispose()` de objetos SKBitmap, SKCanvas, SKPaint +- Usar `using` statements para recursos gráficos +- Não assumir disponibilidade de fontes do sistema +- Configurar `LD_LIBRARY_PATH` em ambientes Linux + +## Performance + +- Usar `ObjectPool` para buffers reutilizáveis +- Usar `Span` e `ReadOnlySpan` onde possível +- Evitar boxing/unboxing em hot paths +- Preferir `stackalloc` para arrays pequenos + +## Multi-TFM + +- Manter compatibilidade com .NET Standard 2.1 +- Usar `#if` directives para APIs específicas de TFM +- Testar em todos os target frameworks + +## Documentação + +- XML docs obrigatórios em todas as APIs públicas +- ``, ``, ``, `` +- Exemplos em `` para APIs complexas + +## Testes + +- xUnit + Shouldly para assertions +- BDD em português: Dado/Quando/Então +- Comparar outputs com referências em `assets/`