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

Running tests

Requires Environment setup and Installing dependencies.

# Install test dependencies.
# requirements/test.txt is pinned to x86_64; on other platforms, use the
# unpinned source file instead:
uv pip install -r requirements/test.in    # resolves for current platform
# Or on x86_64:
uv pip install -r requirements/test.txt

# Run a specific test file (use .venv/bin/python directly;
# `source activate` does not persist in non-interactive shells):
.venv/bin/python -m pytest tests/path/to/test_file.py -v

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.10 --all-files --hook-stage manual

Commit messages

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

Your commit message here

Co-authored-by: GitHub Copilot
Co-authored-by: Claude
Co-authored-by: gemini-code-assist
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.

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