A Shared Spelling Dictionary Is a Review Artifact, Not a Suppression List

One line in CLAUDE.md turns a repeated warning into a one-time review decision

Sooner or later, cspell flags a word in one of my repos that isn't a typo at all. It's a product name, a vendor's own spelling, or just a word my code genuinely needs. The check is right to ask about it once. The problem is what happens the second, third, and tenth time the same word shows up in a different file.

Two Bad Options

The obvious fix is an inline cspell:ignore comment at the exact line that triggered the warning. It works, technically. It also means the same word gets re-justified every time someone touches a nearby line, and a reviewer scanning a diff has no way to tell "this is an accepted term" from "nobody checked this yet." Do it enough times and the suppressions become noise that outlives the reason anyone added them.

The other bad option is to just ignore the warning. That's worse — it trains everyone to skim past cspell output, which is exactly the failure mode a spellchecker exists to prevent.

What's in AndrewDongminYoo/localizations Instead

One of my repos, localizations, takes a third path. Its CLAUDE.md states it plainly:

When adding new product names or technical terms, update .cspell/custom-dictionary.txt if spellcheck flags them.

AGENTS.md repeats the same instruction for an AI-assisted session. The wiring behind it is a few lines in cspell.config.yaml:

dictionaryDefinitions:
  - name: custom-dictionary
    path: ./.cspell/custom-dictionary.txt
    addWords: true
dictionaries:
  - custom-dictionary

And the dictionary file itself is exactly what it sounds like — a flat, alphabetized list. Reading the first lines of the real file in that repo turns up entries like AAID, assetlinks, Bitrise, cmdk, Embla, and — genuinely — donminzzi. That's the name of my website and my business, and a lot of my apps put their bundle and package IDs under kr.donminzzi. A spellchecker has no way of knowing any of that, so to cspell it's just a typo.

That last one is my favorite failure mode: the tool doesn't know what it doesn't know, and the dictionary is where you tell it, once, in a place everyone can see.

What the Dictionary File Actually Buys You

None of this is enforced by cspell itself — it's just what the convention produces once you follow it for a while:

• It's reusable. A word added once is recognized everywhere — this file, the next file, a file that doesn't exist yet.
• It's reviewable. A diff to custom-dictionary.txt is a yes/no question a reviewer can actually answer, instead of a scattered set of inline comments nobody re-checks.
• It keeps the signal. An inline suppression says "ignore this line." A dictionary entry says "this word is accepted, repository-wide, on purpose." The second one is the statement you actually want a year later.
• It's less friction for whoever touches the file next. Nobody has to re-decide "is this a real word or a typo?" for a term the repo already settled.

Where This Convention Actually Lives — and Where It Doesn't

localizations isn't a one-off. When I went looking through the agent instructions in my own repositories, at least five others write down the same rule or a close variant of it: new terms go in .cspell/custom-dictionary.txt. Some phrase it as a direction to the agent ("Add new project terms there, not inline cspell:disable"), some as a scoping rule ("Keep CSpell additions scoped to .cspell/custom-dictionary.txt"), and two also accept words added to cspell.json.

It isn't everywhere, though. One of my repos keeps its words in a differently named file and accepts an inline // cspell:words comment as an equal option. If a repo doesn't have cspell configured, or has settled on a different suppression policy, none of this transfers automatically. The dictionary file is a repo-local decision, not a personal law.

One carve-out I'd keep anyway: inline cspell:ignore still earns its place for genuine one-offs — a base64 blob, a hash, a deliberately misspelled string inside a quoted test fixture. Those aren't vocabulary the repository is adopting; they're noise that happens to live at one specific line, and the dictionary file is the wrong place for them.

If You're Setting This Up

Add the dictionary once, wire it into your spellchecker config, and write the instruction down somewhere a reviewer — human or AI — will actually read it before adding the tenth inline suppression. The payoff isn't fewer warnings. It's a dictionary file that tells you, in one diff, exactly which words this repository decided to trust.

What does your own custom-dictionary.txt look like? I'd bet it has at least one entry as oddly personal as mine.