Como usar IronQR com Claude Code
A equipe de marketing exige que cada código QR da campanha use a cor azul marinho da marca, inclua o logotipo no centro e esteja disponível em tamanhos pôster e adesivo. No entanto, cada escolha de estilo adicional pode reduzir a confiabilidade de leitura. Por exemplo, um logotipo pode ocultar módulos, um primeiro plano claro pode reduzir o contraste, e tamanhos de impressão menores reduzem a densidade de pixels. Um código QR pode parecer correto na tela, mas ainda falhar no uso real. Claude Code, o agente de codificação da Anthropic, opera em terminais, VS Code, JetBrains, aplicativos de desktop e na web. Em qualquer ambiente, ele lê o projeto, edita arquivos e executa comandos, para que possa renderizar códigos estilizados, decodificar arquivos salvos e ajustar o estilo até que o payload seja preservado.
IronQR gera e lê códigos QR dentro do mesmo processo .NET, portanto, o agente pode escanear após cada alteração. A biblioteca rejeita automaticamente alguns designs ilegíveis. Um logotipo dimensionado manualmente que cobre demais, ou uma cor de primeiro plano muito próxima a um fundo branco, gera uma IronQrException ao salvar. Outras escolhas de estilo podem ser salvas com sucesso, mas ainda falhar na decodificação depois. A abordagem mais confiável é testar uma matriz de variantes estilizadas e decodificar cada PNG salvo. Este guia explica como configurar Claude Code para este processo, com três prompts testados e o comportamento do IronQR de que cada um depende.
Uma única configuração de modelo suporta todos os três prompts. O alias opusplan usa Opus em modo plano e Sonnet caso contrário, o que é adequado para uma sessão onde apenas a construção da matriz requer planejamento.
Abra a pasta do projeto em um terminal, inicie o Claude Code e execute /model opusplan. Digite @ antes de um caminho de arquivo para entregar esse arquivo ao Claude Code, depois envie a solicitação.
Install IronQR from NuGet here and make one branded QR code for the
spring-sale campaign in @Brand/campaigns.json. Use that entry's URL,
foreground color, and background color, put @Brand/logo.png in the center,
and save the result as out/spring-sale.png. Print the saved image's width
and height in pixels first, then open the file again with QrReader and print
the decoded text and whether it equals the campaign URL. The license key is
in the IRONQR_LICENSE_KEY environment variable.
A versão mais direta deste código pode falhar. Em nossas sondas, o código de liquidação de primavera no nível de correção de erro padrão com um logotipo dimensionado automaticamente foi salvo sem erro, depois lido como vazio ou lançou ObjectDisposedException no modo de escaneamento padrão do leitor. Um logotipo de 100 pixels em um código de 500 pixels foi lido corretamente.
Verifique a largura impressa primeiro. Em nossa sonda, opções de estilo sem tamanho definido produziram uma imagem de 49 pixels para este URL.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca C# de código QR do NuGet
- Inicie o Claude Code na pasta do projeto e escolha um modelo com
/model - Registre as regras de estilo do IronQR em
CLAUDE.mdpara que cada sessão comece com elas - Descreva cada variante a renderizar, desde o nível de correção e tamanho do logotipo até cores e tamanho de pixel
- Decodifique cada PNG salvo em ambos os modos de escaneamento
O que faz o Claude Code em um projeto de código QR .NET?
O agente escreve o renderizador, lê o arquivo da marca, salva um PNG por variante, decodifica cada arquivo e informa quais designs se mantêm. Você diz quais variantes a campanha precisa e revisa a tabela que retorna.
Códigos de marca tornam essa verificação valer a pena automatizar, porque tamanho do logotipo, nível de correção e tamanho de pixel interagem. Na execução testada, o IronQR salvou um logotipo manual em 30 por cento da largura em um código de 600 pixels e recusou a mesma proporção em 120 pixels para uma campanha, e outra campanha mostrou o oposto.
Nomeie o IronQR como a única biblioteca QR desde o primeiro prompt. Um agente que adivinha um nome de pacote pode instalar um sósia publicado para capturar esse palpite, um ataque chamado slopsquatting.
Como você configura o Claude Code?
Instale o Claude Code com o quickstart da Anthropic e faça login. Quando ele inicia em um terminal e responde, está pronto.
Como você configura um projeto no qual o Claude Code possa trabalhar?
Prepare o repositório antes do primeiro prompt. Um projeto de console .NET 9 que compila, um arquivo Brand/campaigns.json com cada URL e cores da campanha, e os arquivos do logotipo dão ao agente entradas reais para trabalhar. Inicie o Claude Code a partir daquela pasta para que a sessão esteja restrita a ela.
Claude Code lê CLAUDE.md no início de cada sessão, o que o torna o lugar para regras que devem sobreviver a um prompt. Uma vez que o Quickstart tenha adicionado o pacote, um segundo prompt escreve o arquivo.
Write CLAUDE.md in the repository root with a section called QR codes. It
should tell every later session that IronQR (NuGet package IronQR, pinned to
the version now in BrandQr.csproj, namespaces IronQr and IronQr.Enum) is the
only QR library allowed here; that IronQR member names are checked against
IronQr.xml inside the ironqr.slim folder of the local NuGet cache before use;
that QrStyleOptions is always given an explicit Dimensions and Margins; that
the key comes only from IRONQR_LICENSE_KEY at startup and is never written to
a file or printed; and that a QR image counts as finished only after the saved
PNG has been decoded back to its exact payload.
O caminho XML importa porque os tipos de estilo e leitura são entregues no pacote IronQR.Slim, do qual IronQR depende, então a lista de membros está naquela pasta do cache. Para guias além da lista de membros, o IronQR publica um índice para agentes em llms.txt.
Lide com a licença antes do primeiro render. Sem chave, tanto QrWriter.Write quanto QrReader.Read lançam uma LicensingException cuja mensagem lê "Licença de Produção Necessária", e não há saída de teste marcada com marca d'água para recorrer. Esse tipo de exceção não é público, então faça o programa verificar License.IsLicensed depois de definir a chave a partir de IRONQR_LICENSE_KEY em vez de pegar a exceção pelo nome. A página Chaves de Licença do IronQR cobre como obter uma chave e os lugares de onde o IronQR a lê.
Quais configurações do IronQR pertencem ao CLAUDE.md?
Cada linha foi verificada contra o IronQR 2026.10.1 construindo uma sonda ou executando uma com uma chave licenciada. Cole o bloco na seção códigos QR.
## QR codes: IronQR 2026.10.1 behavior
- new QrStyleOptions { ... } starts at Dimensions 0 and margins 0, which
renders one pixel per module. The constructor with arguments defaults to
300 and 10. Always set both.
- Margins are added outside Dimensions. Dimensions 600 with Margins 24
saves a 648 x 648 PNG. Margins has no getter, so read MarginTop and the
other sides.
- QrErrorCorrectionLevel.High is level Q (about 25 percent) and Highest is
level H (about 30 percent). QrWriter.Write without options uses Highest.
- Build QrOptions with its constructor. An object initializer leaves
Encoding at None, and Write throws IronQrEncodingException.
- QrLogo width and height 0 let IronQR choose the logo size. A manual size
it cannot read back throws IronQrException from Save.
- Save checks a changed foreground color. It does not check a changed
background color.
- qr.Verify(expected) takes the expected text, not a file path.
- Save(style) keeps the style on the QrCode, so a later Save() repeats it.
- Do not put QrImageInput in a using block. Its explicit IDisposable.Dispose
throws NotImplementedException after a successful read. Its public
Dispose() works.
- Read every saved PNG with QrScanMode.Auto and QrScanMode.OnlyBasicScan.
Módulos pretos sobre um fundo preto foram salvos sem exceção, e nenhum modo de escaneamento pôde decodificar o arquivo.
Como você controla o tamanho, margens e cores de um código QR?
Um objeto QrStyleOptions contém toda escolha visual. Save o aplica e retorna um bitmap que você escreve no disco com SaveAs. O nível de correção de erro é a única configuração que vive em outro lugar, em QrOptions, porque muda o próprio símbolo codificado.
Dimensions define o tamanho do código em pixels e Margins a zona silenciosa em todos os quatro lados, enquanto MarginTop e os outros lados definem um lado cada. Color pinta os módulos escuros e BackgroundColor a área clara e as margens. Logo leva um QrLogo com o bitmap, largura, altura e raio de canto.
Em nossa sonda, um código de 400 pixels com margens superiores e inferiores de 50 pixels e margens laterais de 20 pixels foi salvo em 440 x 500. O guia de redimensionamento, o guia de margens, e o guia de cores mostram cada configuração por conta própria.
Save sem argumento em um código que nunca foi estilizado retorna uma imagem de 250 x 250. Esse tamanho é um padrão interno.Quão grande pode ser um logotipo em cada nível de correção de erro?
Menor do que os percentuais de correção sugerem. Esses números contam os codewords que a decodificação Reed-Solomon pode reconstruir, e um logotipo central é apenas uma fonte de dano. Renderizamos o URL de liquidação de primavera em 600 pixels com um logotipo quadrado simples, deixamos o IronQR dimensioná-lo automaticamente e, em seguida, aumentamos um tamanho manual um por cento de cada vez até que o IronQR se recusou a salvá-lo.
| Nível | Recuperação documentada | Logotipo automático (largura, área) | Maior logotipo manual (largura, área) |
|---|---|---|---|
| Baixo | 7% | 20%, 4.0% | 23%, 5.3% |
| Médio | 15% | 30%, 9.0% | 31%, 9.6% |
| Alto | 25% | 32,5%, 10,6% | 39%, 15,2% |
| Maior | 30% | 32%, 10,2% | 44%, 19,4% |
Na montagem 2026.10.1, o dimensionamento automático tenta uma lista curta de frações da largura do código, de uma metade até um vigésimo, e mantém a primeira que seu leitor decodifica. Essa lista explica por que High e Highest ficam próximos a um terço da largura. Um tamanho manual vai mais alto, para entre cerca de 60 e 75 por cento da recuperação documentada por área, mas o IronQR verifica com seu próprio leitor em resolução total. Um segundo modo de escaneamento ainda pode falhar onde essa verificação passou.
Os valores dependem do payload. Um URL mais longo produz um símbolo mais denso com limites diferentes, então trate a tabela como a forma do equilíbrio e deixe a matriz medir suas próprias campanhas.
Como você testa cada variante do IronQR estilizada em um único prompt?
Peça a grade inteira em um único prompt e deixe o modo plano resolver o design primeiro. Pressione Shift+Tab até a barra de status mostrar o modo plano, depois envie o prompt.
Build Services/BrandedQrRenderer.cs, which renders one campaign from
@Brand/campaigns.json for a given QrErrorCorrectionLevel, logo mode, and
pixel size, and Services/ScanMatrix.cs, which renders every campaign at every
correction level (Low, Medium, High, Highest), with three logo modes (no
logo, a QrLogo of width and height 0 so IronQR sizes it, and a manual logo 30
percent of Dimensions wide that keeps the logo's aspect ratio), at the poster
and sticker sizes in the JSON. Call the matrix from Program.cs after the
spring-sale code. Save each PNG under out/matrix/. Decode every saved file
twice with a new QrReader each time, once with QrScanMode.Auto and once with
QrScanMode.OnlyBasicScan, and catch exceptions per file, including any that
Save throws. Write out/scan-matrix.csv with campaign, level, logo mode, size,
image width and height, the save result, and both read results, then print
how many variants decode to the exact URL in both modes. When the matrix has
run, have the general-purpose subagent check every IronQR member in the new
files against IronQr.xml and list any it cannot find.
Cada cláusula fecha uma forma de os resultados parecerem melhores do que são.
- Cada combinação é nomeada: três campanhas, quatro níveis, três modos de logotipo, e dois tamanhos fazem 72 variantes, então uma linha ausente em
out/scan-matrix.csvé visível. - Falhas de salvamento são linhas: um salvamento recusado é um resultado, e essas linhas mostram onde o limite de tamanho do logotipo se encontra.
- Um leitor novo para cada leitura: uma falha de leitura não pode afetar a próxima.
- Um segundo agente verifica a API: o subagente de propósito geral carrega
CLAUDE.md, que os subagentes Explore e Plan incorporados ignoram, então a verificação vê as regras do projeto.
O que você deve verificar antes de confiar no código IronQR gerado?
QrScanMode.Auto recorre ao escaneamento básico apenas quando seu modelo de detecção não encontra nada, e a própria documentação do enum o descreve como o modelo de detecção primeiro, depois "uma leitura de força bruta básica se nenhuma for encontrada". Quando o modelo encontra o código mas não pode decodificá-lo, Auto retorna um resultado vazio e o escaneamento básico nunca é executado.
O escaneamento básico decodificou todas as variantes do Quickstart que falharam acima, e a exceção vem de dentro do IronQR 2026.10.1. Em nossa execução de calibração da matriz completa, todos os arquivos que o Auto falhou tinham um logotipo, e seis dos oito eram em High ou Highest, os dois níveis com mais redundância para gastar em um logotipo. Na execução testada, com uma margem lisa de 10 pixels que o agente escolheu, dois dos oito erros do Auto não tinham logotipo algum.
Adicione estas verificações à mesma revisão.
- A construção: um membro inventado falha
dotnet build, e assim faz uma diretiva usando escritaIronQR, que usa a caixa do pacote enquanto o namespace éIronQr. - Os tamanhos: compare cada largura salva com o tamanho solicitado mais ambas as margens laterais. Um descompasso mostra um estilo que nunca chegou à chamada de salvamento.
- O payload: decodifique o arquivo no disco.
Verifycompara texto com a própria renderização na memória do IronQR, então um caminho de arquivo retorna falso e um arquivo escrito com o estilo errado passa despercebido.
O guia de checksum e tolerância a falhas cobre a leitura de códigos danificados e valida o que retorna. Para uma execução completa de tarefa IronQR de ponta a ponta com seus próprios critérios de passagem, veja o guia de assistentes de codificação AI.
O que os prompts produziram em uma execução real?
Enviamos os três prompts acima para o Claude Code em ordem, em uma sessão. O arquivo da marca continha três campanhas, um tamanho de pôster de 600 pixels e um tamanho de adesivo de 120 pixels, ao lado de um logotipo quadrado e uma marca de palavra ampla. Uma construção de Release separada de uma cópia limpa então reexecutou a matriz e escreveu um CSV idêntico, e uma decodificação independente de cada PNG salvo concordou com cada linha.
- Em sua primeira execução, a matriz combinou 0 de 72 variantes em ambos os modos. Depois que Claude Code removeu o bloco usando em
QrImageInput, 55 de 72 corresponderam. - IronQR recusou 9 variantes ao salvar, todas com o logotipo manual. Dos 63 arquivos que salvou, o escaneamento básico decodificou todos os 63 e Auto decodificou 55.
- Para o Quickstart, Claude Code escolheu um código de 300 pixels com margens de 10 pixels e um logotipo de 50 x 50. Seu PNG de 320 x 320 combinou com o URL na primeira leitura.
- O subagente não encontrou membros do IronQR ausentes de
IronQr.xml. - Cada prompt deixou uma construção de Release limpa sem edições manuais, e os totais da matriz são iguais à execução de calibração.
- Uma resposta digitada aprovou o plano do terceiro prompt no lugar da caixa de diálogo de plano, porque a sessão foi executada de forma não interativa.
Versões, modelos, tempos e a máquina de teste para este guia e seus derivados estão no registro de execução compartilhado.
Solução de problemas
- Aplique uma chave de licença no IronQR se a construção tiver êxito e a primeira gravação lançar uma exceção de licenciamento
- Adicione um logotipo aos códigos QR se salvar um logotipo dimensionado manualmente lançar IronQrException
- Defina os níveis de correção de erro do código QR se uma variante precisar de mais redundância para seu logotipo
Questões?
Se você tiver dúvidas, entre em contato com support@ironsoftware.com
Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.