IronWord를 Cursor와 함께 사용하는 방법

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

이 가이드의 샘플 저장소는 본문 요소를 반복하며 InnerText를 읽는 OpenXML SDK 코드를 사용하여 공급업체 양식을 읽습니다. 정규 표현식을 사용해 한 블록의 추출된 텍스트에서 모든 라벨된 값을 파싱하여 IronWord로 그 리더를 이동시키면 실패합니다. 보정에서는 12개의 양식 중 3개만 올바르게 읽어, 다섯 개의 등록 번호를 다음 라벨에 결합하였고, 네 개의 테이블 양식에서 등록 번호를 반환하지 않았습니다.

Cursor는 VS Code 코드베이스를 기반으로 구축되어 있으며 편집기 옆에 에이전트를 제공합니다. 에이전트가 읽는 문서 링크 및 .cursor/rules에 커밋된 프로젝트 규칙이라는 두 가지 기능은 IronWord 코드를 생성하는지, 아니면 OpenXML 리더 패턴을 따르는지 결정합니다. 이 두 기능은 공급업체에서 반환된 DOCX 양식을 읽는 공급업체 온보딩 서비스에 아래에 나타납니다. 서비스는 공급업체 이름, 등록 번호, 가격표 테이블 및 내장된 로고 및 서명 이미지를 추출하며, 리더는 OpenXML SDK에서 IronWord로 옮깁니다.

IronWord의 읽기 방법에 대한 자세한 내용은 텍스트 추출 가이드와 이미지 추출 가이드를 참조하십시오.

빠른 시작
NuGetNuGet으로 설치

PM > Install-Package IronWord

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

공급업체 인테이크 저장소가 열려있는 상태에서, 새로운 에이전트 채팅에 이 프롬프트를 붙여넣으세요.

@src/SupplierIntake/ @TestData/forms/

Don't write anything until you've fetched https://ironsoftware.com/word/csharp/llms.txt.
Read the extract text and extract images pages it links as well.

Then give Program.cs a dump command that opens one form with IronWord:
`dotnet run --project src/SupplierIntake -- dump <file.docx>`

Have the dump print what IronWord returns for that form:
- The ExtractText result, in quotes.
- Every entry of Paragraphs, with its index.
- Every table cell, with its table, row and column numbers.
- Each extracted image's Width and Height, and the pixel size of the AnyBitmap behind it.

The program should read IRONWORD_LICENSE_KEY itself when it's set.
At startup, assign the key to License.LicenseKey.
Never print the key, and keep environment variables out of the output.
Leave Forms/FormReader.cs and its DocumentFormat.OpenXml reference as they are.

Run the dump on TestData/forms/form-03.docx and show me the output.
Text

채팅에 라이선스 키를 입력하지 마십시오. 에이전트는 파일을 편집하고 셸 명령을 실행하기 때문에, 붙여넣은 키는 에이전트가 작성하는 모든 파일, 커밋 메시지 및 빌드 로그에 노출됩니다. 우리의 테스트에서는, IronWord가 키 없이 모든 양식을 열어 읽었고, 문서를 저장할 때에만 LicensingException을 던졌습니다. 라이선스 키 가이드는 키를 코드, Web.config, 또는 appsettings.json에 설정하는 방법을 보여줍니다.



IronWord 작업에 어떤 Cursor 모델을 사용해야 합니까?

Composer는 Cursor의 독자적 에이전트 모델입니다. 모델 선택자는 또한 Cursor와 공동 개발한 SpaceXAI의 Grok 모델 및 OpenAI, Anthropic, Google 기타 실험실의 모델을 제공합니다. 아래 테스트 실행은 Grok 4.7을 사용했습니다.

IronWord 문서를 Cursor에 어떻게 제공합니까?

요청에 IronWord의 문서 링크를 포함시키거나 팀 전체에서 공유하는 규칙에 보관하십시오. IronWord의 llms.txt에는 각 가이드와 API 레퍼런스가 나열되어 있으며, llms-full.txt는 46개의 문서 페이지를 하나의 파일로 압축합니다. 2026년 10월 기준으로, Cursor의 @ 메뉴는 파일, 폴더, 터미널, 채팅, Git 차이 및 브라우저를 첨부하며, IronWord의 문서는 링크로 에이전트로 전달됩니다.

Quickstart 덤프는 텍스트 추출 가이드에서 언급되지 않은 두 가지 동작을 보여줍니다. form-03의 경우, ExtractText은 본문 단락 텍스트를 하나의 문자열로 연결하여 반환하고, 양식의 두 테이블에 있는 모든 텍스트를 생략했습니다.

@src/SupplierIntake/Forms/RegistrationCheck.cs

Answer five questions about IronWord, without editing any files:
1. Does WordDocument.ExtractText include text from table cells?
2. What does it put between paragraphs?
3. Does the Paragraphs collection list the paragraphs inside table cells?
4. What does ExtractImages return, and what element type does the list hold?
5. What unit do the Width and Height of each result use?

Use the documentation at https://ironsoftware.com/word/csharp/llms.txt as your source.
The project rule doesn't count as one.
Check your answers against the form-03 dump from the last turn, where it shows them.
Cite the page each answer comes from.
Where no page states it, say the answer is measured, not documented.
Text

IronWord 규칙을 부호화하는 프로젝트 규칙을 어떻게 작성합니까?

프로젝트 규칙은 .cursor/rules에 저장된 .mdc 파일이며 저장소와 함께 버전이 관리되므로, 모든 클론에 포함됩니다. Cursor는 해당 폴더의 일반 .md 파일을 무시합니다. 이유는 프론트매터가 없으므로 언제 로드할지 결정할 수 없기 때문입니다.

아래 규칙은 globs을 정의하고 alwaysApply을 false로 설정합니다. Cursor는 요청에 폼 리더나 테스트 파일이 포함될 때마다 이를 로드하고, 그렇지 않으면 생략합니다. 이를 .cursor/rules/ironword-forms.mdc로 저장하십시오.

---
description: IronWord conventions for reading supplier forms
globs: src/SupplierIntake/Forms/**/*.cs, tests/**/*.cs
alwaysApply: false
---

Read and write DOCX files with IronWord only, under these package rules:
- The NuGet package is IronWord.
- Its types come from two namespaces, IronWord and IronWord.Models.
- AnyBitmap comes from IronSoftware.Drawing.
- Don't add DocX, NPOI or any other DOCX package.
- Add no new DocumentFormat.OpenXml code.
- The documentation index is https://ironsoftware.com/word/csharp/llms.txt

Keep license keys out of the code, and handle the key this way:
- Read it at run time from an environment variable named IRONWORD_LICENSE_KEY.
- Never print it.

WordDocument.ExtractText leaves out table cells and runs paragraphs together with no separator.
Use the paragraph and table collections instead:
- Read labeled values one paragraph at a time from doc.Paragraphs.
- Read tables through doc.Tables, Rows and Cells.
- doc.Paragraphs also returns the paragraphs inside table cells.

Table.Rows returns ITableRow, and a row's Cells returns ITableCell.
Two casts are needed:
- Cast a row to TableRow before you pass it to a method that takes a TableRow.
- Cast a cell to TableCell before you call ExtractText on it.

Don't invent IronWord members.
When you're unsure of one, say so and name the page you checked.
Markdown
유의 사항: Cursor는 또한 AGENTS.md를 루트 또는 하위 폴더 내에서 읽습니다. 해당 파일에는 프론트매터와 파일 패턴이 없으므로 glob에 의존하는 IronWord 규칙은 .cursor/rules에 속합니다.

Cursor의 규칙 페이지는 규칙이 Tab에 영향을 미치지 않으며, 사용자 규칙이 인라인 편집에 적용되지 않음을 명시합니다. 따라서, Tab과 인라인 편집 제안은 규칙과 수동으로 확인되어야 합니다.

OpenXML SDK 호출을 IronWord로 어떻게 매핑합니까?

IronWord를 사용하도록 모델을 지시하는 것은 각 OpenXML SDK 호출을 대체하는 IronWord 호출을 알려주지 않습니다. 등가물의 표가 이 매핑을 제공합니다.

OpenXML SDKIronWord
WordprocessingDocument.Open경로, 바이트 또는 스트림에서의 WordDocument 생성자
본문 단락 및 그 내부 텍스트Paragraphs, 각 ExtractText와 함께
본문 테이블, 행 및 셀Tables, Rows 및 Cells
Blip 요소 및 이미지 파트 스트림AnyBitmap을 통해 저장된 ExtractImages

두 행은 그들이 교체하는 SDK 코드와 다르게 동작합니다. 단락 목록은 테이블 셀 안의 단락뿐만 아니라 본문 단락도 보유하므로, form-03은 OpenXML SDK 리더가 5개의 본문 단락을 반복하는 곳에서 15개의 항목을 반환합니다. 셀은 ITableCell로 반환되며, 텍스트 방법이 없으므로, 캐스트 없이 호출하면 CS1061로 빌드에 실패합니다.

IronWord는 DocumentFormat.OpenXml 패키지를 참조하지 않으며, IronWord 2026.10.4와 DocumentFormat.OpenXml 3.5.1을 둘 다 참조하는 프로젝트는 빌드 및 실행이 됩니다. 따라서, 마이그레이션은 한 번에 한 리더로 진행할 수 있습니다. OpenXML 충돌 페이지는 2025.7.13 이전의 IronWord 빌드를 다룹니다.

규칙의 끝에 이 줄을 추가하면 규칙을 로드하는 모든 요청에 표가 생깁니다.

Translate OpenXML SDK code instead of porting it, with these equivalents:
- WordprocessingDocument.Open becomes new WordDocument(path).
- Body.Elements<Table>() becomes doc.Tables.
- Counting Blip elements becomes doc.ExtractImages().Count.

Save extracted images with ((AnyBitmap)image.Image).SaveAs(path).
Markdown

IronWord로의 마이그레이션을 어떻게 계획하고 실행합니까?

채팅 입력에서 Shift+Tab을 눌러 Plan Mode가 선택될 때까지 진행한 후, 아래 요청을 보내세요. Cursor는 계획을 편집 가능한 파일로 작성합니다.

@src/SupplierIntake/Forms/ @TestData/forms/expected.csv

Plan the move of FormReader to IronWord so the project can drop DocumentFormat.OpenXml.
Write no code until I approve.
FormReader still reads supplier forms with the OpenXML SDK.
RegistrationCheck already uses IronWord, and the team wants a single DOCX library.

The plan has to cover these points:
- Every OpenXML SDK call, with its IronWord replacement and the file where the call lives.
- How the reader will find the price table.
- How it will find a registration number inside a table.

Keep SupplierForm and the public Read and SaveImages signatures unchanged.
Where something is unclear, state your assumption instead of asking.
Show me the plan when it's ready.
Text

계획의 오류를 수정하세요. 그런 다음 빌드를 클릭하거나 Agent로 돌아가서 이 요청을 보냅니다.

@ironword-forms

Carry out the approved plan.
Check the forms output against TestData/forms/expected.csv before and after the move.
A printed row counts as a match when its supplier, registration, items and images columns agree.

Work through it in this order:
1. Run `dotnet run --project src/SupplierIntake -- forms TestData/forms` and count the matches.
2. Migrate FormReader to IronWord.
3. Remove the DocumentFormat.OpenXml package reference.
4. Run dotnet build, then run the forms command again.

Tell me the match count for the OpenXML version and for the IronWord version.
Then show me the diff.
Text

@ironword-forms 언급은 규칙의 이름으로 규칙을 적용하며, Cursor가 이미 glob을 통해 이를 첨부했는지 여부에 관계없이 적용합니다.

Cursor의 어떤 기능이 각 변경에 적합합니까?

Tab은 편집기에 이미 보이는 편집을 완료하고, 인라인 편집(Ctrl+K)은 하나의 문장 지침에서 선택을 다시 작성합니다. 여러 파일에 걸친 변경 사항이나 빌드가 필요한 변경 사항은 Agent로 이동합니다. 잘못된 변경을 되돌리는 것이 계획을 작성하는 데 드는 시간보다 더 많은 노력이 소요될 때는 Plan Mode를 사용하십시오. Cloud Agent는 무인 작업에 적합합니다.

새로운 공급자는 두 가격 계층에 걸쳐 하나의 항목 셀을 병합한 가격 표가 있는 form-13을 반환합니다. FormReader에서 가격 행을 반복하는 루프를 강조 표시하고, Ctrl+Shift+L(macOS에서는 Cmd+Shift+L)을 눌러 강조 표시된 코드를 채팅 입력에 추가한 다음, 에이전트에서 이 요청을 보냅니다.

Make FormReader.Read handle merged cells in the price rows:
- An Item cell that Word merged with the cell above comes back empty.
- For that row, reuse the item name from the previous row.
- Before you read a cell by its column position, check that the row has that many cells.

Then rerun the forms command over TestData/forms.
Tell me how many rows agree with expected.csv, which now lists 13 forms.
Text

행 길이 검사로 다른 방향으로의 병합 문제를 해결합니다. 별도의 프로브 파일에서, 열 간에 병합된 셀이 하나의 셀로 반환되었고, 그 결과 해당 행은 다른 행보다 짧았습니다.

추출된 텍스트에서 누락된 값을 어떻게 디버그합니까?

저장소의 사전 검사는 ExtractText의 결과에 정규 표현식을 사용하여 등록 번호를 읽습니다.

@src/SupplierIntake/Forms/RegistrationCheck.cs @TestData/forms/

Find out why the pre-check flags 9 of the 13 forms as missing a registration number.
FormReader finds one in all 13, and every number is visible in Word.

Before you edit anything, do these three things:
1. Run the check command on TestData/forms and on TestData/edge, and note what it flags.
2. Run the dump command on one flagged form.
3. Explain what the check reads that FormReader doesn't.

Then fix RegistrationCheck and keep it on IronWord.
Rerun the check on both folders.
Tell me how many forms it flags in TestData/forms and in TestData/edge, before and after the fix.
Text

9 실패는 두 가지 원인이 있습니다. 5개의 양식에서, 연락처 이메일 단락이 번호 뒤에 오므로, 표현식이 GB-0012345Contact를 캡처하고 형식 검사가 이를 거부합니다. 다른 네 개는 회사 세부 사항 테이블에 번호를 저장하며, 라벨 셀은 콜론 없이 등록 번호를 읽고 값은 다음 셀에 있습니다. 단락을 개별적으로 읽고 라벨 옆 셀에서 값을 가져와 두 문제를 해결합니다.

DOCX의 어떤 부분을 IronWord가 생략합니까?

IronWord 2026.10.4에 대한 프로브에서는 라이브러리가 폼 리더에 반환하지 않는 콘텐츠를 식별했습니다.

  • 헤더: 읽기는 헤더 텍스트를 반환하지 않으며, ExtractImages는 헤더 이미지를 생략합니다. 페이지 설정은 헤더의 높이를 노출하지만 그 내용은 노출하지 않습니다.
  • 콘텐츠 컨트롤 및 텍스트 박스: 그들의 텍스트는 단락과 추출된 텍스트에 없 습니다.
  • 추적된 변경 사항: 읽기는 추적이 활성화되었을 때 삽입된 텍스트를 생략합니다.
  • 레거시 파일: Word 97-2003 .doc 파일은 로드 시 "손상된 데이터가 포함된 파일" 오류를 발생시킵니다.
  • 간격 속성이 없는 인라인 그림: 인라인 사진 중에 distT, distB, distL 및 distR을 생략한 DOCX는 InvalidOperationException으로 로드에 실패합니다. python-docx는 이러한 속성을 생략합니다.

부유 그림과 테이블 셀 안의 그림은 문서 순서대로 추출됩니다. 공급업체가 콘텐츠 컨트롤로 만든 양식을 완성하거나 등록 번호를 헤더에 배치하는 경우, 리더에 의존하기 전에 해당 양식을 테스트하십시오.

문서 읽기에 대한 회귀 테스트를 어떻게 작성합니까?

추출된 값들을 알려진 목록과 비교하는 테스트는 리더의 내부 구현과 상관없이 인테이크 서비스의 출력을 확인합니다. Cloud Agent는 독립된 VM에서 이를 작성할 수 있습니다. Cloud Agents 대시보드의 비밀 아래에 먼저 IRONWORD_LICENSE_KEY을 저장하십시오.

@tests/SupplierIntake.Tests/ @TestData/

Write xUnit tests for FormReader and RegistrationCheck.

Each of these needs a test:
- Every row of TestData/forms/expected.csv matches.
- In form-13, both price tiers keep the item name.
- SaveImages writes one PNG per picture, with the pixel sizes listed in the image_sizes column.
- RegistrationCheck passes every form and flags TestData/edge/no-registration.docx.
- Reading TestData/edge/legacy.doc throws a FormatException or a type derived from it.

Copy TestData into the test output and run dotnet test.
Tell me the passed and failed counts.
Text

레거시 파일 어설션은 IronWord의 예외 유형을 참조할 수 없습니다. 왜냐하면 그것이 내부적이기 때문입니다. 이것은 FormatException에서 파생되므로, xUnit의 Assert.ThrowsAny<FormatException>와 같은 파생형을 수용하는 어설션은 컴파일되며 다른 오류가 발생할 때 여전히 실패합니다.

AI 코딩 어시스턴트 가이드는 작성된 통과 기준에 따라 끝까지 실행된 한 IronWord 작업을 포함합니다.

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

일곱 개의 프롬프트는 하나의 채팅에서 순서대로 Cursor에 보내졌습니다. 샘플 저장소는 OpenXML SDK 리더, IronWord 사전 검사, 빈 xUnit 프로젝트, 알려진 값이 있는 12개의 양식 및 두 개의 엣지 파일을 보유했습니다.

  • OpenXML SDK 리더와 그것을 대체한 IronWord 리더는 각각 12개의 양식을 모두 일치시켰습니다.
  • IronWord는 앱과 그 테스트에서 남은 유일한 DOCX 패키지였습니다.
  • form-13이 추가되자, 리더는 13개 중 12개와 일치하고 두 번째 가격 계층에서 품목 이름을 생략했습니다.
  • 병합 셀 변경 후, 리더는 13개 중 13개와 일치했습니다.
  • 사전 검사는 수정 전 13개의 양식 중 9개를 플래그하고 수정 후에는 플래그하지 않았습니다. 두 번 다 등록 번호가 없는 엣지 양식은 플래그되었습니다.
  • 저장된 모든 21개의 이미지가 나열된 픽셀 크기를 가졌습니다.
  • form-03 덤프에는 두 개의 테이블에서 10개의 셀과 108 x 36 포인트 및 144 x 48 픽셀의 하나의 이미지가 나열되었습니다.
  • 문서에서 무엇을 명시하는지 물었을 때, Cursor는 아무 파일도 변경하지 않고 대답했습니다.
  • 6개의 테스트 메서드에서 42개의 사례가 라이선스 키 유무와 상관없이 통과했습니다.
  • 최종 코드의 복사본에서, 병합 셀 처리를 제거하면 2개의 사례가 실패했습니다. 이전 사전 검사를 복원하면 9개가 실패했고, 폼당 하나의 이미지를 건너뛰면 13개가 실패했습니다.
  • 레거시 파일 테스트는 어떤 예외라도 수용했으며, 파일이 삭제된 상태에서 통과했습니다. FormatException으로 축소된 경우, 실제 파일로 통과하고 파일 없이 실패했습니다.
  • Cursor의 첫 번째 IronWord 리더는 행 캐스트가 없었고 CS1503으로 빌드에 실패했습니다. Cursor는 다음 빌드 전에 캐스트를 추가했습니다.
  • 모든 릴리스 빌드는 0 개의 경고와 0 개의 오류가 있었으며, 수동 편집이 없었습니다.
  • 일부 단계는 페이지와 달리 작동했습니다. 규칙은 행 캐스트가 부족했습니다. 병합 셀 프롬프트는 행 길이 검사를 요청하지 않았고, Cursor는 아무것도 추가하지 않았습니다. 테스트 프롬프트는 단지 예외가 던져진 것만을 요구했습니다. 프롬프트와 @멘션이 포함된 것들이 텍스트로 데스크탑 앱에 붙여넣어졌습니다. 계획은 빌드 버튼이 아닌 Agent에서 승인되었습니다. Cloud Agent 프롬프트는 에이전트 모드에서 로컬로 실행되어, VM 없이 운영되었습니다.

Claude Code 가이드는 생성된 코드에서 IronWord.xml에 대해 모든 IronWord 멤버를 점검하는 읽기 전용 서브 에이전트를 추가합니다. ChatGPT Codex 가이드는 쓰기 측면을 다루며, 워드 문서의 어느 부분이 텍스트 치환으로 바뀌는지를 측정합니다.

실행 기록은 IronWord 패키지, 모델, 타이밍 및 이 결과에 대한 테스트 기계를 나열합니다.


문제 해결


질문?

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

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

더 읽기

시작할 준비 되셨나요?

NuGet 다운로드 수 62,392버전:2026.11방금 출시