IronBarcodeのドキュメントに基づくCursorの活用
IronBarcodeのBarcodeReaderOptions.CropAreaが受け取るのはIronSoftware.Drawing.Rectangleであり、System.Drawingの同名の型ではありません。しかし、記憶に頼るモデルは、なじみのある型を選びがちです。同様にdotnet add package IronBarcodeと出力することもありますが、正しいパッケージ名はBarCode、名前空間はIronBarCodeです。
Cursorは以前、@Docsメンションで参照するドキュメントサイトをインデックス化して、この問題に対応していました。現在のCursorのドキュメントには、このメンションは記載されていません。代わりに、プロンプトに貼り付けたリンクをエージェントのwebツールで取得する方法や、ルールまたはスキルで指示する方法を使います。いずれもエージェントに実際のページを参照させる方法で、インデックス化を待つ必要はありません。
CursorはAIを中心に設計されたエディターで、次の2つの機能では作業範囲が大きく異なります。
- インライン編集とTabはカーソルの位置で動作します。
Ctrl+K(MacではCmd+K)で変更内容を1文で指示し、Tabは次の編集を予測します。 - エージェントモードは複数ファイルにまたがる作業を計画し、ビルドを実行し、エラーを確認して修正を繰り返します。プランモードでは、まず開発者と方針を固めます。
次の変更箇所が別のファイルにある場合、Tabはそのファイルへの移動用ポータルを開きます。インライン編集ではその場に差分が表示され、承認または拒否できます。
ルールが適用されるのはエージェントモードとチャットのみです。Cursorのドキュメントには、ルールはCursor Tabや他のAI機能に影響しないと明記されています。そのため、コミットしたルールはTabがメソッドを提案するときには適用されません。
バーコード作業でCursorにドキュメントを参照させるには、2つのファイルをコミットし、プロンプトにリンクを貼り付けます。この準備は、読み取りオプションの絞り込み、クロップ領域の追加、読み取り速度の選択、読み取りに失敗するスキャン画像群に有効な画像補正の特定など、精密な変更で特に重要です。
本稿では、IronBarcodeのリーダー内部の信頼度スコアリングは扱いません。この機能には専用の実装例があります。
クイックスタートCursorでC#プロジェクトを開き、エージェントに書く前に読むページを提供してください。
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.
色やサイズに関するメンバー名は、曖昧な記憶に頼ると間違えやすいため、プロンプトでは先にページを参照させます。バーコードスタイリングガイドには、3つのメンバー名がすべて正確に記載されています。
5つのステップでミニマルワークフロー
- NuGetからC#バーコードライブラリをダウンロード
- バーコードのコードを生成するプロンプトには、IronBarcodeの
llms-full.txtへのリンクを貼り付けてください。 - IronBarcode の
skill.mdを.cursor/skills/ironbarcode/SKILL.mdとして保存してください。 - BarCodeのバージョンと規約を固定するプロジェクトルールをコミットしてください。
- ビルドし、すべてのバーコードを読み戻し、すべてのAPI名をAPIリファレンスと照合してください。
どのモデルをバーコードセッションで実行すべきですか?
Cursorは、このシリーズでモデルを選択できる唯一のツールです。 そのエージェントモデルであるComposerは、エディター内でのツール使用、ファイル編集、ターミナル作業に調整されており、その高速バリアントはデフォルトで使用されます。 ピッカーには、OpenAI、Anthropic、Google、SpaceXAIのフロンティアモデルもリストされています。Tabはこのモデル選択の対象外で、最近の編集、周囲のコード、リンターのエラーをもとに動作します。
バーコードセッションのほとんどは安価で反復的です。バーコード形式を追加し、再ビルドし、テストセットをデコードし、微調整します。 時折、実際のスキャンのバッチがデコードされず、エラーが原因を示さないときは、編集前により長く推論するモデルに切り替える時です。 モデルはコードにも影響を与えるため、シンボロジー、出力サイズ、読み戻し条件をデフォルトに任せるのではなく、固定してください。
ここは、このシリーズの各ガイドに共通する部分です。 Cursor で Claude モデルを実行すると、Claude Codeガイド の説明がその出力にも当てはまります。 モデルは同じです。 異なるのはインターフェースです。
CursorにIronBarcodeのドキュメントを参照させるには?
従来のインデックス化に代わる次の3つの方法は、組み合わせて使用できます。
- リンクを貼り付ける: ドキュメンテーションハブではなく
llms-full.txtを指し示し、一つのURLがガイド、例、メンバー名をエージェントの前に配置します。 - スキルをコミットする: IronBarcodeの公開された
skill.mdを.cursor/skills/ironbarcode/SKILL.mdとして保存し、name: ironbarcodeをフォルダ名に一致させて、コミットします。 - ルールをコミットする:次のセクションで何を入れるかを説明します。
Cursorは、プロジェクトルートまたはサブディレクトリにある.cursor/skills/と.agents/skills/からAgent Skillsを読み込みます。各スキルはフォルダーに格納され、その中のSKILL.mdのフロントマターにnameとdescriptionを記載します。エージェントは関連するタスクでスキルを読み込み、/ironbarcodeと入力して直接呼び出すこともできます。.agents/skills/は複数ツールで共有できる配置先で、CodexとAntigravityも同じファイルをそこから読み込みます。
3つとも省略すると、モデルは現在のリリースと照合されていない学習データに基づいて回答します。最初に誤りが出やすいのはメソッド名です。BarcodeScanner.DecodeImageFile()は実在する呼び出しに見えますが、ビルドに失敗します。
参照するページがあれば、推測に頼っていた質問も、調べて答えられるようになります。
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.
エージェントが提案したAPIのページを引用できない場合は、そのAPIを使った実装を進める前に確認してください。
BarcodeReaderOptionsの内容をスクロールして探す代わりに質問でき、回答には参照元のAPIリファレンスのページが示されます。IronBarcodeの規約をプロジェクトルールに記述するには?
プロジェクトルールはリポジトリルートの.cursor/rulesフォルダーに入ります。 それらはバージョン管理され、コードと共にコミットされるため、すべての開発者は設定なしで同じ動作を得ます。
各ルールは.mdcファイルです。これはdescription、globs、alwaysApplyを設定するYAMLフロントマターを持つMarkdownです。Cursorはフォルダーを再帰的に検索するため、サブフォルダーも使用できます。通常の.mdファイルは、ルールを有効にするフロントマターがないため無視されます。IronBarcodeのルールの例を次に示します。
---
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.
不確かな場合はそう伝えてよいとモデルに指示することで、実在しないAPIの生成を防げます。ルールに一度記載すれば、その後のすべてのセッションに適用されます。
globs行は対象範囲を意識してコピーしてください。alwaysApply: trueのルールはすべてのリクエストで読み込まれ、バーコードに関係のない作業でもコンテキストを消費します。バーコードのコードを含むフォルダーに対象を絞れば、必要な場面だけに適用できます。
AGENTS.mdも読み込みます。このファイルにはフロントマターがなく、グロブもありません。Cursorはプロジェクトルートとサブディレクトリで読み込むため、配置する階層でのみ適用範囲を指定できます。グロブパターンが必要な場合は.cursor/rulesを、複数ツールで指示ファイルを共有する場合はAGENTS.mdを使用します。どのモードが変更に適しているか?
Cursorはこのシリーズで他のツールよりも多くの編集方法を提供します。 1行の変更からリポジトリ全体まで、作業の規模に応じて選びます。
| モード | 使用する場合: | バーコード例 |
|---|---|---|
| Tab | 次の編集が予測できる場合 | 読み取りオプションの繰り返し |
| インライン編集 | 1ファイル内で、変更を1文で説明できる場合 | 読み取り対象を2つの形式に限定 |
| エージェント | 複数ファイルにまたがり、ビルドと修正の反復が必要な場合 | ラベル用とスキャン用のエンドポイント |
| プランモード | 書き換えの規模が大きく、完了後のレビューが困難な場合 | 別のバーコードライブラリからの移行 |
| クラウドエージェント | 無監視で実行できる | すべてのフォーマットにわたる往復テスト |
@メンションで何が変わりますか?
@メンションは、エージェントに読み取る対象を渡します。ファイル、フォルダー、ターミナル、以前のチャット、Git差分、ブラウザーなどを指定できます。バーコードを読み取るファイルは、説明するより直接参照する方が有効です。説明だけでは、バグの原因となる細部が抜け落ちるためです。
@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.
モジュール全体の作業にはフォルダーへのメンションが適しており、どのファイルが重要かを言えないときにはコードベース全体があります。 コードとドキュメントを組み合わせれば、問題の両面を把握できます。ファイルは今のコードが何をしているかを示し、ページはライブラリが実際に提供するものを示します。
一群の写真を救う設定は、写真がどのように損なわれたかに依存しており、説明だけでは、エージェントが実際の画像で動作を確かめる代わりにはなりません。 読み取り速度と画像補正ページが個別の設定をカバーしています。
IronBarcodeへの移行を計画して実行するには?
多くのファイルにわたる未レビューの書き換えは移行中に高価になります。それを元に戻すのは書くより難しいためです。 これのためにプランモードがあります。 チャット入力からShift+Tabを押すか、モードドロップダウンから選択し、エージェントが詳細な質問をし、コードベースを読み、コードを生成する前に、チャットまたはMarkdownで編集できる計画を作成します。 計画はホームディレクトリに保存され、[ワークスペースに保存]すると、チームがレビューするためにリポジトリに移動します。
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.
計画を読み、一文または二文で修正し、再びビルドに送ってください。 エージェントモードはその後、コードを読み、ファイル全体にわたって編集し、コマンドを実行し、出力を確認し、反復するため、次のプロンプトは短くても構いません。
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.
この2つの制約を省くと、エージェントは移行中に呼び出しパターンまで再設計してしまいます。
監督が不要な作業は、エディターでの作業を続けながら、クラウドエージェント(旧称バックグラウンドエージェント)に任せられます。ラウンドトリップテストスイートは、実装の詳細ではなくデコードした値を検証するため、移行の完了を待たずに作成でき、この用途に適しています。
@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.
バイト比較を除外することで、スイートはプラットフォーム間で安定します。
読み取りの問題はどこにありますか?
読み取れないバーコードはIronBarcodeで最も多い質問で、ほとんどの場合、原因はラベルではなく読み取りオプションにあります。Cursorでは、失敗を文章で説明する必要がありません。サービスと読み取りに失敗する画像のフォルダーをメンションすれば、エディターは両方を参照して作業できます。
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.
先に説明を求めれば、変更の意図を逆解析する手間を省き、根拠を検証できます。 ここでは2つの症状が逆方向の修正を必要とします。 読み取りの失敗には、バーコードが認識されないガイドが示すように、狭いフォーマットリスト、クロップエリア、適切な画像フィルターが必要です。 存在しないバーコードの誤検出にはRemoveFalsePositiveと信頼度のしきい値が必要であり、誤認識ガイドでカバーされています。
デプロイメントの失敗は通常.csprojまたはコンテナイメージに戻り、C#ファイルにではありません。ターミナルアクセスを持つエージェントは両方を読み取り、ビルドを実行できます。
@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.
C#のコードを変更しないよう明示してください。 失敗する呼び出しだけを示して変更範囲を制限しないと、エージェントはtry/catchを使用し、問題を解決済みとして報告します。 LinuxにおけるDockerガイドは、イメージが実際に必要なものをリストします。
まず何を設定すべきですか?
スキルファイルと1つのスコープされたルールは約15分かかり、その後のすべてのセッションに適用されます。 ドキュメンテーションリンクを貼り付けるのはプロンプトごとの習慣であり、1行かかります。
エディターの背後にあるモデルを変更しても、3つのチェックは維持されます:コードはコンパイルされ、バーコードはデコードされ、使用したすべてのメンバーがIronBarcodeのドキュメントAPIに表示されます。 それらの3つがちょうどAIコーディングアシスタントとエージェントガイドが測るものです。 Claude Code、ChatGPT Codex、GitHub Copilot、Google Antigravityのページがそれぞれあります。
トラブルシューティング
- インライン編集後にコンパイルは通るものの実行に失敗する場合は、IronBarcodeにライセンスキーを適用する
- 読み取りオプションをさらに調整する必要がある場合は、バーコードが認識されない
- プロジェクトルールのバージョンと
.csprojのバージョンが異なる場合は、IronBarcode NuGet パッケージを確認してください。 - ローカルで読み取りが成功し、コンテナでの読み取りが失敗するとき、LinuxにおけるDockerでIronBarcodeを実行する
ご質問はありますか?
質問がある場合は、support@ironsoftware.com にお問い合わせください。
Curtis Chauは、カールトン大学でコンピュータサイエンスの学士号を取得し、Node.js、TypeScript、JavaScript、およびReactに精通したフロントエンド開発を専門としています。直感的で美しいユーザーインターフェースを作成することに情熱を持ち、Curtisは現代のフレームワークを用いた開発や、構造の良い視覚的に魅力的なマニュアルの作成を楽しんでいます。