IronQR를 Claude Code와 함께 사용하는 방법

Curtis Chau
Curtis Chau
업데이트됨: 2026년 10월 9일

마케팅 팀은 각 캠페인 QR 코드에 브랜드의 네이비 색상을 사용하고, 로고를 중앙에 배치하며, 포스터와 스티커 크기로 제공되도록 요구합니다. 그러나 각 추가 스타일링 선택은 스캔의 신뢰성을 감소시킬 수 있습니다. 예를 들어, 로고는 모듈을 가릴 수 있고, 밝은 전경은 대비를 낮출 수 있으며, 작은 인쇄 크기는 픽셀 밀도를 감소시킵니다. QR 코드는 화면에서 정상적으로 보일 수 있지만 실제 환경에서 실패할 수 있습니다. Claude Code는 Anthropic의 코딩 에이전트로, 터미널, VS Code, JetBrains, 데스크톱 애플리케이션 및 웹에서 작동합니다. 어떤 환경에서든 프로젝트를 읽고 파일을 편집하며 명령어를 실행하여 스타일 코드 렌더링, 저장 파일 디코딩, 페이로드가 보존될 때까지 스타일링 조정이 가능합니다.

IronQR는 같은 .NET 프로세스 내에서 QR 코드를 생성하고 읽기 때문에, 에이전트는 각 변경 후 스캔할 수 있습니다. 라이브러리는 읽을 수 없는 일부 디자인을 자동으로 거부합니다. 너무 많이 가리는 크기의 로고나 흰색 배경과 너무 가까운 전경 색상은 저장할 때 IronQrException을 발생시킵니다. 다른 스타일 선택은 성공적으로 저장되지만 이후 디코딩에 실패할 수 있습니다. 가장 신뢰할 수 있는 접근 방식은 스타일링된 변형의 매트릭스를 테스트하고 각 저장된 PNG를 디코딩하는 것입니다. 이 가이드는 이 과정을 위해 Claude Code를 구성하는 방법을 설명하며, 각각의 IronQR 동작은 세 가지 테스트된 프롬프트에 따라 달라집니다.

하나의 모델 설정이 세 개의 프롬프트 모두를 지원합니다. opusplan 별칭은 계획 모드에서 Opus를 사용하고 그렇지 않으면 Sonnet을 사용하며, 이는 매트릭스 빌드만 기획이 필요한 세션에 적합합니다.

빠른 시작
NuGetNuGet으로 설치

PM > Install-Package IronQR

위 명령을 NuGet 패키지 관리자 콘솔에 입력하거나 NuGet 패키지 관리자에서 패키지를 검색하여 IronQR를 설치하십시오.

터미널에서 프로젝트 폴더를 열고 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.
Text

이 코드의 가장 직접적인 버전이 실패할 수 있습니다. 우리의 프로브에서는 자동으로 크기가 조정된 로고와 기본 오류 수정 수준의 봄 세일 코드가 오류 없이 저장된 후 공백으로 읽히거나 리더의 기본 스캔 모드에서 ObjectDisposedException을 발생시켰습니다. 500픽셀 코드에 수동으로 종이 100픽셀 로고를 넣은 경우 올바르게 읽혔습니다.

출력된 너비를 먼저 확인하세요. 우리의 프로브에서는 크기가 설정되지 않은 스타일 옵션이 이 URL을 위해 49픽셀 이미지를 생성했습니다.



.NET QR 코드 프로젝트에서 Claude Code는 무엇을 합니까?

에이전트는 렌더러를 작성하고, 브랜드 파일을 읽고, 각 변형당 하나의 PNG를 저장하고, 각 파일을 디코드하며, 디자인이 유지되는지를 보고합니다. 캠페인에 필요한 변형을 말하고 돌아오는 표를 검토합니다.

브랜드화된 코드는 로고 크기, 수정 수준 및 픽셀 크기가 상호 작용하기 때문에 이를 자동화할 가치가 있습니다. 테스트된 실행에서는 IronQR가 600픽셀 코드에 폭의 30%로 수동 로고를 저장하고, 120픽셀에서 같은 비율을 거부했으며, 다른 캠페인에서는 반대의 결과를 보였습니다.

첫 프롬프트에서 IronQR를 유일한 QR 라이브러리로 명명합니다. 패키지 이름을 추측하는 에이전트가 그 추측을 포착한 유사품이 게시된 것을 설치할 수 있는 공격을 슬롭스쿠왓팅이라고 합니다.

Claude Code를 어떻게 설정하나요?

Anthropic의 quickstart로 Claude Code를 설치하고 로그인하세요. 터미널에서 시작하여 응답하면 준비되었습니다.

Claude Code가 작업할 수 있는 프로젝트를 어떻게 설정하나요?

첫 프롬프트 전에 저장소를 준비합니다. .NET 9 콘솔 프로젝트가 빌드되고, 각 캠페인의 URL과 색상을 가진 Brand/campaigns.json 파일, 그리고 에이전트가 작업할 수 있는 로고 파일이 필요합니다. 해당 폴더에서 Claude Code를 시작하여 세션이 그에 집중되도록 합니다.

"<code>CLAUDE.md"에서 각 세션이 시작될 때 Claude Code가 읽기 때문에 하나의 프롬프트로 생존해야 할 규칙의 장소로 만듭니다. 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.
Text

XML 경로는 스타일링 및 읽기 타입이 IronQR.Slim 패키지에 포함되어 있기에 중요하며, IronQR가 이를 종속성이기 때문에 멤버 리스트가 캐시의 해당 폴더에 위치합니다. 멤버 리스트 이외의 가이드를 위해 IronQR는 에이전트를 위한 검색 색인을 llms.txt에 게시합니다.

첫 렌더 전에 라이선스를 처리하세요. 키가 없을 경우, QrWriter.Write 및 QrReader.Read 각각이 "Production License Required"라는 메시지를 가진 라이센스 예외를 던지며, 이는 워터마크 체험판 출력을 대체할 수 없습니다. 해당 예외 타입은 공개되지 않았으므로, 프로그램이 License.IsLicensed을 확인하여야 하며, IRONQR_LICENSE_KEY에서 키를 설정한 후 이름으로 예외를 잡으려 하지 마세요. IronQR License Keys 페이지에는 키를 얻는 방법과 IronQR가 이를 읽는 위치가 설명되어 있습니다.

어떤 IronQR 설정이 CLAUDE.md에 포함되어야 하나요?

각 행은 IronQR 2026.10.1에 대해 프로브를 빌드하거나 라이센스된 키로 실행하는 것으로 확인되었습니다. 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.
Markdown

검정 배경에 검정 모듈이 예외 없이 저장되었고, 어느 스캔 모드도 파일을 디코드할 수 없었습니다.

QR 코드의 크기, 여백 및 색상을 어떻게 제어하십니까?

하나의 QrStyleOptions 객체가 모든 시각적 선택을 포함합니다. Save이 이를 적용하고 디스크에 SaveAs으로 쓸 비트맵을 반환합니다. 오류 수정 수준은 자체적으로 인코딩된 기호를 변경하기 때문에 QrOptions에 있는 유일한 설정입니다.

코드 크기는 픽셀 단위로 Dimensions가 설정하고, Margins은 네 면의 조용한 구역을 설정하며, MarginTop 및 다른 면들은 각 면을 설정합니다. 어두운 모듈은 Color로 칠하고, 밝은 영역과 여백은 BackgroundColor로 칠합니다. 비트맵, 너비, 높이 및 코너 반경을 가진 QrLogo을 Logo가 수용합니다.

우리의 프로브에서는 50픽셀의 상하 여백과 20픽셀의 사이드 여백이 있는 400픽셀 코드가 440 x 500으로 저장되었습니다. 각각의 설정을 자체적으로 보여주는 크기 조정 가이드, 여백 가이드, 및 색상 가이드를 참고하세요.

유의 사항: 인수가 없는 상태에서 한 번도 스타일링되지 않은 코드에 Save을(를) 호출하면 250 x 250 이미지가 반환됩니다. 그 크기는 내부 기본값입니다.

각 오류 수정 수준에서 로고는 얼마나 클 수 있습니까?

수정 비율이 권장하는 것보다 작습니다. 해당 수치는 Reed-Solomon 디코딩이 재구축할 수 있는 코드워드를 계산하며, 중앙의 로고는 손상되는 유일한 원인이 아닙니다. 봄 세일 URL을 600픽셀로 랜더링하고, 단순한 사각형 로고가 IronQR에 의해 자동으로 크기 조정되도록 한 후 수동 크기를 IronQR이 저장을 거부할 때까지 1%씩 올렸습니다.

수준복원 문서화됨자동 로고 (너비, 면적)가장 큰 수동 로고 (너비, 면적)
낮음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 어셈블리에서는 자동 크기 조정이 코드 폭의 몇 분의 몇의 리스트를 시도하며, 절반에서 20분의 1까지이며, 리더가 디코드하는 첫 번째 것을 유지합니다. 해당 리스트는 왜 높은 수준과 가장 높은 수준이 폭의 약 3분의 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.
Text

각 조항은 결과가 실제보다 더 좋아 보일 수 있는 방법을 닫습니다.

  1. 모든 조합이 명명됩니다: 세 개의 캠페인, 네 개의 수준, 세 개의 로고 모드, 두 개의 크기가 72개의 변형을 생성하므로, out/scan-matrix.csv에 행이 누락되면 바로 알 수 있습니다.
  2. 저장 실패는 행입니다: 저장 거부는 결과이며, 해당 행은 로고 크기 제한이 어디 있는지 보여줍니다.
  3. 각 읽기에 새로운 리더: 한 번의 읽기 실패가 다음에 영향을 줄 수 없습니다.
  4. 두 번째 에이전트가 API를 확인합니다: 범용 하위 에이전트가 CLAUDE.md을 로드하며, 내장된 탐색 및 계획 하위 에이전트는 이를 건너뛰므로 검사는 프로젝트의 규칙을 확인합니다.
팁: 모든 변형을 나열하고 각각에 대해 try 블록을 표시한 후에만 계획을 승인하십시오.

생성된 IronQR 코드를 믿기 전에 확인해야 할 것은 무엇입니까?

검출 모델이 아무것도 찾지 못할 때만 QrScanMode.Auto은 기본 스캔으로 되돌아가며, 열거형의 자체 문서는 이를 검출 모델 먼저, 그런 다음 "아무 것도 발견되지 않으면 기본의 무차별 읽기"로 설명합니다. 모델이 코드를 찾았지만 디코딩할 수 없을 때는 Auto가 빈 결과를 반환하고 기본 스캔은 실행되지 않습니다.

기본 스캔은 위에서 실패한 모든 Quickstart 변형을 디코드했으며, 예외는 IronQR 2026.10.1 내부에서 발생합니다. 전체 매트릭스의 보정 실행에서, Auto가 놓친 모든 파일에는 로고가 있었고, 여덟 중 여섯은 가장 높거나 높은 수준이었으며, 이는 로고에 쓸 수 있는 가장 많은 여유를 가진 두 수준입니다. 에이전트가 고른 평면 10픽셀 여백으로 테스트된 실행에서는 여덟 Auto 누락 중 두 개는 로고가 전혀 없었습니다.

같은 리뷰에 이러한 검사를 추가하세요.

  • 빌드: 발명된 멤버는 dotnet build에서 실패하며, 패키지의 케이싱을 사용하는 반면 네임스페이스는 IronQr이기 때문에 IronQR로 철자가 적힌 사용 지시문도 마찬가지입니다.
  • 크기: 저장된 각 너비를 요청된 크기 및 양 사이드 여백과 비교합니다. 불일치는 저장 호출에 도달하지 않은 스타일을 보여줍니다.
  • 페이로드: 디스크에 있는 파일을 디코드합니다. 패스 경로가 false를 반환하고 잘못된 스타일로 작성된 파일은 눈치 채지 못하기 때문에, Verify은 IronQR의 자체 메모리 내 렌더링과 텍스트를 비교합니다.

체크섬 및 내결함성 가이드에는 손상된 코드를 읽고 반환되는 것을 검증하는 것이 포함되어 있습니다. 자체 자격 기준으로 시작 및 종료하는 완전한 IronQR 작업 실행을 위해, AI 코딩 보조 도우미 가이드를 참조하세요.

실제 실행에서 프롬프트가 무엇을 생성했습니까?

우리는 위의 세 가지 프롬프트를 순서대로 Claude Code에 보냈습니다, 한 세션에서. 브랜드 파일에는 세 가지 캠페인, 600픽셀 포스터 사이즈 및 120픽셀 스티커 사이즈, 그리고 사각 로고와 넓은 워드마크가 포함되어 있었습니다. 독립적인 디코드가 저장된 각 PNG를 모두 동일한 CSV와 일치하게 하고 독립적으로 다시 읽었습니다.

  • 첫 실행에서 매트릭스는 두 모드에서 72개 변형 중 0개와 일치했습니다. Claude Code가 QrImageInput에 있는 사용 블록을 제거한 후 72개 중 55개가 일치했습니다.
  • IronQR는 수동 로고가 있는 모든 9개 변형을 저장 시 거부했습니다. 저장한 63개의 파일 중 기본 스캔은 모두 63개를 디코딩했고 Auto는 55개를 디코딩했습니다.
  • Quickstart를 위해 Claude Code는 10픽셀 여백과 50 x 50 로고가 있는 300픽셀 코드를 선택했습니다. 초기 읽기에서 320 x 320 PNG가 URL과 일치했습니다.
  • 하위 에이전트는 IronQr.xml에서 누락된 IronQR 멤버를 찾지 못했습니다.
  • 모든 프롬프트는 수동 수정 없는 깨끗한 릴리스 빌드를 남겼고, 매트릭스 합계는 보정 실행과 동일합니다.
  • 입력된 응답은 플랜 대화 상자 대신 세 번째 프롬프트의 계획을 승인했습니다, 세션은 비대화식으로 실행되었습니다.

이 가이드 및 그 형제들의 버전, 모델, 타이밍 및 테스트 머신은 공유된 실행 기록에 기재되어 있습니다.


문제 해결


질문?

질문이 있으시면 support@ironsoftware.com으로 문의하세요.

커티스 차우는 칼턴 대학교에서 컴퓨터 과학 학사 학위를 취득했으며, Node.js, TypeScript, JavaScript, React를 전문으로 하는 프론트엔드 개발자입니다. 직관적이고 미적으로 뛰어난 사용자 인터페이스를 만드는 데 열정을 가진 그는 최신 프레임워크를 활용하고, 잘 구성되고 시각적으로 매력적인 매뉴얼을 제작하는 것을 즐깁니다.

더 읽기

시작할 준비 되셨나요?

NuGet 다운로드 수 82,442버전:2026.11방금 출시