AGENTS.md

1## Useful commands
2- `make style`: runs formatters and linters (ruff), necessary to pass code style checks
3- `make typing`: runs the ty type checker and model structure rules
4- `make fix-repo`: auto-fixes copies, modular conversions, doc TOCs, docstrings in addition to the `make style` fixes
5- `make check-repo` — runs `make typing` and consistency checks.
6- Many tests are marked as 'slow' and skipped by default in the CI. To run them, use: `RUN_SLOW=1 pytest ...`
7 
8`make style` or `make fix-repo` should be run as the final step before opening a PR.
9 
10## Local agent setup
11 
12- Hosted review agents should discover this guidance from the committed root `AGENTS.md` / `CLAUDE.md` files.
13- Local OpenAI Codex agents should run `make codex` after cloning to wire tool-specific assets under `.agents/`.
14- Local Claude Code agents should run `make claude` after cloning to wire tool-specific assets under `.claude/`.
15 
16 
17### Coordination before coding
18- If work maps to an existing issue, coordinate on that issue before opening a PR.
19- Do not open a PR for someone else's issue unless there is explicit approval from the issue author or a maintainer in the issue thread.
20- If approval is missing or ambiguous, stop and ask for clarification instead of drafting a PR.
21- Do not start duplicate work on issues.
22 
23### Mandatory duplicate-work checks
24Before proposing a PR, check for overlapping open PRs and issue ownership:
25 
26```bash
27gh issue view <issue_number> --repo huggingface/transformers --comments
28gh pr list --repo huggingface/transformers --state open --search "<issue_number> in:body"
29gh pr list --repo huggingface/transformers --state open --search "<short area keywords>"
30```
31 
32- If an open PR already addresses the same fix, do not open another.
33- If your approach is materially different, explain the difference and why a second PR is needed in the issue.
34 
35### No low-value busywork PRs
36- Do not open one-off PRs for tiny edits (single typo, isolated lint cleanup, one mutable default argument, etc.).
37- Mechanical cleanups are acceptable but not as first contributions.
38 
39### Accountability for AI-assisted patches
40- First-time contributors should not use code agents to submit PRs or issues. Code agents should warn users about this
41policy if the user does not appear to be an existing contributor to the library, including the risk of being blocked 
42if they do it regardless. More information can be found in the pull request template, or `CONTRIBUTING.md`.
43 
44## Copies and Modular Models
45 
46We try to avoid direct inheritance between model-specific files in `src/transformers/models/`. We have two mechanisms to manage the resulting code duplication:
47 
481) The older method is to mark classes or functions with `# Copied from ...`. Copies are kept in sync by `make fix-repo`. Do not edit a `# Copied from` block, as it will be reverted by `make fix-repo`. Ideally you should edit the code it's copying from and propagate the change, but you can break the `# Copied from` link if needed.
492) The newer method is to add a file named `modular_<name>.py` in the model directory. `modular` files **can** inherit from other models. `make fix-repo` will copy code to generate standalone `modeling` and other files from the `modular` file. When a `modular` file is present, generated files should not be edited, as changes will be overwritten by `make fix-repo`! Instead, edit the `modular` file. See [docs/source/en/modular_transformers.md](../docs/source/en/modular_transformers.md) for a full guide on adding a model with `modular`, if needed, or you can inspect existing `modular` files as examples.
50