Uso de la documentación de IronBarcode como base para Cursor
BarcodeReaderOptions.CropArea en IronBarcode acepta un IronSoftware.Drawing.Rectangle, no el tipo System.Drawing del mismo nombre, y un modelo que recurre a su memoria elige el tipo que conoce. El mismo hábito lo lleva a escribir dotnet add package IronBarcode, pero el paquete es BarCode y el espacio de nombres es IronBarCode.
Cursor solía resolver esto indexando un sitio de documentación mediante una mención @Docs. Esa mención ya no aparece en la documentación de Cursor. En su lugar, se pega un enlace en la indicación para que la herramienta web del agente consulte la página, o se proporcionan instrucciones mediante una regla o una habilidad. Las tres opciones dirigen al agente a páginas reales, sin esperar a que se cree un índice.
Cursor es un editor diseñado en torno a la IA, y su agente trabaja con dos alcances muy diferentes:
- Edición en línea y Tab funcionan donde está su cursor: con
Ctrl+K(Cmd+Ken una Mac) indica un cambio en una oración, y Tab predice su próxima edición. - Modo agente planifica cambios en varios archivos, compila, lee los errores e itera, mientras que el modo Plan acuerda primero el enfoque con usted.
Tab abre un portal a otro archivo cuando el siguiente cambio corresponde a ese archivo, y una edición en línea muestra las diferencias en el mismo lugar para que usted las acepte o rechace.
Las reglas solo se aplican al modo agente y al chat. La documentación de Cursor afirma claramente que las reglas no afectan a Cursor Tab ni a otras funciones de IA. Por lo tanto, una regla que haya guardado en un commit no se aplica cuando Tab sugiere un método.
Para que Cursor trabaje con códigos de barras basándose en la documentación, necesita dos archivos guardados en commits y un enlace pegado en la indicación. Esa preparación resulta especialmente útil para cambios precisos: limitar las opciones del lector, agregar una región de recorte, elegir una velocidad de lectura o identificar la corrección de imagen que permite leer un lote de escaneos deficientes.
Nada de esto se refiere a la puntuación de confianza del lector de IronBarcode, que tiene su propio ejemplo práctico.
Inicio rápidoAbra un proyecto de C# en Cursor y dé al agente una página para leer antes de que escriba.
In Program.cs, generate a Code 128 barcode for an asset tag and style it for a
printed label. Set the bar color and the background with ChangeBarCodeColor and
ChangeBackgroundColor, size it with ResizeTo, and print the value under the
bars. The license comes out of IRONBARCODE_LICENSE_KEY.
Work from https://ironsoftware.com/barcode/csharp/llms-full.txt, use only
members that appear in it, and tell me which page each styling call came from.
Los miembros de color y tamaño son fáciles de recordar a medias, por eso la indicación envía al agente a la página primero. La guía de personalización del estilo de códigos de barras nombra los tres exactamente.
Flujo de trabajo mínimo en 5 pasos
- Descargue la biblioteca de códigos de barras para C# desde NuGet
- Pegue el enlace
llms-full.txtde IronBarcode en cualquier indicación que solicite código para trabajar con códigos de barras - Guarde
skill.mdde IronBarcode como.cursor/skills/ironbarcode/SKILL.md - Guarde en un commit una regla de proyecto que fije la versión de BarCode y sus convenciones
- Compile, vuelva a leer cada código de barras y verifique cada nombre de API en la referencia de API
¿Qué modelo debería ejecutar su sesión de código de barrasí
Cursor es la única herramienta de esta serie en la que usted elige el modelo. Composer, su propio modelo para agentes, está optimizado para usar herramientas, editar archivos y trabajar en la terminal dentro del editor; su variante rápida es la opción predeterminada. El selector también incluye modelos de vanguardia de OpenAI, Anthropic, Google y SpaceXAI. Tab queda fuera de esa elección y se basa en sus ediciones recientes, el código circundante y los errores del linter.
La mayor parte de una sesión de trabajo con códigos de barras es de bajo costo y repetitiva. Usted agrega un formato, vuelve a compilar, decodifica el conjunto de pruebas y ajusta. De vez en cuando, un lote de escaneos reales no se puede decodificar y ningún error explica por qué; ese es el momento de cambiar a un modelo que razone más tiempo antes de editar. El modelo también determina cómo se escribe el código, así que fije la simbología, el tamaño de salida y la condición que debe cumplir la lectura posterior, en lugar de dejarlos a los valores predeterminados.
Aquí es donde las guías de la serie coinciden. Ejecute un modelo de Claude en Cursor y las notas de la guía de Claude Code se aplicarán a su salida. El modelo es el mismo. Solo cambia la interfaz.
¿Cómo hacer que Cursor se base en la documentación de IronBarcode?
Tres acciones sustituyen al antiguo índice y se complementan:
- Pegue el enlace: dirija al agente a
llms-full.txten lugar del centro de documentación, para que una sola URL le proporcione las guías, los ejemplos y los nombres de los miembros. - Guarde la habilidad en un commit: guarde el archivo
skill.mdpublicado por IronBarcode como.cursor/skills/ironbarcode/SKILL.md, establezcaname: ironbarcodepara que coincida con la carpeta y guárdelo en un commit. - Guarde la regla en un commit: la siguiente sección explica qué debe contener.
Cursor carga habilidades de agente desde .cursor/skills/ y .agents/skills/, en la raíz del proyecto o en un subdirectorio. Cada habilidad es una carpeta que contiene un archivo SKILL.md cuyo frontmatter incluye name y description. El agente carga una habilidad cuando parece pertinente para una tarea, y usted puede invocarla directamente escribiendo /ironbarcode. .agents/skills/ es la ruta neutral para el mismo archivo, por lo que Codex y Antigravity también lo cargan desde allí.
Si omite las tres acciones, el modelo responderá a partir de datos de entrenamiento que nunca se contrastaron con la versión actual. Los primeros errores aparecen en los nombres de métodos. BarcodeScanner.DecodeImageFile() parece una llamada real, pero falla al compilar.
Con una página para trabajar, las preguntas que habrían sido suposiciones se convierten en búsquedas.
Which options narrow a read to two symbologies inside a fixed region of a
larger image? Give me the exact class and property names, and quote the lines
you took them from in https://ironsoftware.com/barcode/csharp/llms-full.txt.
Si el agente no puede citar una página para la API que sugirió, verifíquela antes de basar más trabajo en ella.
BarcodeReaderOptions en lugar de buscar desplazándose por la documentación, y la respuesta cita la página de referencia de API de la que procede.¿Cómo escribir reglas de proyecto que recojan sus convenciones de IronBarcode?
Las reglas de proyecto van en una carpeta .cursor/rules en la raíz del repositorio. Están bajo control de versiones y se guardan en commits junto con el código, por lo que cada desarrollador obtiene el mismo comportamiento sin configuración adicional.
Cada regla es un archivo .mdc: un archivo Markdown con frontmatter YAML que establece description, globs y alwaysApply. Cursor busca en la carpeta de forma recursiva, por lo que admite subcarpetas. Un archivo .md simple en esa ubicación se ignora porque no tiene el frontmatter que lo activa. Una regla de IronBarcode tiene este aspecto.
---
description: IronBarcode conventions for barcode reading and writing in this project
globs: ["**/Services/**/*.cs", "**/Barcodes/**/*.cs"]
alwaysApply: false
---
# IronBarcode conventions
Applies to the barcode code in this folder only.
- IronBarcode (package BarCode, namespace IronBarCode) writes and reads every
barcode here. Never reach for a second barcode package.
- Reader options are explicit: set ExpectBarcodeTypes to the formats this
feature really reads, and reuse one BarcodeReaderOptions per format set
rather than allocating per call.
- Reads on a request path are async.
- CropArea takes IronSoftware.Drawing.Rectangle, not System.Drawing.
- Verified recipes: https://ironsoftware.com/barcode/csharp/skill.md
- If you are unsure a member exists, say so and cite the page. Do not guess a
method name that sounds plausible.
Decirle al modelo que la incertidumbre es aceptable es lo que detiene la API inventada, y una regla lo dice una vez para cada sesión que sigue.
Copie la línea globs a propósito. Una regla con alwaysApply: true se carga en cada solicitud y gasta contexto en trabajo que no tiene códigos de barras. Delimitarla a las carpetas que contienen código de barras la mantiene donde pertenece.
AGENTS.md simple, el mismo que usan ChatGPT Codex y Google Antigravity. No lleva frontmatter y, por lo tanto, tampoco patrones glob. Cursor lo lee en la raíz del proyecto y en subdirectorios, por lo que la ubicación en carpetas anidadas es la única forma de delimitar su alcance. Use .cursor/rules cuando necesite patrones glob, y AGENTS.md cuando quiera un archivo de instrucciones para varias herramientas.¿Qué modo se adapta al cambio?
Cursor ofrece más formas de editar que cualquier otra herramienta en esta serie. Elija por tamaño, desde una sola línea hasta todo el repositorio:
| Modo | Úselo cuando | Ejemplo de código de barras |
|---|---|---|
| Tab | La próxima edición es predecible | Repetir una opción de lector |
| Edición en línea | Un archivo, una oración | Restringir una lectura a dos formatos |
| Agente | El trabajo abarca varios archivos y necesita un ciclo de compilación | Un endpoint de etiquetas y un endpoint de escaneo |
| Modo Plan | La reescritura es demasiado grande para revisarla después | Migrar desde otra biblioteca de códigos de barras |
| Agente en la nube | Puede funcionar sin supervisión | Pruebas de ida y vuelta en cada formato |
¿Qué cambia una mención @?
Una mención @ entrega al agente lo que debe leer: un archivo, una carpeta, una terminal, un chat anterior, un diff de Git o el navegador. Referenciar el archivo que lee los códigos de barras es más eficaz que describirlo, porque una descripción pierde el detalle en el que se encuentra el error.
@Services/ScanService.cs @TestData/depot/
Read https://ironsoftware.com/barcode/csharp/llms-full.txt for the options.
Half the photos in TestData/depot/ come back empty. The reader options are
where this gets fixed, not the label generator. Name the setting that was
missing, and give me a decode rate for the folder before your change and after
it.
Una mención de carpeta sirve para trabajar en todo un módulo, y el agente puede consultar todo el código cuando usted no sabe qué archivo importa. Combinar el código con la documentación cubre ambas partes de la pregunta: el archivo muestra lo que su código hace ahora y la página muestra lo que realmente proporciona la biblioteca.
La configuración que permite leer un lote de fotos depende de cómo están dañadas, y ninguna descripción sustituye a que el agente pruebe las imágenes. Las páginas de velocidad de lectura y corrección de imagen cubren los ajustes individuales.
¿Cómo planificar y ejecutar una migración a IronBarcode?
Una reescritura no revisada que abarca muchos archivos se vuelve costosa durante una migración, porque deshacerla es más difícil que escribirla. Para esto existe el modo Plan. Presione Shift+Tab desde la entrada del chat, o elíjalo del menú desplegable de modo, y el agente hace preguntas aclaratorias, lee el código, y produce un plan que edita en el chat o como markdown antes de que aparezca cualquier código. Los planes se guardan en su directorio de inicio, y 'Guardar en el espacio de trabajo' mueve uno al repositorio para que el equipo lo revise.
The barcode code in @Labels/ belongs to another library. Using
https://ironsoftware.com/barcode/csharp/llms-full.txt, work out what replacing
it with IronBarcode would actually involve. Which files change, what the
equivalent call is for each thing the folder does today, and where the
documentation says no clean equivalent exists.
Public method signatures are fixed. If the plan needs one to change, say so in
the plan rather than changing it.
Lea el plan, corríjalo con una oración o dos y devuélvalo para que se implemente. El modo agente lee entonces el código, edita varios archivos, ejecuta comandos, verifica la salida e itera, por lo que la siguiente indicación puede ser breve.
Carry out the plan we agreed. Compile it, clear whatever errors come up, and
satisfy yourself that every symbology the folder handles still comes back out
the same as it went in. Show me the diff at the end. BarCode is the only package
that may appear in the .csproj.
Elimine esos dos límites y los agentes rediseñan el patrón de llamada mientras migran.
El trabajo que no necesita supervisión puede asignarse a un agente en la nube, antes llamado agente en segundo plano, mientras usted sigue trabajando en el editor. Un conjunto de pruebas de ida y vuelta es adecuado para ello, porque sus aserciones se basan en valores decodificados y no en detalles de implementación, por lo que puede escribirlas sin esperar a que termine la migración.
@Services/
Send this to a cloud agent while I keep working on the reader options.
Cover the migrated service with xUnit. Use a [Theory] over the symbologies it
supports rather than one [Fact] per format, so adding a format later costs one
line. Each case writes a sample value and reads it back, and the assertion is on
the decoded string and the decoded format together.
Then three edge cases as their own facts: an empty image returns no results
instead of throwing, a letters-only value is refused as EAN-13, and a missing
path fails with a readable message. Image bytes are off limits as an assertion
target.
Descartar comparaciones de bytes es lo que mantiene el conjunto estable entre plataformas.
¿Dónde viven los problemas de lectura?
Los códigos de barras ilegibles son el motivo de consulta más frecuente sobre IronBarcode, y la respuesta casi siempre está en las opciones del lector, no en la etiqueta. Cursor permite evitar la descripción del fallo: mencione el servicio y la carpeta de imágenes que fallan, y el editor trabajará a partir de ambos.
Photos of returns labels read fine on a handheld scanner but come back empty
from @Services/ScanService.cs, and a few product photos carrying no barcode at
all return a value. Samples of both are in @TestData/returns/.
Explain the cause of each before changing anything, then fix both in the reader
options.
Insistir primero en una explicación le proporciona un razonamiento que puede verificar, en lugar de un cambio que deba analizar mediante ingeniería inversa. Aquí los dos síntomas requieren correcciones opuestas. Las lecturas fallidas necesitan una lista de formatos más limitada, un área de recorte y el filtro de imagen adecuado, como explica la guía de códigos de barras no reconocidos. Los valores fantasma requieren RemoveFalsePositive y un umbral de confianza, tratados en la guía de falsos positivos.
Un fallo de despliegue suele deberse al .csproj o a la imagen del contenedor, no a un archivo de C#, y un agente con acceso a la terminal puede leer ambos y compilar por sí mismo.
@Dockerfile @LabelScan.csproj @Terminals
Reading works on Windows but fails in our Linux container. The failing build is
in the terminal output above, so read it there rather than asking me to paste it.
Check which BarCode package the project references and whether the image has
the native dependencies IronBarcode needs on Linux. Explain the cause, then
propose the change. Don't modify C# code unless the cause is there.
Diga explícitamente que no se debe tocar el C#. Dada una llamada fallida y sin límite, un agente recurrirá a un try/catch e informará el problema como resuelto. La guía de Docker en Linux enumera lo que realmente necesita la imagen.
¿Qué debería configurar primero?
Preparar el archivo de habilidad y una regla con alcance delimitado lleva unos quince minutos, y ambos se aplican a todas las sesiones posteriores. Pegar el enlace de documentación sigue siendo un hábito que debe mantener en cada indicación y solo ocupa una línea.
Aunque cambie el modelo del editor, siguen vigentes tres comprobaciones: el código compila, el código de barras se decodifica y cada miembro utilizado aparece en la API documentada de IronBarcode. Esas tres comprobaciones son exactamente lo que evalúa la guía de asistentes y agentes de programación con IA. Hay una página para Claude Code, ChatGPT Codex, GitHub Copilot y Google Antigravity.
Solución de problemas
- Aplicar una clave de licencia en IronBarcode cuando una edición en línea compila, pero no se puede ejecutar.
- Código de barras no reconocido cuando todavía es necesario ajustar las opciones del lector.
- Paquetes NuGet de IronBarcode cuando la versión en su regla de proyecto y la versión en el
.csprojno coinciden. - Ejecutar IronBarcode en Docker en Linux cuando las lecturas locales tienen éxito y las lecturas del contenedor no.
¿Preguntasí
Si tiene alguna pregunta, contacte 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.