AGENTS.md

# 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

```bash
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:

```text
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.