IronWord와 Claude Code 사용 방법

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

매년 11월, 보험사는 갱신 서신을 피보험자에게 보냅니다. 규정 준수 팀은 서신의 문구를 위한 단일 Word 템플릿을 관리하며, 이름, 날짜, 보험료 및 보장 세부 정보는 정책 시스템에서 가져옵니다. 완전해 보이는 합병 서신이 합병이 성공적으로 이루어졌음을 증명하지는 않습니다. 이 가이드의 뒷면 탐색에서는 빈 커버리지 행이 남거나 참조 번호가 누락되거나 첫 번째 고객의 데이터가 재사용되는 합병도 예외 없이 완료되었습니다. Anthropic의 에이전트 코딩 도구인 Claude Code는 코드베이스를 읽고 파일을 편집하며 터미널, VS Code, JetBrains IDE, 데스크톱 앱 또는 브라우저에서 명령을 실행합니다.

IronWord는 DOCX 템플릿에서 사전, 데이터 행 또는 데이터 세트를 사용하여 MERGEFIELD 플레이스홀더를 채우며, 테이블 행을 위한 반복 영역을 지원합니다. Microsoft Office가 필요하지 않습니다. 합병 자체는 몇 줄의 코드만으로 완료됩니다. 호출 순서와 기본 옵션이 출력의 정확성을 결정하며, 일부 실수는 예외를 발생시키지 않고 잘못된 출력을 생성합니다. 아래의 네 가지 테스트된 프롬프트는 Claude Code가 갱신 서신 배치를 생성하도록 설정하며, 각각은 IronWord의 동작에 의존합니다.

빠른 시작
NuGetNuGet으로 설치

PM > Install-Package IronWord

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

프로젝트 폴더에서 claude을 시작하고, 어떤 프롬프트 이전에 /model opusplan을 한 번 실행하십시오. 경로 앞의 @는 요청에 해당 파일의 내용을 포함시킵니다.

Add the IronWord NuGet package, version 2026.10.4, to RenewalLetters.csproj.
Then write one renewal letter in Program.cs.

Merge the first customer row of @Data/customers.csv into @Templates/renewal-letter.docx.
Save the letter to out/letters/NM-104233.docx.
Create that folder first, and pass the path to the save call.
Don't change the template file.

Next, open the saved letter in a new WordDocument and print these in order:

1. The body text.
2. The text of every table cell, row by row, with each cell cast to TableCell to read it.
3. The names of any merge fields still in the document, or "none".

My license key is in the IRONWORD_LICENSE_KEY environment variable.
Have the program read that variable itself and apply the key before the first IronWord call.
Don't print, echo or save the key anywhere.
Don't list environment variables to look for it either.
Tell me whether it's set and nothing more.
Text

본문 텍스트 이전에 테이블 출력을 검토하십시오. 커버리지 행은 반복 영역에 있으며, 해당 영역 호출만이 이를 채웁니다.



.NET Word 문서 프로젝트에서 Claude Code는 무엇을 하나요?

Claude Code는 병합 서비스를 작성하고 두 개의 CSV 파일에서 정책별로 하나의 서신을 생성합니다. 그 후 각 저장 된 서신을 다시 열고 검토합니다. 검토가 실패할 경우 병합 코드를 수정하고 배치를 다시 실행합니다. 개발자는 올바른 서신에 포함될 내용을 결정하고 종료 시 감사 파일을 검토합니다.

첫 번째 프롬프트에서 IronWord 패키지와 버전을 명명하십시오. 공격자는 언어 모델이 환각하는 패키지 이름으로 악성 패키지를 등록하는데, 이를 슬롭스쿼팅이라고 합니다.

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

Anthropic의 퀵스타트는 설치 및 로그인 절차를 다룹니다. claude이 터미널에서 열리고 응답하면 설정이 완료됩니다.

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

먼저 저장소에 실제 입력값을 넣으십시오. 이 가이드에 사용된 픽스처는 컴파일하는 .NET 9 콘솔 응용 프로그램, 병합 필드를 가진 갱신 서신이 포함된 Templates 폴더, 고객 CSV 하나와 정책 번호로 키를 지정한 보장 행 CSV 하나가 포함된 Data 폴더로 구성됩니다.

Claude Code는 각 새 세션마다 CLAUDE.md를 로드하므로 그 규칙은 모든 이후 프롬프트에 적용됩니다. 퀵스타트가 패키지를 설치한 후, 두 번째 프롬프트가 그 파일과 병합 코드를 위한 검토자를 생성합니다.

Create CLAUDE.md in the repository root and give it a section called Mail merge.
Every later session should find these rules in it:

- IronWord is the only DOCX library this project may use.
- The NuGet package is IronWord, at the version RenewalLetters.csproj references now.
- Look up IronWord member names in docs/IronWord.xml.
- Templates/ is read-only, and each letter starts from a new load of the template file.
- The license key rules from my first message, written out in full.
- A letter isn't finished until the saved file has been reopened and checked.

Copy docs/IronWord.xml now from the ironword folder of the local NuGet cache.
If the file isn't there, stop and say so.

Then add a subagent at .claude/agents/merge-auditor.md.
Give it the Read, Grep and Glob tools and no others.
Its job is to list every IronWord type and member used under Services/.
It should name each one that docs/IronWord.xml doesn't document.
IronSoftware.* types such as ITableCell are documented in other packages.
Have it list those separately, so it doesn't call them missing.
Text

Claude Code는 .claude/agents에서 새 하위 에이전트 파일을 감시하지만, 감시자는 시작 시 존재하는 폴더만을 포함하므로 세션을 시작하기 전에 해당 폴더를 생성하십시오. 멤버 목록 이상의 문서를 위해, 에이전트는 IronWord의 llms.txt에서 시작할 수 있으며, 이 파일에는 안내서 및 문제 해결 페이지가 연결되어 있습니다.

첫 번째 저장 전 라이선싱을 해결하십시오. 키가 없으면 모든 저장 호출이 "Production License Required"라는 메시지가 포함된 LicensingException을 발생시킵니다. 이는 경로 또는 스트림이 유무에 관계없이 Save 및 SaveAs에 적용됩니다. IronWord 라이선스 키 페이지에서는 체험 및 유료 키와 코드 내 또는 구성 파일에서 키를 설정하는 방법을 설명합니다.

어떤 IronWord 병합 규칙이 CLAUDE.md에 들어가야 하나요?

픽스처 템플릿에 대한 탐색은 IronWord 2026.10.4를 기준으로 각 라인을 확인했으며, 마지막 세 개는 라이선스 키가 있었습니다. 병합 섹션 아래에 블록을 추가하십시오.

IronWord 2026.10.4 behaves this way in a mail merge:

- MailMerge.Execute(DataTable) merges the first row only.
- Merge each row into its own WordDocument, loaded fresh from the template file.
- A merge removes the fields it fills, so a second Execute on the same document changes nothing.
- Call ExecuteWithRegions before Execute.
- Execute removes any region it has no table for, because RemoveUnusedRegions defaults to true.
- That region's row then stays in the table with empty cells.
- A region table with no rows removes the region row and keeps the rest of the table.
- RemoveUnusedFields defaults to true, so a field with no matching key is deleted with no error.
- Compare GetFieldNames() with the data columns before merging.
- Field names match without regard to case unless CaseInsensitiveFieldNames is set to false.
- NullValueReplacement replaces DBNull values. An empty string merges as an empty string.
- WordDocument.ExtractText() returns body paragraphs only, joined with no separator.
- ExtractText() skips table cells, the header and the footer.
- Rows[i].Cells holds ITableCell values, which have no ExtractText().
- Cast each cell to TableCell before calling ExtractText() on it.
- GetFields() and GetFieldNames() don't see merge fields in the header.
- Save each letter with Save(outputPath).
- One troubleshooting page reports a header that SaveAs(outputPath) dropped and Save kept.
- Never call Save() with no argument. It overwrites the file the document was loaded from.
Markdown

사용되지 않는 필드 규칙은 탐색에서 가장 가시성이 낮은 오류를 초래했습니다. 템플릿에는 "참조" 다음에 고객 파일에 일치하는 열이 없는 참조 코드 필드가 포함되며, 기본 병합은 "참조"로 문장을 변경했습니다.. "이 번호를 언급하세요." 예외 없이.

Word 템플릿을 반복적으로 테이블 행과 병합하는 방법은?

템플릿에서 반복 행을 동일한 영역 이름을 공유하는 시작 필드와 끝 필드로 표시합니다. 픽스처 템플릿에서는 커버리지 행이 TableStart:Coverages로 시작하고 TableEnd:Coverages로 끝납니다. 영역 호출은 영역과 이름이 일치하는 데이터 테이블을 받아 각 데이터 행마다 한 번 복사합니다. 그 후, 값 호출은 영역 외부의 모든 필드를 사전 또는 단일 데이터 행에서 채웁니다.

메일 병합 가이드는 각 오버로드 및 병합 옵션을 문서화합니다.

컴파일되는 IronWord 코드를 프롬포트하는 방법은?

합병 및 그 감사는 하나의 프롬포트에 포함되며, 디자인이 파일 변경 전에 결정되도록 계획 모드로 전송됩니다. 계획 모드에서 Shift+Tab으로 순환하여 상태 바가 표시되면 프롬포트를 한 번 전송하십시오. Opus는 opusplan으로 계획을 처리하고 승인 후 Sonnet이 코드를 작성합니다.

Build the batch in Services/LetterMerger.cs and Services/LetterAudit.cs.
Run both from Program.cs after the Quickstart letter.

LetterMerger reads @Data/customers.csv and @Data/coverages.csv.
For each customer it does this:

1. Loads Templates/renewal-letter.docx again.
2. Fills the Coverages region with that policy's rows, if any.
3. Fills the other fields from the customer row.
4. Saves out/letters/<PolicyNumber>.docx.

Before the first merge, it prints each template merge field with no column in either CSV.

LetterAudit opens each saved letter from disk and passes it when these all hold:

- Every customer value appears in the body text.
- The coverage table holds only that policy's rows, in CSV order.
- word/document.xml, read as a zip entry, has no merge field or MERGEFIELD instruction left.

For an empty customer value, check its whole sentence.
One case is the agent sentence with no phone number.

Two more columns don't count toward a pass:

- Header, from word/header1.xml: shows the policy number, still has the merge field, or is missing.
- Footer, from word/footer1.xml: matches the template's footer, changed, or is missing.

Write out/letter-audit.csv with one row per letter.
Print how many letters pass.
After the batch, run git status on Templates/ and tell me about any change.

Don't use a docx skill or rewrite any package XML by hand.
The audit can read parts as zip entries.
Keep fixing the merger until every letter passes.
If a header keeps its field, tell me whether any IronWord call reached it.
Then have the merge-auditor subagent review Services/.
Text

프롬포트의 두 부분은 IronWord 및 Claude Code의 동작에 따라 달라집니다.

  1. 감사는 저장된 패키지를 읽습니다: 헤더와 푸터는 추출된 텍스트나 필드 목록에 포함되지 않습니다. IronWord 병합 호출은 헤더를 채우지 않으므로 그 열은 패스 카운트에서 제외되며, 이를 셈에 포함하면 프롬트에서 금지된 XML 해결 방법으로 에이전트를 유도할 것입니다.
  2. 읽기 전용 검토자: Explore와 Plan을 제외한 모든 기본 에이전트가 CLAUDE.md를 로드하므로, 병합 감사자는 메일 병합 규칙에 대해 Services/를 검토합니다.
팁: 계획이 고객별 루프 내에서 템플릿을 로드하고 값 호출 전에 영역 호출을 배치하는 경우에만 계획을 승인하십시오. 템플릿을 한 번 로드하는 계획은 첫 번째 서신의 다섯 개 사본을 생성합니다.

IronWord 병합 코드를 라이센스 키 없이 테스트할 수 있나요?

네, 저장 전에 테스트를 중단하는 한 가능합니다. 템플릿을 로드하고 이를 병합하고 텍스트를 읽는 모든 작업은 라이센스 없이 실행되므로 키가 없는 빌드 에이전트도 병합 테스트를 실행할 수 있습니다.

Add a RenewalLetters.Tests xUnit project that tests LetterMerger without writing any file.

Merge NM-104267 and NM-104288 in memory.
Assert the body text and every coverage table cell against the CSV rows.
Cover the policy with no coverage rows and the agent sentence with an empty phone number.

A few things about the setup:

- Split the merge from the save in LetterMerger if a test needs that.
- Leave the license key unset when the variable is missing.
- Put the test project in its own folder, with no solution file at the repository root.
- Keep RenewalLetters.csproj from compiling the files in that folder.
- Have the test project copy Templates/ and Data/ to its output folder.

Run dotnet test on the test project once, in a child process with no IRONWORD_LICENSE_KEY variable.
Show me the tests passing without a key.
Text

생성된 IronWord 코드를 신뢰하기 전에 무엇을 확인해야 하나요?

추출된 본문 텍스트에 대한 포함 테스트로 각 값을 비교하십시오. 단락 사이에 줄 바꿈 없이 반환되기 때문입니다.

검토에 세 가지 검사를 추가하십시오.

  • 빌드: IronWord에 존재하지 않는 멤버 이름에 대해 dotnet build이 실패합니다. 전달된 IronWord.xml은 공용이 아닌 멤버도 나열하므로, 그곳에서 발견된 이름이라도 CS1061로 실패할 수 있으며, 그 점은 두 WordDocument 멤버가 탐색에서 실패했습니다.
  • 템플릿: 배치 후 커밋된 복사본과 비교하십시오. 라이센스가 있는 탐색에서는 인수가 없는 단일 저장은 첫 번째 고객의 병합된 편지로 템플릿을 대체했으므로, 이후 그 파일을 로드할 때 채울 필드가 없었습니다.
  • 헤더: 헤더 문제 해결 페이지는 사용자에게 자신의 출력을 열어 헤더를 확인하도록 권장합니다. 같은 탐색에서 모든 저장 호출이 헤더와 푸터를 바이트 단위로 보존한다는 것이 밝혀졌습니다.

AI 코딩 도우미 가이드는 고정된 통과 기준을 가진 완전한 IronWord 작업을 포함하므로, 모든 독자가 이를 다시 실행할 수 있습니다.

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

Claude Code는 하나의 세션에서 네 개의 프롬프트를 차례로 실행했습니다. 세 번째 프롬포트 전에 병합 블록이 CLAUDE.md에 들어갔습니다. 코드는 수동으로 편집되지 않았습니다. 데이터는 다섯 명의 고객과 열 개의 보장 행을 보유하고 있었습니다. 깨끗한 릴리스 리빌드는 같은 감사 파일을 생성했습니다. 우리의 패키지 검사는 모든 행을 일치시켰습니다.

  • 값만으로 병합된 퀵스타트 서신은 헤더 행과 하나의 빈 행을 유지했습니다.
  • 5개의 배치 서신 모두 첫 번째 감사를 통과했습니다.
  • 서신은 CSV와 같이 3, 1, 4, 0, 2의 보장 행을 보유하고 있었습니다.
  • 사전 검사는 데이터 열이 없는 하나의 필드를 보고했습니다, ReferenceCode.
  • 정책 번호 필드는 모든 5개의 헤더에 남아 있었습니다.
  • 각 푸터는 템플릿과 일치했습니다.
  • 4개의 테스트 중 4개가 IRONWORD_LICENSE_KEY 없이 프로세스를 통과했습니다.
  • 하위 에이전트가 IronWord.xml에 없는 IronWord 멤버를 발견하지 못했습니다.
  • 배치 후 템플릿의 해시는 변경되지 않았습니다.
  • 모든 프롬포트는 깨끗한 릴리스 빌드로 끝났습니다.
  • 이번 실행의 모든 트랜스크립트, 세션 파일, 저장소 파일에 라이선스 키가 존재하지 않았습니다.
  • 프롬포트 1과 4에서 셸 테스트는 키가 설정되었는지를 출력했습니다.
  • 일부 단계는 페이지와 달리 작동했습니다. 세션이 헤드리스로 실행되었기 때문에, 운영자는 세 번째 프롬포트 계획을 타이핑된 응답으로 승인했습니다. 청크 3이 CLAUDE.md를 따르기 위해 퀵스타트의 SaveAs 호출을 Save로 변경했습니다.

Cursor 가이드에서는 Cursor도 파일을 편집하기 전에 계획하고, 계획을 편집 가능한 파일로 작성합니다. ChatGPT Codex 가이드는 AGENTS.md, Claude.md의 Codex 대응물에 서 설로을 저장합니다.

공유된 실행 기록은 이번 실행의 Claude Code 릴리스, 모델, 기간 및 테스트 머신을 제공합니다.


문제 해결


질문?

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

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

더 읽기

시작할 준비 되셨나요?

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