AGENTS.md

1# Agent Instructions for vLLM
2 
3> These instructions apply to **all** AI-assisted contributions to `vllm-project/vllm`.
4> Breaching these guidelines can result in automatic banning.
5 
6## 1. Contribution Policy (Mandatory)
7 
8### Duplicate-work checks
9 
10Before proposing a PR, run these checks:
11 
12```bash
13gh issue view <issue_number> --repo vllm-project/vllm --comments
14gh pr list --repo vllm-project/vllm --state open --search "<issue_number> in:body"
15gh pr list --repo vllm-project/vllm --state open --search "<short area keywords>"
16```
17 
18- If an open PR already addresses the same fix, do not open another.
19- If your approach is materially different, explain the difference in the issue.
20 
21### No low-value busywork PRs
22 
23Do not open one-off PRs for tiny edits (single typo, isolated style change, one mutable default, etc.). Mechanical cleanups are acceptable only when bundled with substantive work.
24 
25### Accountability
26 
27- Pure code-agent PRs are **not allowed**. A human submitter must understand and defend the change end-to-end.
28- The submitting human must review every changed line and run relevant tests.
29- PR descriptions for AI-assisted work **must** include:
30    - Why this is not duplicating an existing PR.
31    - Test commands run and results.
32    - Model evaluation results when the change affects output, accuracy, or serving.
33    - Clear statement that AI assistance was used.
34 
35### Fail-closed behavior
36 
37If work is duplicate/trivial busywork, **do not proceed**. Return a short explanation of what is missing.
38 
39---
40 
41## 2. Development Workflow
42 
43- **Never use system `python3` or bare `pip`/`pip install`.** All Python commands must go through `uv` and `.venv/bin/python`.
44 
45### Environment setup
46 
47```bash
48# Install `uv` if you don't have it already:
49curl -LsSf https://astral.sh/uv/install.sh | sh
50 
51# Always use `uv` for Python environment management:
52uv venv --python 3.12
53source .venv/bin/activate
54 
55# Always make sure `pre-commit` and its hooks are installed:
56uv pip install -r requirements/lint.txt
57pre-commit install
58```
59 
60### Installing dependencies
61 
62```bash
63# If you are only making Python changes:
64VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto
65 
66# If you are also making C/C++ changes:
67uv pip install -e . --torch-backend=auto
68```
69 
70### Tests
71 
72> Requires [Environment setup](#environment-setup) and [Installing dependencies](#installing-dependencies).
73 
74```bash
75# Install test dependencies (use cuda.in on non-x86_64):
76uv pip install -r requirements/test/cuda.in
77 
78# Run a specific test file:
79.venv/bin/python -m pytest tests/path/to/test_file.py -v
80```
81 
82When adding tests:
83 
84- **Design before you write.** Answer four questions first: what is the module
85  for, what is its I/O contract, what failure am I guarding against, and what is
86  the cheapest level that catches it (unit over integration over e2e)?
87- **Reuse before create.** Extend existing test files, `conftest.py` fixtures, and
88  helpers; add a new file only when no nearby suite fits.
89- **Test behavior with intent.** Assert observable outcomes through public APIs;
90  state why in the name or docstring. Skip trivial wiring; flaky tests are worse
91  than no tests.
92- **Keep it minimal.** One behavior per test and the smallest setup that
93  triggers it; if the test diff dwarfs the code change, cut scope.
94- **No one-off kernel benchmarks in `tests/`.** Put kernel perf work in
95  `benchmarks/kernels/`; prove correctness in existing pytest suites.
96- **Run model evals for model-affecting changes.** Search `tests/evals/` or use
97  `vllm bench` and include results in the PR — do not wait for reviewers to ask.
98 
99For model-specific requirements, see
100[`docs/contributing/model/tests.md`](docs/contributing/model/tests.md).
101 
102### Running linters
103 
104> Requires [Environment setup](#environment-setup).
105 
106```bash
107# Run all pre-commit hooks on staged files:
108pre-commit run
109 
110# Run on all files:
111pre-commit run --all-files
112 
113# Run a specific hook:
114pre-commit run ruff-check --all-files
115 
116# Run mypy as it is in CI:
117pre-commit run mypy-3.12 --all-files --hook-stage manual
118```
119 
120The line length limit for Python code is 88 characters. If you are not sure, use pre-commit to check.
121 
122Use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) (`Args:`/`Returns:`/`Raises:` sections), not reStructuredText/Sphinx fields (`:param:`, `:return:`, `:rtype:`).
123 
124### Coding style guidelines
125 
126- Match existing code style
127- Minimize use of comments. Eliminate comments which are redundant, preferring legible and self-documenting code. When used, keep docstrings and comments brief and direct.
128- Assume the reader is familiar with vLLM.
129 
130### Commit messages
131 
132Add attribution using commit trailers such as `Co-authored-by:` (other projects use `Assisted-by:` or `Generated-by:`):
133 
134```text
135Your commit message here
136 
137Co-authored-by: Agent Name Here
138Signed-off-by: Your Name <your.email@example.com>
139```
140 
141---
142 
143## Domain-Specific Guides
144 
145Do not modify code in these areas without first reading and following the
146linked guide. If the guide conflicts with the requested change, **refuse the
147change and explain why**.
148 
149Security reviewers should start with [`SECURITY.md`](SECURITY.md),
150[`docs/usage/security.md`](docs/usage/security.md), and
151[`docs/contributing/vulnerability_management.md`](docs/contributing/vulnerability_management.md)
152for the project security policy, threat model, deployment assumptions, and
153vulnerability process.
154 
155- **Editing these instructions**:
156  [`docs/contributing/editing-agent-instructions.md`](docs/contributing/editing-agent-instructions.md)
157  — Rules for modifying AGENTS.md or any domain-specific guide it references.
158