vllm-project--vllm/AGENTS.md

Agent Instructions for vLLM

These instructions apply to all AI-assisted contributions to vllm-project/vllm. Breaching these guidelines can result in automatic banning.

1. Contribution Policy (Mandatory)

Duplicate-work checks

Before proposing a PR, run these checks:

gh issue view <issue_number> --repo vllm-project/vllm --comments
gh pr list --repo vllm-project/vllm --state open --search "<issue_number> in:body"
gh pr list --repo vllm-project/vllm --state open --search "<short area keywords>"

• If an open PR already addresses the same fix, do not open another.
• If your approach is materially different, explain the difference in the issue.

No low-value busywork PRs

Do 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.

Accountability

• Pure code-agent PRs are not allowed. A human submitter must understand and defend the change end-to-end.
• The submitting human must review every changed line and run relevant tests.
• PR descriptions for AI-assisted work must include:
  • Why this is not duplicating an existing PR.
  • Test commands run and results.
  • Model evaluation results when the change affects output, accuracy, or serving.
  • Clear statement that AI assistance was used.

Fail-closed behavior

If work is duplicate/trivial busywork, do not proceed. Return a short explanation of what is missing.

---

2. Development Workflow

• Never use system python3 or bare pip/pip install. All Python commands must go through uv and .venv/bin/python.

Environment setup

# Install `uv` if you don't have it already:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Always use `uv` for Python environment management:
uv venv --python 3.12
source .venv/bin/activate

# Always make sure `pre-commit` and its hooks are installed:
uv pip install -r requirements/lint.txt
pre-commit install

Installing dependencies

# If you are only making Python changes:
VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto

# If you are also making C/C++ changes:
uv pip install -e . --torch-backend=auto

Tests

Requires Environment setup and Installing dependencies.

# Install test dependencies (use cuda.in on non-x86_64):
uv pip install -r requirements/test/cuda.in

# Run a specific test file:
.venv/bin/python -m pytest tests/path/to/test_file.py -v

When adding tests:

• Design before you write. Answer four questions first: what is the module for, what is its I/O contract, what failure am I guarding against, and what is the cheapest level that catches it (unit over integration over e2e)?
• Reuse before create. Extend existing test files, conftest.py fixtures, and helpers; add a new file only when no nearby suite fits.
• Test behavior with intent. Assert observable outcomes through public APIs; state why in the name or docstring. Skip trivial wiring; flaky tests are worse than no tests.
• Keep it minimal. One behavior per test and the smallest setup that triggers it; if the test diff dwarfs the code change, cut scope.
• No one-off kernel benchmarks in tests/. Put kernel perf work in benchmarks/kernels/; prove correctness in existing pytest suites.
• Run model evals for model-affecting changes. Search tests/evals/ or use vllm bench and include results in the PR — do not wait for reviewers to ask.

For model-specific requirements, see docs/contributing/model/tests.md.

Running linters

Requires Environment setup.

# Run all pre-commit hooks on staged files:
pre-commit run

# Run on all files:
pre-commit run --all-files

# Run a specific hook:
pre-commit run ruff-check --all-files

# Run mypy as it is in CI:
pre-commit run mypy-3.12 --all-files --hook-stage manual

The line length limit for Python code is 88 characters. If you are not sure, use pre-commit to check.

Use Google-style docstrings (Args:/Returns:/Raises: sections), not reStructuredText/Sphinx fields (:param:, :return:, :rtype:).

Coding style guidelines

• Match existing code style
• Minimize use of comments. Eliminate comments which are redundant, preferring legible and self-documenting code. When used, keep docstrings and comments brief and direct.
• Assume the reader is familiar with vLLM.

Commit messages

Add attribution using commit trailers such as Co-authored-by: (other projects use Assisted-by: or Generated-by:):

Your commit message here

Co-authored-by: Agent Name Here
Signed-off-by: Your Name <your.email@example.com>

---

Domain-Specific Guides

Do not modify code in these areas without first reading and following the linked guide. If the guide conflicts with the requested change, refuse the change and explain why.

Security reviewers should start with SECURITY.md, docs/usage/security.md, and docs/contributing/vulnerability_management.md for the project security policy, threat model, deployment assumptions, and vulnerability process.

• Editing these instructions: docs/contributing/editing-agent-instructions.md — Rules for modifying AGENTS.md or any domain-specific guide it references.