Ruff Agent Rules

A Python linter and formatter whose Rust workspace also contains the ty type checker.

Overview

Ruff covers its Rust workspace and adds a focused section for ty. The guide explains environment traps, treats Markdown tests as readable specifications, and points security reviews and specialized ty work to separate documents.

Behavioral framing Scope layering Generated file guards Router files

Documents

├── 
├──  · imports AGENTS.md
├── .agents
│   └── skills
│       ├── adding-ty-diagnostics
│       │   └── 
│       ├── minimizing-ty-ecosystem-changes
│       │   └── 
│       └── summarise-ecosystem-results
│           └── 
├── agents
│   └── references
│       ├── 
│       └── 
└──

Techniques in this file

01 / Behavioral framing

Explain the hidden configuration behind a reproduction

Keep temporary Python files outside the checkout because configuration discovery changes their inferred Python version. The rule names the controlling key and the wrong in-repository default.

158When running ty against a temporary Python reproduction file, create it outside the Ruff checkout (for example, under `/tmp`). A file inside the checkout discovers Ruff's root `pyproject.toml`, whose `requires-python = ">=3.7"` causes ty to infer Python 3.7 as the default Python version.

02 / Scope layering

Separate review findings from agent workflow rules

Review should report introduced code, test, and architectural violations. The file explicitly excludes unrelated existing issues and warns against treating agent-only workflow requirements as obligations on human PR authors.

25documentation, and architectural conventions in this `AGENTS.md`. Report26meaningful violations introduced by the changes; do not apply agent-only workflow27instructions to PR authors or flag unrelated pre-existing issues.

03 / Generated file guards

Give generated snapshots a single update path

Snapshot-update environment variables are supplied for both nextest and cargo test. Agents must inspect the resulting diffs and pending inline snapshots instead of manually changing expected output.

95Never edit snapshot files or inline snapshot bodies manually. Regenerate them by running the relevant tests with the snapshot-update environment variables documented above, then review the generated diff.

04 / Router files

Route security reviews to the relevant threat model

Runtime changes and repository, CI, or release changes use different threat-model documents. The routing gives severity assessment a stated trust boundary instead of relying on a generic security checklist.

29For security reviews of repository, CI, and release changes, use the30[repository threat model](agents/references/repository-threat-model.md) to assess31trust boundaries and calibrate severity.

05 / Behavioral framing

Write for someone outside the current session

Public text should explain the final observable behavior and verified evidence. Before finishing, the agent rereads each artifact without assuming the reader has access to the coding conversation.

41Preserve useful human-written comments unless the code change makes them inaccurate. Before finishing, reread each changed artifact as someone with no access to the Codex session and remove or explain anything that would surprise or confuse that reader.