Cómo usar IronWord con Claude Code
Cada noviembre, una aseguradora envía cartas de renovación a sus asegurados. El equipo de cumplimiento gestiona una única plantilla de Word para el texto de la carta, mientras que los nombres, fechas, primas y detalles de cobertura se obtienen del sistema de pólizas. Una carta combinada que parece completa no prueba que la combinación haya funcionado. En las pruebas detrás de esta guía, combinaciones que dejaron una fila de cobertura en blanco, eliminaron un número de referencia o reutilizaron los datos del primer cliente, todas terminaron sin una excepción. Claude Code, la herramienta de codificación agéntica de Anthropic, lee una base de código, edita archivos y ejecuta comandos desde un terminal, VS Code, un IDE de JetBrains, la aplicación de escritorio o un navegador.
IronWord llena marcadores MERGEFIELD en plantillas DOCX usando diccionarios, filas de datos o conjuntos de datos, y es compatible con regiones repetitivas para filas de tabla. No requiere Microsoft Office. La combinación en sí misma requiere unas pocas líneas de código. El orden de las llamadas y las opciones predeterminadas determinan si la salida es correcta, y algunos errores producen una salida incorrecta sin generar una excepción. Los cuatro comandos probados a continuación configuran Claude Code para producir un lote de cartas de renovación, y cada uno es seguido por el comportamiento de IronWord en el que confía.
Inicio rápidoInicie claude en la carpeta del proyecto y ejecute /model opusplan una vez, antes de cualquier comando. Un @ antes de una ruta incluye el contenido de ese archivo en la solicitud.
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 la salida de la tabla antes del texto del cuerpo. Las filas de cobertura están en una región repetitiva, que solo la llamada a la región llena.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de Word de C# desde NuGet
- Abra Claude Code desde la carpeta del proyecto y configure el modelo con /model
- Registre las reglas de combinación de IronWord en CLAUDE.md para que cada sesión las cargue.
- Solicite una carta por fila de datos, con las filas de la región llenas antes que los otros campos.
- Reabra cada carta guardada, verifique su texto y las celdas de la tabla contra los datos de origen, e inspeccione sus partes de encabezado y pie de página.
¿Qué hace Claude Code en un proyecto de documento de Word .NET?
Claude Code escribe el servicio de combinación y produce una carta por póliza a partir de los dos archivos CSV. Luego vuelve a abrir cada carta guardada y la verifica. Cuando una verificación falla, revisa el código de combinación y vuelve a ejecutar el lote. El desarrollador decide qué contiene una carta correcta y revisa el archivo de auditoría al final.
Nombre el paquete de IronWord y su versión en el primer comando. Los atacantes registran paquetes maliciosos bajo los nombres de los paquetes que los modelos de lenguaje alucinan, una técnica llamada slopsquatting.
¿Cómo configuras Claude Code?
El inicio rápido de Anthropic cubre la instalación y el inicio de sesión. La configuración se completa una vez que claude se abre en un terminal y responde.
¿Cómo configuras un proyecto en el que Claude Code pueda trabajar?
Ponga primero entradas reales en el repositorio. El dispositivo utilizado en esta guía consiste en una aplicación de consola .NET 9 que compila, una carpeta de Plantillas que contiene la carta de renovación con sus campos de combinación, y una carpeta de Datos con un CSV de clientes y otro de filas de cobertura claveadas por número de póliza.
Claude Code carga CLAUDE.md en cada nueva sesión, por lo que sus reglas se aplican a todas las solicitudes posteriores. Después de que el inicio rápido instala el paquete, un segundo comando crea ese archivo y un revisor para el código de combinación.
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/agentes en busca de nuevos archivos de subagentes, pero el observador solo cubre carpetas presentes al inicio, por lo que cree esa carpeta antes de comenzar la sesión. Para documentación más allá de la lista de miembros, los agentes pueden comenzar desde el llms.txt de IronWord, que enlaza las guías de cómo hacerlo y las páginas de resolución de problemas.
Aborde el licenciamiento antes de la primera guardada. Sin una clave, cada llamada de guardado lanza una LicensingException que dice "Se requiere licencia de producción". Esto se aplica a Save con o sin una ruta o flujo, y a SaveAs. La página de Claves de Licencia de IronWord cubre claves de prueba y pagadas y cómo establecer una en código o en un archivo de configuración.
¿Qué reglas de combinación de correspondencia de IronWord pertenecen a CLAUDE.md?
Una prueba en la plantilla del dispositivo verificó cada línea contra IronWord 2026.10.4, con una clave de licencia para las últimas tres. Agregue el bloque bajo la sección de combinación de correo.
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.
La regla de campo no utilizado produjo el fallo menos visible en las pruebas. La plantilla contiene "Referencia" seguido de un campo de código de referencia sin columna coincidente en el archivo de clientes, y la combinación predeterminada cambió la oración a "Referencia . Cite este número cuando nos llame." sin generar una excepción.
¿Cómo se combina una plantilla de Word con filas de tabla repetitivas?
Marque la fila repetitiva en la plantilla con un campo de inicio y un campo de fin que compartan un nombre de región. En la plantilla del dispositivo, la fila de cobertura comienza con TableStart:Coverages y termina con TableEnd:Coverages. La llamada a la región acepta una tabla de datos cuyo nombre coincide con la región y copia la fila una vez por cada fila de datos. Luego, la llamada al valor llena cada campo fuera de la región a partir de un diccionario o una sola fila de datos.
La guía de combinación de correo documenta cada sobrecarga y opción de combinación.
¿Cómo se solicita código de IronWord que compila?
La combinación y su auditoría van en un solo comando, enviado en modo plan para que el diseño esté listo antes de cualquier cambio de archivo. Ciclo con Shift+Tab a modo plan y envíe el comando una vez que la barra de estado lo muestre. Con opusplan, Opus maneja el plan y Sonnet escribe el código después de la aprobación.
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/.
Dos partes del comando dependen de cómo se comportan IronWord y Claude Code.
- La auditoría lee el paquete guardado: el encabezado y el pie de página no están incluidos en el texto extraído o en la lista de campos. Sus columnas están excluidas del conteo de pasadas porque ninguna llamada de combinación de IronWord llena el encabezado, por lo que contarlo llevaría al agente al solución alternativa XML que el comando prohíbe.
- Un revisor de solo lectura: los subagentes personalizados cargan CLAUDE.md, al igual que todos los agentes integrados excepto Explorar y Planear, por lo que el auditor de combinación revisa Services/contra las reglas de combinación de correo.
¿Se puede probar el código de combinación de IronWord sin una clave de licencia?
Sí, siempre y cuando la prueba se detenga antes de guardar. Cargar la plantilla, combinarla y leer el texto de nuevo todo se ejecuta sin licencia, por lo que un agente de compilación sin clave aún puede ejecutar las pruebas de combinación.
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.
¿Qué debe verificar antes de confiar en el código de IronWord generado?
Compare cada valor con una prueba de contiene en el texto del cuerpo extraído, porque sus párrafos se devuelven sin saltos de línea entre ellos.
Agregue tres verificaciones a la revisión.
- La compilación:
dotnet buildfalla en cualquier nombre de miembro que le falte a IronWord. El IronWord.xml enviado también enumera miembros que no son públicos, por lo que un nombre encontrado allí aún puede fallar con CS1061, como lo hicieron dos miembros de WordDocument en la prueba. - La plantilla: compárela con su copia comprometida después del lote. En nuestra prueba con licencia, un solo guardado sin argumento reemplazó la plantilla con la carta combinada del primer cliente, por lo que cada carga posterior de ese archivo no contenía campos a llenar.
- El encabezado: la página de soluciones de problemas del encabezado indica a los lectores que abran su propia salida y verifiquen el encabezado. La misma prueba encontró que cada llamada de guardado preservó el encabezado y el pie de página byte por byte.
La guía de asistentes de codificación con IA contiene una tarea completa de IronWord cuyos criterios de aprobación están establecidos, por lo que cualquier lector puede volver a ejecutarla.
¿Qué produjeron los prompts en una ejecución real?
Claude Code ejecutó los cuatro mensajes en una sesión, en orden. El bloque de combinación de correo se colocó en CLAUDE.md antes del comando 3. No se editó código a mano. Los datos contenían cinco clientes y diez filas de cobertura. Una reconstrucción de Release limpia produjo el mismo archivo de auditoría. Nuestra inspección del paquete coincidió con cada fila.
- La carta de inicio rápido, combinada solo con valores, mantuvo la fila de encabezado y una fila vacía.
- Todas las 5 cartas del lote pasaron la primera auditoría.
- Las cartas contenían 3, 1, 4, 0 y 2 filas de cobertura, como en el CSV.
- La verificación previa al vuelo informó un campo sin columna de datos, ReferenceCode.
- El campo de número de póliza permaneció en los 5 encabezados.
- Cada pie de página coincidió con la plantilla.
- 4 de 4 pruebas pasaron sin que IRONWORD_LICENSE_KEY estuviera presente en el proceso.
- El subagente no encontró ningún miembro de IronWord faltante en IronWord.xml.
- El hash de la plantilla no cambió después del lote.
- Cada comando terminó con una compilación de Release limpia.
- La clave de licencia estaba ausente de cada transcripción, archivo de sesión y archivo de repositorio de esta ejecución.
- En los comandos 1 y 4, una prueba de shell imprimió solo si la clave estaba establecida.
- Algunos pasos se ejecutaron de manera diferente a lo esperado. Debido a que la sesión se ejecutó sin cabeza, el operador aprobó el plan del comando 3 con una respuesta escrita. El comando 3 cambió la llamada SaveAs del Inicio Rápido a Save para seguir CLAUDE.md.
En la guía de Cursor, Cursor también planea antes de editar cualquier archivo, y escribe el plan en un archivo editable. La guía de ChatGPT Codex almacena sus instrucciones permanentes en AGENTS.md, la contraparte de Codex de CLAUDE.md.
El registro compartido de ejecución proporciona esta ejecución de Claude Code, modelos, duración y máquina de prueba.
Solución de problemas
- Documentos de Word con combinación de correspondencia si una región o campo no se llena
- El encabezado desaparece después de SaveAs si una carta combinada pierde su encabezado
- Licencia de IronWord en web.config si la clave en la configuración es ignorada
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.