Cómo usar IronQR con Claude Code
El equipo de marketing requiere que cada código QR de campaña use el color azul marino de la marca, incluya el logo en el centro y esté disponible en tamaños de póster y etiqueta. Sin embargo, cada opción de estilo adicional puede reducir la fiabilidad del escaneo. Por ejemplo, un logo puede oscurecer módulos, un primer plano claro puede disminuir el contraste, y tamaños de impresión más pequeños reducen la densidad de píxeles. Un código QR puede parecer correcto en pantalla pero fallar en su uso en el mundo real. Claude Code, el agente de codificación de Anthropic, opera en terminales, VS Code, JetBrains, aplicaciones de escritorio y la web. En cualquier entorno, lee el proyecto, edita archivos y ejecuta comandos, por lo que puede renderizar códigos con estilo, decodificar archivos guardados y ajustar el estilo hasta que se conserve la carga útil.
IronQR genera y lee códigos QR dentro del mismo proceso .NET, por lo que el agente puede escanear después de cada cambio. La biblioteca rechaza automáticamente algunos diseños ilegibles. Un logo de tamaño manual que cubre demasiado, o un color de primer plano demasiado similar a un fondo blanco, desencadena una IronQrException al guardar. Otras opciones de estilo pueden guardarse con éxito pero seguir fallando al decodificarse más tarde. El enfoque más fiable es probar una matriz de variantes con estilo y decodificar cada PNG guardado. Esta guía explica cómo configurar Claude Code para este proceso, con tres indicaciones probadas y el comportamiento de IronQR del que depende cada una.
Un único ajuste de modelo admite las tres indicaciones. El alias opusplan usa Opus en modo plan y Sonnet de otra manera, lo cual se adapta a una sesión donde solo la construcción de la matriz requiere planificación.
Abra la carpeta del proyecto en un terminal, inicie Claude Code y ejecute /model opusplan. Escriba @ antes de una ruta de archivo para entregar a Claude Code ese archivo, luego envíe la solicitud.
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.
La versión más directa de este código puede fallar. En nuestras pruebas, el código de venta de primavera al nivel de corrección de errores predeterminado con un logo de tamaño automático se guardó sin error, luego se leyó vacío o lanzó ObjectDisposedException en el modo de escaneo predeterminado del lector. Un logo manual de 100 píxeles en un código de 500 píxeles se leyó correctamente.
Verifique primero el ancho impreso. En nuestra prueba, las opciones de estilo sin tamaño definido produjeron una imagen de 49 píxeles para esta URL.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de códigos QR C# desde NuGet
- Inicie Claude Code en la carpeta del proyecto y elija un modelo con
/model - Registre las reglas de estilo de IronQR en
CLAUDE.mdpara que cada sesión comience con ellas. - Describa cada variante a renderizar, desde el nivel de corrección y el tamaño del logotipo hasta los colores y el tamaño de píxeles.
- Decodifique cada PNG guardado en ambos modos de escaneo.
¿Qué hace Claude Code en un proyecto de códigos QR de .NET?
El agente escribe el renderizador, lee el archivo de la marca, guarda un PNG por variante, decodifica cada archivo y reporta qué diseños se mantienen. Usted dice qué variantes necesita la campaña y revisa la tabla que regresa.
Los códigos de marca hacen que esa verificación valga la pena automatizar, porque el tamaño del logotipo, el nivel de corrección y el tamaño de píxeles interactúan. En la ejecución probada, IronQR guardó un logo manual en el 30 por ciento del ancho en un código de 600 píxeles y rechazó la misma proporción a 120 píxeles para una campaña, y otra campaña mostró lo contrario.
Nombre a IronQR como la única biblioteca QR desde la primera indicación. Un agente que adivine un nombre de paquete puede instalar uno similar publicado para atrapar esa adivinanza, un ataque llamado slopsquatting.
¿Cómo configuras Claude Code?
Instala Claude Code con el inicio rápido de Anthropic y accede. Cuando comienza en un terminal y responde, está listo.
¿Cómo configuras un proyecto en el que Claude Code pueda trabajar?
Prepare el repositorio antes de la primera indicación. Un proyecto de consola .NET 9 que construye, un archivo Brand/campaigns.json con la URL y los colores de cada campaña, y los archivos de logotipo dan al agente entradas reales para trabajar. Inicie Claude Code desde esa carpeta para que la sesión esté delimitada a ella.
Claude Code lee CLAUDE.md al inicio de cada sesión, lo que lo convierte en el lugar para reglas que deberían sobrevivir a una sola indicación. Una vez que el Quickstart ha agregado el paquete, una segunda indicación escribe el archivo.
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.
La ruta XML importa porque los tipos de estilo y lectura se envían en el paquete IronQR.Slim, del cual IronQR depende, por lo que la lista de miembros se encuentra en esa carpeta del caché. Para guías más allá de la lista de miembros, IronQR publica un índice para agentes en llms.txt.
Maneje la licencia antes del primer renderizado. Sin clave, tanto QrWriter.Write como QrReader.Read lanzan una LicensingException cuyo mensaje indica "Se requiere licencia de producción", y no hay salida de prueba con marca de agua para recurrir. Ese tipo de excepción no es público, por lo que el programa debe verificar License.IsLicensed después de establecer la clave desde IRONQR_LICENSE_KEY en lugar de capturar la excepción por nombre. La página de Claves de licencia de IronQR cubre cómo obtener una clave y de dónde la lee IronQR.
¿Qué configuraciones de IronQR pertenecen a CLAUDE.md?
Cada línea se verificó contra IronQR 2026.10.1 al construir una prueba o al ejecutar una con una clave con licencia. Pegue el bloque bajo la sección de 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 negros sobre un fondo negro se guardaron sin una excepción, y ningún modo de escaneo pudo decodificar el archivo.
¿Cómo se controlan el tamaño, márgenes y colores de un código QR?
Un objeto QrStyleOptions contiene cada opción visual. Save lo aplica y devuelve un mapa de bits que se escribe en el disco con SaveAs. El nivel de corrección de errores es la única configuración que vive en otro lugar, en QrOptions, porque cambia el símbolo codificado en sí mismo.
Dimensions establece el tamaño del código en píxeles y Margins la zona silenciosa en los cuatro lados, mientras que MarginTop y los otros lados establecen un lado cada uno. Color pinta los módulos oscuros y BackgroundColor el área clara y los márgenes. Logo toma un QrLogo con el mapa de bits, el ancho, la altura y el radio de esquina.
En nuestra prueba, un código de 400 píxeles con márgenes superior e inferior de 50 píxeles y márgenes laterales de 20 píxeles guardado a 440 x 500. La guía de redimensionamiento, la guía de márgenes, y la guía de colores muestran cada configuración por sí sola.
Save sin argumento en un código que nunca ha sido estilizado devuelve una imagen de 250 x 250. Ese tamaño es un valor por defecto interno.¿Qué tan grande puede ser un logo en cada nivel de corrección de errores?
Más pequeño de lo que sugieren los porcentajes de corrección. Esas cifras cuentan las palabras de código que el decodificador de Reed-Solomon puede reconstruir, y un logotipo central es solo una fuente de daño. Renderizamos la URL de la venta de primavera a 600 píxeles con un logotipo cuadrado simple, dejamos que IronQR lo dimensionara automáticamente, y luego aumentamos un tamaño manual uno por ciento a la vez hasta que IronQR se negó a guardarlo.
| Nivel | Recuperación documentada | Logo automático (ancho, área) | Logo manual más grande (ancho, área) |
|---|---|---|---|
| Bajo | 7% | 20%, 4.0% | 23%, 5.3% |
| Medio | 15% | 30%, 9.0% | 31%, 9.6% |
| Alta | 25% | 32.5%, 10.6% | 39%, 15.2% |
| Más alto | 30% | 32%, 10.2% | 44%, 19.4% |
En la ensambladura 2026.10.1, el dimensionamiento automático intenta una lista corta de fracciones del ancho del código, desde la mitad hasta un vigésimo, y conserva la primera que su lector decodifica. Esa lista explica por qué High y Highest aterrizan cerca de un tercio del ancho. Un tamaño manual va más alto, entre aproximadamente el 60 y el 75 por ciento de la recuperación documentada por área, pero IronQR lo verifica con su propio lector a plena resolución. Un segundo modo de escaneo aún puede fallar donde esa verificación pasó.
Las cifras dependen de la carga útil. Una URL más larga produce un símbolo más denso con diferentes límites, así que trate la tabla como la forma de la compensación y deje que la matriz mida sus propias campañas.
¿Cómo se prueba cada variante de IronQR estilizada en una indicación?
Solicite toda la rejilla en una sola indicación y deje que el modo plan determine el diseño primero. Presione Shift+Tab hasta que la barra de estado muestre el modo plan, luego envíe la indicación.
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 cierra una forma en que los resultados podrían parecer mejores de lo que son.
- Cada combinación está nombrada: tres campañas, cuatro niveles, tres modos de logotipo y dos tamaños hacen 72 variantes, por lo que una fila faltante en
out/scan-matrix.csves visible. - Las fallas de guardado son filas: un guardado rechazado es un resultado, y esas filas muestran dónde está el límite de tamaño del logo.
- Un lector nuevo para cada lectura: una lectura fallida no puede afectar a la siguiente.
- Un segundo agente verifica la API: el subagente de propósito general carga
CLAUDE.md, que los subagentes Explore y Plan incorporados omiten, por lo que la verificación ve las reglas del proyecto.
¿Qué debe verificar antes de confiar en el código generado por IronQR?
QrScanMode.Auto regresa al escaneo básico solo cuando su modelo de detección no encuentra nada, y la documentación propia del enum lo describe como el modelo de detección primero, y luego "una lectura de fuerza bruta básica si no se encuentran". Cuando el modelo encuentra el código pero no puede decodificarlo, Auto retorna un resultado vacío y el escaneo básico nunca se ejecuta.
El escaneo básico decodificó cada variante Quickstart que falló arriba, y la excepción proviene del interior de IronQR 2026.10.1. En nuestra ejecución de calibración de la matriz completa, cada archivo que Auto falló tenía un logotipo, y seis de los ocho estaban en High o Highest, los dos niveles con más redundancia para gastar en un logotipo. En la ejecución probada, con un margen plano de 10 píxeles que el agente eligió, dos de los ocho errores de Auto no tenían logotipo en absoluto.
Agregue estas verificaciones a la misma revisión.
- La construcción: un miembro inventado falla
dotnet build, y también lo hace una directiva using escritaIronQR, que usa el casing del paquete mientras el namespace esIronQr. - Los tamaños: compare cada ancho guardado con el tamaño solicitado más ambos márgenes laterales. Una discrepancia muestra un estilo que nunca alcanzó la llamada de guardado.
- La carga útil: decodifique el archivo en el disco.
Verifycompara texto con el propio renderizado en memoria de IronQR, por lo que una ruta de archivo devuelve false y un archivo escrito con el estilo incorrecto pasa desapercibido.
La guía de checksum y tolerancia a fallos cubre la lectura de códigos dañados y la validación de lo que regresa. Para una ejecución completa de tarea de IronQR de principio a fin con sus propios criterios de aprobación, consulte la guía de asistentes de codificación AI.
¿Qué produjeron los prompts en una ejecución real?
Enviamos las tres indicaciones anteriores a Claude Code en orden, en una sola sesión. El archivo de la marca contenía tres campañas, un tamaño de póster de 600 píxeles y un tamaño de etiqueta de 120 píxeles, junto a un logo cuadrado y una marca de palabra ancha. Una construcción Release separada de una copia limpia luego volvió a ejecutar la matriz y escribió un CSV idéntico, y una decodificación independiente de cada PNG guardado coincidió con cada fila.
- En su primera ejecución, la matriz coincidió 0 de 72 variantes en ambos modos. Después de que Claude Code eliminó el bloque using en
QrImageInput, hubo coincidencia con 55 de 72. - IronQR rechazó 9 variantes al guardar, cada una con el logo manual. De los 63 archivos que guardó, el escaneo básico decodificó los 63 y Auto decodificó 55.
- Para el Quickstart, Claude Code eligió un código de 300 píxeles con márgenes de 10 píxeles y un logo de 50 x 50. Su PNG de 320 x 320 coincidió con la URL en la primera lectura.
- El subagente no encontró ningún miembro de IronQR que faltara en
IronQr.xml. - Cada indicación dejó una construcción Release limpia sin ediciones manuales, y los totales de la matriz igualan la corrida de calibración.
- Una respuesta tipificada aprobó el plan de la tercera indicación en lugar del cuadro de diálogo de plan, porque la sesión se ejecutó de manera no interactiva.
Versiones, modelos, tiempos y la máquina de prueba para esta guía y sus hermanas se encuentran en el registro de ejecución compartido.
Solución de problemas
- Aplique una clave de licencia en IronQR si la construcción tiene éxito y la primera escritura lanza una excepción de licencia.
- Agregue un logo a los códigos QR si guardar un logo de tamaño manual lanza IronQrException.
- Establezca niveles de corrección de errores de códigos QR si una variante necesita más redundancia para su logo.
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.