Comment utiliser IronWord avec Claude Code

Curtis Chau
Curtis Chau
Mis à jour : 19 octobre 2026

Chaque novembre, un assureur envoie des lettres de renouvellement à ses assurés. L'équipe de conformité gère un modèle unique de document Word pour le texte de la lettre, tandis que les noms, dates, primes et détails de couverture proviennent du système de polices. Une lettre fusionnée qui semble complète ne prouve pas que la fusion a fonctionné. Dans les tests à l'origine de ce guide, des fusions qui ont laissé une ligne de couverture vide, supprimé un numéro de référence ou réutilisé les données du premier client ont toutes été terminées sans exception. Claude Code, l'outil de codage agentique d'Anthropic, lit un code source, édite des fichiers et exécute des commandes depuis un terminal, VS Code, un IDE JetBrains, l'application de bureau ou un navigateur.

IronWord remplit les espaces réservés MERGEFIELD dans les modèles DOCX avec des dictionnaires, des lignes de données ou des ensembles de données, et prend en charge les régions répétées pour les lignes de tableaux. Il ne nécessite pas Microsoft Office. La fusion elle-même nécessite quelques lignes de code. L'ordre des appels et les options par défaut déterminent si le résultat est correct, et certaines erreurs produisent un mauvais résultat sans lever d'exception. Les quatre invites testées ci-dessous configurent Claude Code pour produire un lot de lettres de renouvellement, chacune étant suivie par le comportement IronWord sur lequel elle repose.

Démarrage rapide
NuGetInstaller avec NuGet

PM > Install-Package IronWord

Installez IronWord en exécutant la commande ci-dessus dans la console du gestionnaire de packages NuGet, ou recherchez le package dans le gestionnaire de packages NuGet.

Commencez claude dans le dossier du projet et exécutez /model opusplan une fois, avant toute invite. Un @ avant un chemin inclut le contenu de ce fichier dans la requête.

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

Examinez le résultat du tableau avant le texte principal. Les lignes de couverture sont dans une région répétée, que seul l'appel de la région remplit.



Que fait Claude Code dans un projet de document Word .NET ?

Claude Code écrit le service de fusion et produit une lettre par police à partir des deux fichiers CSV. Il rouvre ensuite chaque lettre enregistrée et la vérifie. Lorsqu'une vérification échoue, il révise le code de fusion et relance le lot. Le développeur décide de ce que contient une lettre correcte et examine le fichier d'audit à la fin.

Nommez le package IronWord et sa version dans la première invite. Les attaquants enregistrent des packages malveillants sous les noms de package que les modèles de langage imaginent, une technique appelée slopsquatting.

Comment configurer Claude Code ?

Le démarrage rapide d'Anthropic couvre l'installation et la connexion. La configuration est terminée une fois que claude s'ouvre dans un terminal et réagit.

Comment configurer un projet dans lequel Claude Code peut travailler ?

Mettez d'abord de véritables entrées dans le dépôt. Le modèle utilisé dans ce guide se compose d'une application console .NET 9 qui se compile, d'un dossier Templates contenant la lettre de renouvellement avec ses champs de fusion, et d'un dossier Data avec un CSV de clients et un de lignes de couverture indexées par numéro de police.

Claude Code charge CLAUDE.md dans chaque nouvelle session, donc ses règles s'appliquent à toutes les invites ultérieures. Après que le démarrage rapide installe le package, une deuxième invite crée ce fichier ainsi qu'un examinateur pour le code de fusion.

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 surveille .claude/agents pour de nouveaux fichiers de sous-agents, mais le surveillant ne couvre que les dossiers présents au lancement, donc créez ce dossier avant de commencer la session. Pour la documentation au-delà de la liste des membres, les agents peuvent commencer à partir de llms.txt d'IronWord, qui lie les guides pratiques et les pages de résolution de problèmes.

Abordez l'octroi de licence avant la première sauvegarde. Sans clé, chaque appel de sauvegarde déclenche une LicensingException qui indique "Production License Required". Cela s'applique à Save avec ou sans chemin ou flux, et à SaveAs. La page IronWord License Keys couvre les clés d'essai et payantes et explique comment en définir une dans le code ou dans un fichier de configuration.

Quels règles de fusion de courrier IronWord appartiennent à CLAUDE.md ?

Un test sur le modèle de gabarit a vérifié chaque ligne par rapport à IronWord 2026.10.4, avec une clé de licence pour les trois dernières. Ajoutez le bloc sous la section Mail merge.

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

La règle du champ inutilisé a produit l'échec le moins visible dans les tests. Le modèle contient "Reference" suivi d'un champ de code de référence sans colonne correspondante dans le fichier client, et la fusion par défaut a modifié la phrase en "Reference . Citez ce numéro lorsque vous nous appelez." sans déclencher d'exception.

Comment fusionner un modèle Word avec des lignes de tableau répétées ?

Marquez la ligne répétée dans le modèle avec un champ de début et un champ de fin partageant un même nom de région. Dans le modèle de gabarit, la ligne de couverture commence par TableStart:Coverages et se termine par TableEnd:Coverages. L'appel de la région accepte une table de données dont le nom correspond à la région et copie la ligne une fois pour chaque ligne de données. L'appel de valeur remplit ensuite chaque champ en dehors de la région à partir d'un dictionnaire ou d'une unique ligne de données.

Le guide de fusion de courrier documente chaque surcharge et option de fusion.

Comment inciter pour un code IronWord qui se compile ?

La fusion et son audit vont dans une seule invite, envoyée en mode plan pour que la conception soit arrêtée avant toute modification de fichier. Cyclez avec Shift+Tab pour le mode plan et envoyez l'invite une fois que la barre d'état l'affiche. Avec opusplan, Opus gère le plan et Sonnet écrit le code après approbation.

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

Deux parties de l'invite dépendent du comportement d'IronWord et de Claude Code.

  1. L'audit lit le package enregistré : l'en-tête et le pied de page ne sont pas inclus dans le texte extrait ou la liste des champs. Leurs colonnes sont exclues du nombre de passes car aucun appel de fusion IronWord ne remplit l'en-tête, donc le compter conduirait l'agent à la solution de contournement XML que l'invite interdit.
  2. Un relecteur en lecture seule : les sous-agents personnalisés chargent CLAUDE.md, tout comme tous les agents intégrés sauf Explore et Plan, donc l'auditeur de fusion examine Services/contre les règles de fusion de courrier.
Conseils: Approuvez le plan uniquement s'il charge le modèle à l'intérieur de la boucle par client et place l'appel de région avant l'appel de valeur. Un plan qui charge le modèle une fois produit cinq copies de la première lettre.

Le code de fusion IronWord peut-il être testé sans clé de licence ?

Oui, tant que le test s'arrête avant la sauvegarde. Charger le modèle, le fusionner et lire le texte en arrière-plan se déroulent sans licence, donc un agent de compilation sans clé peut toujours exécuter les tests de fusion.

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

Que devez-vous vérifier avant de faire confiance au code généré par IronWord ?

Comparez chaque valeur avec un test de contenu sur le texte principal extrait, car ses paragraphes sont renvoyés sans saut de ligne entre eux.

Ajoutez trois vérifications à l'examen.

  • La construction : dotnet build échoue sur tout nom de membre qu'IronWord n'a pas. L'IronWord.xml fourni liste également les membres qui ne sont pas publics, donc un nom trouvé là peut encore échouer avec CS1061, comme deux membres de WordDocument dans le test.
  • Le modèle : comparez-le avec sa copie validée après le traitement en lot. Dans notre test sous licence, une seule sauvegarde sans argument a remplacé le modèle par la lettre fusionnée du premier client, donc chaque chargement ultérieur de ce fichier ne contenait pas de champs à remplir.
  • L'en-tête : la page de résolution des problèmes d'en-tête demande aux lecteurs d'ouvrir leur propre sortie et de vérifier l'en-tête. Le même test a trouvé que chaque appel de sauvegarde préservait l'en-tête et le pied de page octet par octet.

Le guide des assistants de codage IA contient une tâche IronWord complète dont les critères de réussite sont fixes, de sorte que tout lecteur peut la relancer.

Qu'est-ce que les messages ont produit lors d'une réelle exécution ?

Claude Code a exécuté les quatre invites en une seule session, dans l'ordre. Le bloc de fusion de courrier est entré dans CLAUDE.md avant l'invite 3. Aucun code n'a été édité à la main. Les données contenaient cinq clients et dix lignes de couverture. Une reconstruction propre Rélease a produit le même fichier d'audit. Notre inspection de package a correspondu à chaque ligne.

  • La lettre Quickstart, fusionnée uniquement avec des valeurs, a conservé la ligne d'en-tête et une ligne vide.
  • Toutes les 5 lettres du lot ont passé le premier audit.
  • Les lettres ont contenu 3, 1, 4, 0 et 2 lignes de couverture, comme dans le CSV.
  • Le pré-vérification a rapporté un champ sans colonne de données, ReferenceCode.
  • Le champ de numéro de police est resté dans les 5 en-têtes.
  • Chaque pied de page a correspondu au modèle.
  • 4 des 4 tests ont réussi avec IRONWORD_LICENSE_KEY absent du processus.
  • Le sous-agent n'a trouvé aucun membre d'IronWord manquant dans IronWord.xml.
  • Le hachage du modèle était inchangé après le traitement en lot.
  • Chaque invite s'est terminée par une reconstruction propre Rélease.
  • La clé de licence était absente de chaque transcription, fichier de session et fichier de dépôt de cette exécution.
  • Dans les invites 1 et 4, un test de shell a imprimé uniquement si la clé était définie.
  • Certaines étapes ont été exécutées différemment de la page. Parce que la session s'est déroulée sans interface, l'opérateur a approuvé le plan de l'invite 3 avec une réponse tapée. L'invite 3 a changé l'appel SaveAs du démarrage rapide en Save pour suivre CLAUDE.md.

Dans le guide du curseur, le curseur planifie aussi avant de modifier tout fichier, et il écrit le plan dans un fichier modifiable. Le guide ChatGPT Codex stocke ses instructions permanentes dans AGENTS.md, l'homologue du Codex de CLAUDE.md.

Le journal d'exécution partagé donne la version de Claude Code de cette exécution, les modèles, la durée et la machine de test.


Dépannage


Des questions ?

Si vous avez des questions, contactez support@ironsoftware.com

Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes et créer des manuels bien structurés et visuellement attrayants.

Lire la suite

Prêt à commencer ?

Téléchargements NuGet 62,392Version :2026.11tout juste publié