From 3d118bc219901e152e5176d94b6e879cd9e30297 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 18 May 2026 23:50:24 +0000 Subject: [PATCH] feat: add complete agent harness (AGENTS.md, skills, rules, platform files) - Created AGENTS.md as SSoT with full project context - Added CLAUDE.md, DEVIN.md, GEMINI.md platform-specific files - Added .agents/ directory: CONTEXT.md, RULES.md, MEMORY.md, TOOLS.md, WORKFLOWS.md, README.md - Added skills: qrcode-development, qrcode-testing - Added rules: csharp-qrcoder.instructions.md (applyTo: **/*.cs) - Added ignore files for all platforms: .aiignore, .claudeignore, .cursorignore, .devinignore, .geminiignore, .windsurfignore Co-Authored-By: Afonso Dutra Nogueira Filho --- .agents/CONTEXT.md | 51 ++++++++ .agents/MEMORY.md | 30 +++++ .agents/README.md | 50 ++++++++ .agents/RULES.md | 51 ++++++++ .agents/TOOLS.md | 45 +++++++ .agents/WORKFLOWS.md | 85 ++++++++++++ .agents/skills/qrcode-development/SKILL.md | 51 ++++++++ .agents/skills/qrcode-testing/SKILL.md | 66 ++++++++++ .aiignore | 55 ++++++++ .claudeignore | 55 ++++++++ .cursorignore | 55 ++++++++ .devinignore | 55 ++++++++ .geminiignore | 55 ++++++++ .windsurfignore | 55 ++++++++ AGENTS.md | 142 +++++++++++++++++++++ CLAUDE.md | 19 +++ DEVIN.md | 26 ++++ GEMINI.md | 22 ++++ rules/csharp-qrcoder.instructions.md | 46 +++++++ 19 files changed, 1014 insertions(+) create mode 100644 .agents/CONTEXT.md create mode 100644 .agents/MEMORY.md create mode 100644 .agents/README.md create mode 100644 .agents/RULES.md create mode 100644 .agents/TOOLS.md create mode 100644 .agents/WORKFLOWS.md create mode 100644 .agents/skills/qrcode-development/SKILL.md create mode 100644 .agents/skills/qrcode-testing/SKILL.md create mode 100644 .aiignore create mode 100644 .claudeignore create mode 100644 .cursorignore create mode 100644 .devinignore create mode 100644 .geminiignore create mode 100644 .windsurfignore create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 DEVIN.md create mode 100644 GEMINI.md create mode 100644 rules/csharp-qrcoder.instructions.md 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/`