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

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 .

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

Running tests

Tests require extra dependencies. All versions for test dependencies should be read from requirements/test.txt

# Install bare minimum test dependencies:
uv pip install pytest pytest-asyncio tblib

# Install additional test dependencies as needed, or install them all as follows:
uv pip install -r requirements/test.txt

# Run specific test from specific test file
pytest tests/path/to/test.py -v -s -k test_name

# Run all tests in directory
pytest tests/path/to/dir -v -s

Running linters

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