Como fundamentar o Cursor na documentação do IronBarcode
BarcodeReaderOptions.CropArea no IronBarcode requer um IronSoftware.Drawing.Rectangle, não o tipo System.Drawing com o mesmo nome, e um modelo que se baseia na memória recorre ao tipo mais familiar. O mesmo hábito escreve dotnet add package IronBarcode, mas o pacote é BarCode e o namespace é IronBarCode.
Cursor costumava responder a isso indexando um site de documentação por trás de uma menção @Docs. Essa menção não aparece mais na documentação do Cursor. O que está em seu lugar é um link colado na solicitação, que a ferramenta web do agente busca, ou orientação contida em uma regra ou habilidade. Todos os três direcionam o agente para páginas reais, e nenhum deles espera por um índice.
Cursor é um editor com foco em IA, e seu agente atua em dois escopos muito diferentes:
- Edição inline e Tab funcionam na posição do cursor: com
Ctrl+K(Cmd+Kem um Mac), você descreve uma alteração em uma frase, e o Tab prevê sua próxima edição. - Modo Agente planeja entre arquivos, executa a compilação, lê os erros e itera, enquanto o modo Plano faz com que ele primeiro estabeleça a abordagem com você.
O Tab abre um portal para outro arquivo quando a próxima alteração precisa ser feita nele, e uma edição inline mostra o diff no próprio local para você aceitar ou rejeitar.
As regras se aplicam apenas ao modo agente e ao chat. A documentação do Cursor afirma claramente que elas não afetam o Cursor Tab nem outros recursos de IA. Portanto, uma regra salva em um commit não é usada quando o Tab sugere um método.
Fundamentar o trabalho do Cursor com códigos de barras exige dois arquivos salvos em commits e um link colado no prompt. Essa preparação importa mais em mudanças precisas, restringindo opções de leitura, adicionando uma região de corte, escolhendo uma velocidade de leitura ou identificando a única correção de imagem que resgata um lote de digitalizações ruins.
Nada aqui diz respeito à pontuação de confiança dentro do leitor do IronBarcode, que tem seu próprio exemplo prático.
Início RápidoAbra um projeto C# no Cursor e dê ao agente uma página para ler antes que ele escreva.
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.
Os membros de cor e dimensionamento são fáceis de lembrar pela metade, por isso o prompt envia o agente para a página primeiro. O guia de estilo do código de barras nomeia todos os três exatamente.
Fluxo de trabalho mínimo em 5 passos
- Baixe a biblioteca de códigos de barras C# do NuGet
- Cole o link
llms-full.txtdo IronBarcode em qualquer prompt que gere código para trabalhar com códigos de barras - Salve o
skill.mddo IronBarcode como.cursor/skills/ironbarcode/SKILL.md - Faça commit de uma regra de projeto que fixe a versão do BarCode e suas convenções
- Compile, leia novamente todos os códigos de barras e confira todos os nomes de API na referência de API
Qual modelo deve rodar sua sessão de código de barras?
Cursor é a única ferramenta nesta série onde você escolhe o modelo. Composer, seu próprio modelo voltado a tarefas de agentes, é ajustado para uso de ferramentas, edições de arquivos e trabalho no terminal dentro do editor, e sua variante rápida é o que você obtém por padrão. O seletor também lista modelos de fronteira de OpenAI, Anthropic, Google e SpaceXAI. O Tab está fora dessa escolha e funciona a partir das suas edições recentes, do código ao redor e dos erros do lint.
A maior parte de uma sessão de código de barras é barata e repetitiva. Você adiciona um formato, recompila, decodifica o conjunto de teste e ajusta. De vez em quando, um lote de digitalizações reais não decodifica e nenhum erro diz por quê, e esse é o momento de mudar para um modelo que dedique mais tempo ao raciocínio antes de editar. O modelo também molda o código, então fixe a simbologia, o tamanho de saída e o critério de releitura em vez de deixá-los no padrão.
É aqui que os temas da série se cruzam. Execute um modelo Claude no Cursor e as notas no guia do Claude Code se aplicam à sua saída. O modelo é o mesmo. Apenas a interface difere.
Como fundamentar o Cursor na documentação do IronBarcode?
Três ações substituem o antigo índice e se complementam:
- Cole o link: aponte para
llms-full.txtem vez do hub de documentação, de modo que uma única URL coloque os guias, os exemplos e os nomes dos membros na frente do agente. - Faça commit da habilidade: salve o
skill.mdpublicado do IronBarcode como.cursor/skills/ironbarcode/SKILL.md, definaname: ironbarcodepara coincidir com a pasta e faça commit do arquivo. - Faça commit da regra: a próxima seção cobre o que vai nela.
O Cursor carrega habilidades de agente de .cursor/skills/ e .agents/skills/, na raiz do projeto ou em um subdiretório. Cada habilidade fica em uma pasta que contém um SKILL.md com name e description no frontmatter. O agente carrega uma habilidade quando ela parece relevante para a tarefa, e digitar /ironbarcode a invoca diretamente. .agents/skills/ é o caminho neutro para o mesmo arquivo, então Codex e Antigravity o carregam de lá também.
Pule todos os três e o modelo responde a partir de dados de treinamento que nunca foram verificados contra a versão atual. Os nomes dos métodos são os primeiros a sair errados. BarcodeScanner.DecodeImageFile() soa como uma chamada real e falha na compilação.
Com uma página para trabalhar, perguntas que teriam sido suposições se tornam consultas.
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.
Se o agente não puder citar uma página para a API que sugeriu, verifique antes de usá-la como base.
BarcodeReaderOptions é algo que você interroga em vez de rolar, e a resposta cita a página de referência da API de onde veio.Como você escreve regras de projeto que codificam suas convenções do IronBarcode?
As regras do projeto vão em uma pasta .cursor/rules na raiz do repositório. Elas estão sob controle de versão, salvas em commits junto com o código, para que todos os desenvolvedores tenham o mesmo comportamento sem ajustes.
Cada regra é um arquivo .mdc, que é markdown com frontmatter YAML que define description, globs e alwaysApply. O Cursor pesquisa a pasta recursivamente, então subpastas funcionam. Um arquivo .md simples lá é ignorado, porque não tem frontmatter para ativá-lo. Uma regra do IronBarcode se parece com isto.
---
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.
Informar o modelo de que a incerteza é aceitável é o que impede a API inventada, e uma regra diz isso uma vez para cada sessão que se segue.
Copie a linha globs de forma consciente. Uma regra com alwaysApply: true carrega em cada solicitação e gasta contexto em trabalho que não contém códigos de barras. Restringir a regra às pastas com código que trabalha com códigos de barras mantém sua aplicação no escopo adequado.
AGENTS.md simples, o mesmo arquivo que o ChatGPT Codex e o Google Antigravity usam. Ele não possui frontmatter e, portanto, sem globs, e Cursor lê na raiz do projeto e em subdiretórios, então o aninhamento é a única limitação que oferece. Use .cursor/rules quando quiser padrões glob, e AGENTS.md quando quiser um arquivo de instruções para várias ferramentas.Qual modo se encaixa na mudança?
Cursor oferece mais maneiras de editar do que qualquer outra ferramenta nesta série. Escolha pelo tamanho, de uma única linha ao repositório inteiro:
| Modo | Use-o quando | Exemplo de código de barras |
|---|---|---|
| Tab | A próxima edição é previsível | Repetir uma opção de leitura |
| Edição inline | Um arquivo, uma frase | Restringir uma leitura a dois formatos |
| Agente | Trabalho abrange arquivos e precisa de um loop de compilação | Um endpoint de etiquetas e um endpoint de leitura |
| Modo de plano | A reescrita é grande demais para revisar depois | Migrando de outra biblioteca de códigos de barras |
| Agente na nuvem | Ele pode rodar sem supervisão | Testes de ida e volta em todos os formatos |
O que uma menção @ muda?
Uma menção @ passa para o agente o que ler, que pode ser um arquivo, uma pasta, um terminal, um chat anterior, um diff do Git ou o navegador. Referenciar o arquivo que lê códigos de barras supera descrevê-lo, porque uma descrição deixa escapar o detalhe em que está o bug.
@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.
Uma menção de pasta serve para trabalho a nível de módulo, e todo o código base está lá quando você não pode dizer qual arquivo importa. Juntar o código com a documentação cobre ambas as metades da questão: o arquivo mostra o que seu código faz agora, e a página mostra o que a biblioteca realmente oferece.
Qual configuração resgata um lote de fotos depende de como elas estão danificadas, e nenhuma descrição substitui executar o agente contra as imagens. As páginas de velocidade de leitura e correção de imagem cobrem as configurações individuais.
Como planejar e executar uma migração para IronBarcode?
Uma reescrita sem revisão em muitos arquivos se torna cara durante uma migração, porque desfazê-la é mais difícil do que escrevê-la. Modo de plano existe para isso. Pressione Shift+Tab na entrada do chat, ou escolha no menu suspenso de modo, e o agente faz perguntas de esclarecimento, lê o código base e produz um plano que você edita no chat ou como markdown antes que qualquer código apareça. Planos são salvos no seu diretório pessoal, e "Salvar para o espaço de trabalho" move um para dentro do repositório para o time revisar.
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.
Leia o plano, corrija-o com uma ou duas frases e envie-o de volta para execução. O modo agente então lê o código, edita vários arquivos, executa comandos, verifica a saída e itera, para que o próximo prompt possa ser curto.
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.
Sem esses dois limites, os agentes redesenham o padrão de chamada durante a migração.
Trabalho que não precisa de supervisão pode ir para um agente na nuvem, anteriormente chamado de agente em segundo plano, enquanto você continua trabalhando no editor. Uma suíte de testes de ida e volta se adapta a isso, porque suas asserções verificam valores decodificados em vez de detalhes de implementação, então os testes podem ser escritos antes da migração.
@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.
Excluir comparações de bytes é o que mantém a suíte estável em todas as plataformas.
Onde estão os problemas de leitura?
Problemas com códigos de barras ilegíveis são a dúvida mais frequente sobre o IronBarcode, e a resposta quase sempre está nas opções do leitor e não na etiqueta. O que o Cursor adiciona é que você não precisa descrever a falha. Mencione o serviço e a pasta de imagens com falhas, e o editor trabalha 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.
Exigir uma explicação antes da alteração fornece um raciocínio que pode ser verificado, em vez de uma mudança que precisa ser decifrada. Aqui os dois sintomas precisam de correções opostas. Falhas de leitura exigem uma lista de formatos mais restrita, uma área de corte e o filtro de imagem certo, que o guia de Código de Barras Não Reconhecido analisa. Valores fantasmas exigem RemoveFalsePositive e um limiar de confiança, cobertos no guia de falsos positivos.
Uma falha de implantação geralmente tem origem no .csproj ou na imagem do contêiner, não em um arquivo C#, e um agente com acesso ao terminal pode ler ambos e executar a compilação.
@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 explicitamente que o C# não deve ser tocado. Dada uma chamada falha e nenhum limite, um agente recorrerá a um try/catch e relatará o problema como resolvido. O guia Docker no Linux lista o que a imagem realmente precisa.
O que você deve configurar primeiro?
Preparar o arquivo de habilidade e uma regra com escopo definido leva cerca de quinze minutos, e eles se aplicam a cada sessão depois disso. Colar o link da documentação torna-se um hábito a cada prompt, e custa uma linha.
Mude o modelo por trás do editor e ainda restam três verificações: o código compila, o código de barras decodifica, e cada membro que você usou aparece na API documentada do IronBarcode. Esses três são exatamente o que o guia de assistentes e agentes de programação com IA mede. Há uma página para Claude Code, ChatGPT Codex, GitHub Copilot e Google Antigravity.
Solução de problemas
- Aplique uma Chave de Licença no IronBarcode quando uma edição inline compilar, mas a execução falhar.
- Código de Barras Não Reconhecido quando as opções de leitura ainda precisam ser ajustadas.
- Pacotes NuGet do IronBarcode quando a versão na regra do seu projeto e a versão no
.csprojnão concordam. - Execute IronBarcode no Docker no Linux quando leituras locais tiverem sucesso e leituras no contêiner não.
Dúvidas?
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.