cspell

Core Principles

1. Config Check First — Verify repo has cspell config before any action; offer bootstrap if missing
2. Adjust Text Before Adding to Dictionary — Restructure words (hyphenate, camelCase) when safe
3. Narrowest Scope Wins — Inline directive for one-off words; project dictionary for recurring terms

Documentation: Fetch cspell syntax and config details via Context7 (

/streetsidesoftware/cspell

) at runtime; never rely on hardcoded syntax.

When to Use

• cspell flags an unknown word (IDE diagnostic or CI output)
• User asks to fix cspell warnings, add words to dictionary, or suppress cspell errors
• User wants to set up cspell in a project that doesn't have it
• User asks why a word is flagged or wants to understand cspell behavior
• Linting pipeline or pre-commit hook fails due to unrecognized words

Workflow

1. Check for cspell config — Search from the file's directory upward for cspell config files:

   package.json

   (

   cspell

   field),

   .cspell.json

   ,

   cspell.json

   ,

   cspell.config.{json,mjs,js,cjs,yaml,yml,toml}

   ,

   cspell.{yaml,yml}

   , and their

   .

   /

   .config/

   prefixed variants (e.g.,

   .cspell.config.yaml

   ,

   .config/cspell.json

   ). Also check

   .vscode/cspell.json

   . If none found: notify user, do NOT auto-fix, offer to bootstrap (see below). Note:

   cspell.*

   settings in

   .vscode/settings.json

   are IDE-local and do not count as project config.
2. Apply fix priority — Stop at the first applicable level (see table below).
3. Select directive — When using inline directives, consult decision-tree.md for the selection guide.

Fix Priority

Config Bootstrapping

Guidelines

DO

• Check repo config before any action
• Prefer text adjustment over dictionary pollution
• Use narrowest scope directive that fits
• Place

  cspell:words

  at file top for discoverability
• Verify the flagged word is genuinely unknown (not a missing dictionary)

DON'T

• Replace words with semantically different alternatives
• Add one-off words to project dictionary (use inline directives)
• Use

  cspell:disable

  to suppress large sections when individual words can be handled
• Blindly accept all cspell suggestions — some flagged words are correct
• Hyphenate or restructure runtime API identifiers, package names, or fixed external terms

Error Handling

cspell .

ignorePaths

cspell init --help

For bootstrapping-specific errors (

cspell

CLI not installed,

cspell init

fails), see config-bootstrapping.md.

Reference Files

• decision-tree.md — Full decision flowchart, text adjustment rules and exceptions, dictionary vs inline criteria, directive selection, edge cases
• config-bootstrapping.md — Interactive setup flow, stack detection, CI integration, post-init adjustments