AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

AI-assistance policy (read first)

codespell is maintained by a small number of volunteers. Code is reviewed and maintained by humans, so interactions about it should be between humans, too.

  • The human opening the PR is the sole author. Do not add AI co-authorship trailers (Co-Authored-By: for Claude / Copilot / Cursor / any other tool) to commits, and do not use a bot as the commit author. The author takes full responsibility for the contents and must be able to explain and defend every line on request.
  • Do not write issues, PR descriptions, or comments for the human. Pasted AI-generated text makes it harder for reviewers to assess a contribution. The human writes those in their own words, and discloses in the PR description which AI tools were used and the scope of their assistance.
  • Optimize for the reviewer and for long-term maintainability, not for output volume. Every line you add is read by a volunteer reviewer and then maintained by humans in perpetuity.

Keep changes small

A big diff is a cost, not an accomplishment. Aim for the smallest change that delivers the user-visible behavior; anything else can be added later, when something actually needs it.

  • Sketch before you generate. For anything beyond a local fix, summarize the design in a few sentences for the human you are working with and confirm it is the smallest one that works before writing code.
  • YAGNI. Do not add options, config knobs, fallbacks, or “robustness” the change does not need. Every new command-line option is documented, tested, and supported forever, so it needs a demonstrated user need, not a hypothetical one.
  • Reuse before writing something new. Look for an existing helper in codespell_lib/_codespell.py and build on it rather than adding a near-duplicate.
  • Do not add dependencies without asking first.
  • Add to an existing test before writing a new one. Extend a test in codespell_lib/tests/test_basic.py that already sets up what you need, then add a new test function there, and only then consider a new file. A few compact assertions beat a long test that re-creates setup.
  • For a bug fix, confirm the test fails without the fix and passes with it. A regression test that passes without the fix guards nothing.

Commands

pip install -e . --group dev        # editable install with test/lint deps
pre-commit install --install-hooks  # ruff, mypy, codespell, file sorting, ...
pytest codespell_lib/tests/test_basic.py -k write_changes  # CLI tests
make check-dictionaries  # sort + validate dictionaries (test_dictionary.py)
pre-commit run --all-files          # all linters, auto-fixing where possible
make check               # everything CI checks: dictionaries, build, pytest, ruff

Project layout

Pure Python (>= 3.9), no runtime dependencies.

  • codespell_lib/_codespell.py: the CLI (main()), option parsing, and file checking/fixing.
  • codespell_lib/data/dictionary*.txt: the misspelling dictionaries, one per --builtin set.
  • codespell_lib/tests/test_basic.py: CLI behavior tests, mostly calling cs.main(...) on files in tmp_path.
  • codespell_lib/tests/test_dictionary.py: dictionary format and consistency checks.

Dictionary entries are typo->fix; with more than one fix, end the line with a comma so none is applied automatically:

calulated->calculated
fiel->feel, field, file, phial,

See “Dictionary format” in README.rst for the full rules.

Boundaries

  • Always: run the relevant tests and pre-commit run --files <changed files> before handing work back.
  • Ask first: new command-line options, new dependencies, and changes to CI (.github/), pyproject.toml, or .pre-commit-config.yaml.
  • Never: hand-edit dictionary_en_to_en-OX_AUTOGENERATED.txt (it is generated from dictionary_en-GB_to_en-US.txt by make), delete or weaken a failing test to make it pass, or commit secrets.