Como Usar IronWord com Claude Code
Todo novembro, uma seguradora envia cartas de renovação para seus segurados. A equipe de conformidade gerencia um único modelo Word para a redação da carta, enquanto nomes, datas, prêmios, e detalhes de cobertura são obtidos do sistema de apólices. Uma carta mesclada que parece completa não prova que a mesclagem funcionou. Nas sondagens por trás deste guia, mesclagens que deixaram uma linha de cobertura em branco, perderam um número de referência, ou reutilizaram os dados do primeiro cliente, todas terminaram sem uma exceção. Claude Code, a ferramenta de codificação agentica da Anthropic, lê uma base de código, edita arquivos e executa comandos de um terminal, VS Code, um IDE da JetBrains, o aplicativo de desktop ou um navegador.
IronWord preenche os espaços MERGEFIELD em modelos DOCX usando dicionários, linhas de dados ou conjuntos de dados, e suporta regiões repetitivas para linhas de tabela. Não requer Microsoft Office. A mesclagem em si leva algumas linhas de código. A ordem das chamadas e as opções padrão determinam se a saída está correta, e alguns erros produzem uma saída incorreta sem gerar uma exceção. Os quatro prompts testados abaixo configuram Claude Code para produzir um lote de cartas de renovação, e cada um é seguido pelo comportamento do IronWord do qual ele depende.
Início RápidoInicie claude na pasta do projeto e execute /model opusplan uma vez, antes de qualquer prompt. Um @ antes de um caminho inclui o conteúdo desse arquivo na solicitação.
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.
Revise a saída da tabela antes do texto do corpo. As linhas de cobertura estão em uma região repetitiva, que apenas a chamada de região preenche.
Fluxo de trabalho mínimo (5 etapas)
- Baixe a biblioteca C# Word do NuGet
- Abra Claude Code da pasta do projeto e defina o modelo com /model
- Registre as regras de mesclagem do IronWord em CLAUDE.md para que cada sessão as carregue.
- Solicite uma carta por linha de dados, com as linhas de região preenchidas antes dos outros campos.
- Reabra cada carta salva, verifique seu texto e as células da tabela em relação aos dados de origem, e inspecione suas partes de cabeçalho e rodapé.
O que Claude Code faz em um projeto de documento Word .NET?
Claude Code escreve o serviço de mesclagem e produz uma carta por apólice a partir dos dois arquivos CSV. Em seguida, reabre cada carta salva e a verifica. Quando uma verificação falha, ele revisa o código de mesclagem e executa o lote novamente. O desenvolvedor decide o que uma carta correta contém e revisa o arquivo de auditoria no final.
Nomeie o pacote IronWord e sua versão no primeiro prompt. Atacantes registram pacotes maliciosos com os nomes de pacotes que modelos de linguagem alucinam, uma técnica chamada slopsquatting.
Como você configura o Claude Code?
O início rápido da Anthropic cobre instalação e login. A configuração está completa assim que claude abre em um terminal e responde.
Como você configura um projeto no qual o Claude Code possa trabalhar?
Coloque entradas reais no repositório primeiro. O fixador usado neste guia consiste em um aplicativo de console .NET 9 que compila, uma pasta Templates contendo a carta de renovação com seus campos de mesclagem, e uma pasta Data com um CSV de clientes e um de linhas de cobertura, indexado por número de apólice.
Claude Code carrega CLAUDE.md em cada nova sessão, então suas regras se aplicam a todos os prompts posteriores. Depois que o Início Rápido instala o pacote, um segundo prompt cria esse arquivo e um revisor para o código de mesclagem.
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.
Claude Code observa .claude/agents para novos arquivos de subagentes, mas o observador cobre apenas pastas presentes no lançamento, portanto, crie essa pasta antes de iniciar a sessão. Para documentação além da lista de membros, agentes podem começar a partir de llms.txt do IronWord, que vincula os guias de como fazer e as páginas de solução de problemas.
Resolva o licenciamento antes da primeira salvamento. Sem uma chave, toda chamada de salvamento gera uma LicensingException que lê "Licença de Produção Necessária". Isso aplica-se a Save com ou sem um caminho ou fluxo, e a SaveAs. A página de Chaves de Licença do IronWord abrange chaves de teste e pagas e como configurar uma em código ou em um arquivo de configuração.
Quais regras de mesclagem do IronWord pertencem a CLAUDE.md?
Uma sondagem sobre o modelo fixador verificou cada linha contra o IronWord 2026.10.4, com uma chave de licença para os últimos três. Adicione o bloco sob a seção de Mesclagem de correio.
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.
A regra de campo não utilizado produziu a falha menos visível nas sondagens. O modelo contém "Referência" seguido por um campo código de referência sem coluna correspondente no arquivo do cliente, e a mesclagem padrão alterou a frase para "Referência . Cite este número quando nos ligar." sem gerar uma exceção.
Como você mescla um modelo Word com linhas de tabela repetitivas?
Marque a linha repetitiva no modelo com um campo de início e um campo de fim que compartilhem um nome de região. No modelo fixador, a linha de cobertura começa com TableStart:Coverages e termina com TableEnd:Coverages. A chamada de região aceita uma tabela de dados cujo nome corresponde à região e copia a linha uma vez para cada linha de dados. A chamada de valor então preenche cada campo fora da região a partir de um dicionário ou uma única linha de dados.
O guia de mesclagem de correio documenta cada sobrecarga e opção de mesclagem.
Como você solicita código IronWord que compila?
O merger e sua auditoria vão em um único prompt, enviado no modo de plano para que o design seja acertado antes de quaisquer alterações no arquivo. Ciclo com Shift+Tab para o modo plano e envie o prompt assim que a barra de status exibir. Com opusplan, Opus lida com o plano e Sonnet escreve o código após a aprovação.
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/.
Duas partes do prompt dependem de como IronWord e Claude Code se comportam.
- A auditoria lê o pacote salvo: o cabeçalho e o rodapé não são incluídos no texto extraído ou na lista de campos. Suas colunas são excluídas da contagem de passes porque nenhuma chamada de mesclagem do IronWord preenche o cabeçalho, então contá-lo levaria o agente à solução alternativa XML que o prompt proíbe.
- Um revisor somente leitura: subagentes personalizados carregam CLAUDE.md, assim como todos os agentes internos, exceto Explorar e Planejar, então o revisor de mesclagem revisa Serviços/contra as regras de Mesclagem de Correio.
O código de mesclagem do IronWord pode ser testado sem uma chave de licença?
Sim, desde que o teste pare antes do salvamento. Carregar o modelo, mesclá-lo, e ler o texto de volta todos executam sem licença, então um agente de construção sem chave ainda pode executar os testes de mesclagem.
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.
O que você deve verificar antes de confiar no código IronWord gerado?
Compare cada valor com um teste de contagem no texto do corpo extraído, porque seus parágrafos são retornados sem quebras de linha entre eles.
Adicione três verificações à revisão.
- A compilação:
dotnet buildfalha em qualquer nome de membro que o IronWord não tem. O IronWord.xml enviado também lista membros que não são públicos, então um nome encontrado lá ainda pode falhar com CS1061, como dois membros WordDocument fizeram na sonda. - O modelo: compare-o com sua cópia comprometida após o lote. Em nossa sonda licenciada, um único salvamento sem argumento substituiu o modelo pela carta mesclada do primeiro cliente, portanto, todas as cargas subsequentes desse arquivo não continham campos para preencher.
- O cabeçalho: a página de solução de problemas de cabeçalho informa aos leitores que abram seu próprio resultado e confiram o cabeçalho. A mesma sonda descobriu que cada chamada de salvamento preservava o cabeçalho e o rodapé byte a byte.
O guia de assistentes de codificação de IA contém uma tarefa completa do IronWord cujos critérios de aprovação são fixos, para que qualquer leitor possa executá-la novamente.
O que os prompts produziram em uma execução real?
Claude Code executou as quatro sugestões em uma sessão, em ordem. O bloco de Mesclagem de Correio foi para CLAUDE.md antes do prompt 3. Nenhum código foi editado manualmente. Os dados continham cinco clientes e dez linhas de cobertura. Uma reconstrução limpa do Release produziu o mesmo arquivo de auditoria. Nossa inspeção de pacote correspondia a cada linha.
- A carta do Início Rápido, mesclada apenas com valores, manteve a linha de cabeçalho e uma linha vazia.
- Todas as 5 cartas do lote passaram na primeira auditoria.
- As cartas continham 3, 1, 4, 0, e 2 linhas de cobertura, como no CSV.
- O pré-teste reportou um campo sem coluna de dados, ReferenceCode.
- O campo de número da apólice permaneceu em todos os 5 cabeçalhos.
- Cada rodapé combinava com o modelo.
- 4 de 4 testes passaram com IRONWORD_LICENSE_KEY ausente do processo.
- O subagente não encontrou nenhum membro do IronWord faltando no IronWord.xml.
- O hash do modelo estava inalterado após o lote.
- Cada prompt terminou com uma compilação limpa do Release.
- A chave de licença estava ausente de cada transcrição, arquivo de sessão, e arquivo do repositório desta execução.
- Nos prompts 1 e 4, um teste de shell imprimiu apenas se a chave estava configurada.
- Alguns passos foram executados de forma diferente da página. Como a sessão foi executada sem interface, o operador aprovou o plano do prompt 3 com uma resposta digitada. O prompt 3 alterou a chamada SaveAs no Início Rápido para Save para seguir CLAUDE.md.
No guia do Cursor, o Cursor também planeja antes de editar qualquer arquivo, e escreve o plano em um arquivo editável. O guia ChatGPT Codex armazena suas instruções permanentes em AGENTS.md, o correspondente do Codex de CLAUDE.md.
O registro de execução compartilhado fornece o release do Claude Code desta execução, modelos, duração, e máquina de teste.
Solução de problemas
- Documentos Word de Mesclagem de Correio se uma região ou campo não preencher.
- Cabeçalho Desaparece Após SaveAs se uma carta mesclada perder seu cabeçalho.
- Licença IronWord em web.config se a chave na configuração for ignorada.
Questões?
Se você tiver dúvidas, entre em contato com support@ironsoftware.com
Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.