如何使用IronQR和Claude Code
市场团队要求每个活动二维码使用品牌的海军色,在中心展示标志,并提供海报和贴纸两种大小。 然而,每一个额外的样式选择都可能降低扫描可靠性。 例如,一个标志可能会遮挡模块,浅色前景会降低对比度,而较小的打印尺寸会降低像素密度。 一个二维码在屏幕上看起来是正确的,但在实际使用中可能仍会失败。 Claude Code是Anthropic的编码代理,可以在终端、VS Code、JetBrains、桌面应用和网络上运行。 在任何环境中,它都会读取项目、编辑文件并运行命令,因此可以渲染样式代码、解码保存的文件,并调整样式直到有效载荷被保留。
IronQR在相同的.NET进程中生成和读取二维码,所以代理可以在每次更改后进行扫描。 该库会自动拒绝某些不可读的设计。 一个手动调整的尺寸过大的标志,或者前景色过于接近白色背景,在保存时会触发IronQrException。 其他样式选择可能成功保存,但之后仍无法解码。 最可靠的方法是测试一个样式变种矩阵,并解码每个保存的PNG。 本指南解释了如何为此过程配置Claude Code,包括三个经过测试的提示和每个依赖的IronQR行为。
一个单一的模型设置支持这三个提示。opusplan别名在计划模式下使用Opus,其他情况下使用Sonnet,这适用于仅需规划矩阵构建的会话。
在终端中打开项目文件夹,启动Claude Code,运行/model opusplan。 在文件路径前输入@将该文件交给Claude Code,然后发送请求。
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.
此代码的最直接版本可能会失败。 在我们的探测中,以默认错误校正级别自动调整大小的标志,春季折扣代码在保存时没有错误,但在读取时返回空或在读取器的默认扫描模式下抛出ObjectDisposedException。 在500像素的代码上,手动100像素的标志读取回正确无误。
首先检查打印的宽度。在我们的探测中,没有设置尺寸的样式选项为该URL生成了一个49像素的图像。
最小工作流程(5 个步骤)
- 从NuGet下载C#二维码库
- 在项目文件夹中启动Claude Code,并选择一个带有
/model的模型。 - 将IronQR样式规则记录在
CLAUDE.md中,以便每个会话都从它们开始。 - 描述每个要渲染的变种,从校正级别和标志大小到颜色和像素大小。
- 在两种扫描模式下解码每个保存的PNG。
Claude Code在.NET二维码项目中做什么?
代理编写渲染器,读取品牌文件,为每个变种保存一个PNG,解码每个文件,并报告哪种设计能扛住。你可以说出该活动需要哪些变种,并查看返回的表格。
品牌代码使得自动化检查变得有意义,因为标志大小、校正级别和像素大小会相互作用。 在经过测试的运行中,IronQR在600像素代码上以30%宽度保存了一致的标志,但在一个活动中拒绝在120像素上的相同比例,另一个活动显示了相反的情况。
在第一个提示中将IronQR命名为唯一的二维码库。 一个猜测包名的代理可以安装一个发布的相似物以捕获该猜测,这种攻击称为slopsquatting。
如何设置Claude Code?
使用Anthropic的快速入门安装Claude Code并登录。 当它在终端中启动并回复时,证明它已准备好。
如何设置一个Claude Code可以工作的项目吗?
在第一个提示前准备好存储库。 一个构建的.NET 9控制台项目,一个包含每个活动的URL和颜色的Brand/campaigns.json文件,以及标志文件为代理提供了实际的输入以开始工作。 从该文件夹启动Claude Code,以便会话仅限于此范围。
Claude Code在每个会话开始时读取CLAUDE.md,这使得它成为应超越一个提示的规则之地。 一旦Quickstart添加了包,第二个提示会写入文件。
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.
XML路径重要,因为样式和读取类型在IronQR.Slim包中发布,而IronQR依赖于它,因此成员列表位于缓存中的文件夹。 除了成员列表之外的指南,IronQR在llms.txt为代理发布了一个索引。
在首次渲染之前处理许可证。 没有密钥,QrWriter.Write和QrReader.Read都会抛出LicensingException,消息内容为“需要生产许可证”,并且没有水印试用输出可供选择。 该异常类型不是公共的,所以程序在通过IRONQR_LICENSE_KEY设置密钥后检查License.IsLicensed,而不是通过名称捕捉异常。 IronQR许可证密钥页面介绍了获取密钥和IronQR读取它的位置。
CLAUDE.md应该包含哪些IronQR设置?
每一行都通过搭建探测装置或使用有证密钥运行探测装置,以对IronQR 2026.10.1进行验证 将块粘贴到二维码部分下面。
## 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.
黑色模块在黑色背景上保存时没有出现异常,且扫描模式都无法解码文件。
如何控制二维码的大小、边距和颜色?
一个QrStyleOptions对象容纳所有视觉选择。Save应用它并返回一个位图,你可以用SaveAs写入磁盘。 错误校正级别是一个独立设置于QrOptions之外,因为它改变编码符号本身。
Dimensions设置代码的像素大小,Margins设置四边的安静区,而MarginTop和其他边则分别设置一边。 Color绘制深色模块和BackgroundColor的浅色区域和边距。 Logo接收一个QrLogo,其中包含位图、宽度、高度和角度半径。
在我们的探测中,400像素代码与50像素上下边距和20像素侧边距以440x500保存。重设指南、边距指南和颜色指南分别展示每个设置。
Save时,不带参数会返回250 x 250的图像。 该尺寸是内部默认值。在每个错误校正级别下标志能有多大?
比校正百分比建议的小。这些数字计算Reed-Solomon解码可以重建的代码字,而中央标志只是损坏的来源之一。 我们在600像素处渲染了春季折扣的URL,用简单的方形标志,让IronQR自动调整大小,然后一次提高1%的手动大小,直到IronQR拒绝保存它。
| 级别 | 记录的恢复 | 自动标志(宽度,面积) | 最大手动标志(宽度,面积) |
|---|---|---|---|
| low | 7% | 20%,4.0% | 23%,5.3% |
| 语言 | 15% | 30%,9.0% | 31%,9.6% |
| 高的 | 25% | 32.5%,10.6% | 39%,15.2% |
| 最高 | 30% | 32%,10.2% | 44%,19.4% |
在2026.10.1程序集,自动调整大小尝试代码宽度的部分短列表,从二分之一到五分之一,并保留其读取器解码的第一个。 该列表解释了高和最高为何接近宽度的三分之一。 手动大小更高,约为文档化恢复面积的60%至75%,但IronQR在全分辨率下用自己的读取器进行检查。 第二个扫描模式依然可能在该检查通过的地方失败。
这些数据取决于有效载荷。 较长的URL会产生密度更高的符号,其限制不同,因此将该表视作权衡的形状,并让矩阵测量您自己的活动。
如何在一个提示中测试每一个样式化的IronQR变体?
在一次提示中要求整个网格,并让计划模式首先设定设计。按Shift+Tab直到状态栏显示计划模式,然后发送提示。
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.
每个条款关闭了一种结果可以看起来比实际情况更好的方法。
- 每一个组合都有命名:三个活动,四个级别,三个标志模式和两个尺寸共72个变种,因此缺失的行在
out/scan-matrix.csv中可见。 - 保存失败是行:一个被拒绝的保存是一个结果,且这些行显示标志尺寸限制所在地。
- 每次读取有一个新的读取器:一次失败的读取不能影响下一次。
- 第二个代理检查API:通用子代理加载
CLAUDE.md,而内置的Explore和Plan子代理跳过,因此检查可以查看项目的规则。
在信任生成的IronQR代码之前应验证什么?
只有当其检测模型找不到任何东西时,QrScanMode.Auto才会返回基本扫描,而枚举自有文档描述它首先是检测模型,然后是“如果找不到则进行基本的暴力读取”。 当模型找到代码但不能解码时,Auto返回空结果,而基本扫描从不运行。
基本扫描解码了每一个早前失败的Quickstart变体,该异常来自于IronQR 2026.10.1。在我们的完整矩阵的校准运行中,Auto未检测到的每个文件都有一个标志,且八个中有六个处于高或最高,这是在标志上花费最多冗余的两个级别。 在经过测试的运行中,代理选择的平整10像素边距,八个Auto失误中的两个没有标志。
将这些检查添加到同一个回顾中。
- 构建:一个杜撰的成员在
dotnet build中失败,而用IronQR拼写的使用指令亦然,使用包的大小写,而命名空间为IronQr。 - 尺寸:将每个保存的宽度与请求尺寸加上双侧边距进行比较。 不匹配显示的是一个从未到达保存调用的样式。
- 有效载荷:解码磁盘上的文件。
Verify将文本与IronQR自己的内存渲染进行比较,因此一个文件路径返回false,而用错误样式写入的文件未被注意。
校验和容错指南涵盖读取损坏的代码和验证返回的内容。 对于从头到尾运行并有自己通过标准的完整IronQR任务,请参阅AI编码助手指南。
在实际运行中这些提示生成了什么?
我们按顺序将上述三个提示发送给Claude Code,全部在一个会话中。 品牌文件持有着三个活动,一个600像素的海报尺寸和一个120像素的贴纸尺寸,并附带一个方形标志和一个宽的文字标志。 然后,一个干净副本的单独Release构建重新运行矩阵并写入相同的CSV,且每个保存的PNG的独立解码与每行一致。
- 在第一次运行时,矩阵在两种模式下都没有匹配72个变种中的0个。 在Claude Code删除
QrImageInput的using块后,72个中的55个匹配。 - IronQR在保存时拒绝了9个变种,全部带有手动标志。 在它保存的63个文件中,基本扫描解码了所有63个,而Auto解码了55个。
- 对于Quickstart,Claude Code选择了一个300像素的代码,带有10像素边距和50 x 50的标志。 它的320 x 320 PNG在第一次读取时与URL匹配。
- 子代理没有发现
IronQr.xml中缺少IronQR成员。 - 每个提示都留下了一个无需手动编辑的干净Release构建,并且矩阵总和等于校准运行。
- 因为会话是非交互式进行的,所以通过键入回复在第三个提示的地方批准了计划替代计划对话框。
本指南及其兄弟的版本、模型、定时和测试机被记录在共享的运行记录中。
故障排除
- 如果构建成功且第一次写入抛出许可证异常,请在IronQR中应用许可证密钥
- 如果保存手动尺寸的标志抛出IronQrException,请为二维码添加标志
- 如果变种需要更多冗余以应对其标志,请设置二维码错误校正级别
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。