A high-throughput and memory-efficient inference and serving engine for LLMs
Mirrored from https://github.com/tduncan-lum/Nvidia-Optimization-Stack---VLLM.git
Synced Nov 6, 19:15 UTC
Add `AGENTS.md` (#36877)
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com> Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Harry Mellor committed
Mar 12, 2026 at 17:20 UTC
e39257a552d18ae9abb6ba1bbe65865d385ea764
6 files changed
+128
-4
.gitignore
-2
@@ -189,11 +189,9 @@ cython_debug/
189
.vscode/
190
191
# Claude
192
-CLAUDE.md
192
.claude/
193
194
# Codex
196
-AGENTS.md
195
.codex/
196
197
# Cursor
.pre-commit-config.yaml
+1
@@ -30,6 +30,7 @@ repos:
30
- id: markdownlint-cli2
31
language_version: lts
32
args: [--fix]
33
+ exclude: ^CLAUDE\.md$
34
- repo: https://github.com/rhysd/actionlint
35
rev: v1.7.7
36
hooks:
AGENTS.md
new
+114
@@ -0,0 +1,114 @@
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
+
10
+Before proposing a PR, run these checks:
11
+
12
+```bash
13
+gh issue view <issue_number> --repo vllm-project/vllm --comments
14
+gh pr list --repo vllm-project/vllm --state open --search "<issue_number> in:body"
15
+gh 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
+
23
+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.
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
+ - Clear statement that AI assistance was used.
33
+
34
+### Fail-closed behavior
35
+
36
+If work is duplicate/trivial busywork, **do not proceed**. Return a short explanation of what is missing.
37
+
38
+---
39
+
40
+## 2. Development Workflow
41
+
42
+### Environment setup
43
+
44
+```bash
45
+# Install `uv` if you don't have it already:
46
+curl -LsSf https://astral.sh/uv/install.sh | sh
47
+
48
+# Always use `uv` for Python environment management:
49
+uv venv
50
+source .venv/bin/activate
51
+
52
+# Always make sure `pre-commit` and its hooks are installed:
53
+uv pip install pre-commit
54
+pre-commit install
55
+```
56
+
57
+### Installing dependencies
58
+
59
+```bash
60
+# If you are only making Python changes:
61
+VLLM_USE_PRECOMPILED=1 uv pip install -e .
62
+
63
+# If you are also making C/C++ changes:
64
+uv pip install -e .
65
+```
66
+
67
+### Running tests
68
+
69
+Tests require extra dependencies.
70
+All versions for test dependencies should be read from `requirements/test.txt`
71
+
72
+```bash
73
+# Install bare minimum test dependencies:
74
+uv pip install pytest==<requirements/test.txt version>
75
+uv pip install tblib==<requirements/test.txt version>
76
+
77
+# Install additional required dependencies from `requirements/test.txt` as needed:
78
+uv pip install <requirements/test.txt dependency>==<requirements/test.txt version>
79
+
80
+# Run specific test from specific test file
81
+pytest tests/path/to/test.py -v -s -k test_name
82
+
83
+# Run all tests in directory
84
+pytest tests/path/to/dir -v -s
85
+```
86
+
87
+### Running linters
88
+
89
+```bash
90
+# Run all pre-commit hooks on staged files:
91
+pre-commit run
92
+
93
+# Run on all files:
94
+pre-commit run --all-files
95
+
96
+# Run a specific hook:
97
+pre-commit run ruff-check --all-files
98
+
99
+# Run mypy as it is in CI:
100
+pre-commit run mypy-3.10 --all-files --hook-stage manual
101
+```
102
+
103
+### Commit messages
104
+
105
+Add attribution using commit trailers such as `Co-authored-by:` (other projects use `Assisted-by:` or `Generated-by:`). For example:
106
+
107
+```text
108
+Your commit message here
109
+
110
+Co-authored-by: GitHub Copilot
111
+Co-authored-by: Claude
112
+Co-authored-by: gemini-code-assist
113
+Signed-off-by: Your Name <your.email@example.com>
114
+```
CLAUDE.md
new
+1
@@ -0,0 +1 @@
1
+@AGENTS.md
docs/contributing/README.md
+5
@@ -189,6 +189,11 @@ Using `-s` with `git commit` will automatically add this header.
189
190
### AI Assisted Contributions
191
192
+Before making an AI assisted contribution, you must:
193
+
194
+1. **Be involved**: Do not submit "pure agent" PRs. The human submitter is responsible for reviewing all changed lines, validating behavior end-to-end, and running relevant tests.
195
+2. **Ensure significance**: Avoid one-off "busywork" PRs (single typo, isolated style cleanup, one mutable default fix, etc.). Bundle mechanical cleanups into a clear, systematic scope.
196
+
197
When AI tools provide non-trivial assistance in generating or modifying code, you must:
198
199
1. **Review thoroughly**: You remain responsible for all code you submit. Review and understand AI-generated code with the same care as code you write manually.
docs/governance/process.md
+7
-2
@@ -139,9 +139,14 @@ In case where CI didn't pass due to the failure is not related to the PR, the PR
139
140
AI tools can accelerate development, but contributors remain fully responsible for all code they submit. Like the Developer Certificate of Origin, this policy centers on accountability: contributors must believe they have the right to submit their contribution under vLLM's open source license, regardless of how the code was created.
141
142
-All AI-assisted contributions must meet the same quality, testing, and review standards as any other code. Contributors must review and understand AI-generated code before submission—just make sure it is good code.
142
+All AI-assisted contributions must meet the same quality, testing, and review standards as any other code. Contributors must review and understand AI-generated code before submission—just make sure it is good code:
143
144
-Attribution preserves legal clarity and community trust. Contributors must disclose AI assistance in pull requests and mark commits with appropriate trailers (e.g. `Co-authored-by:`).
144
+- Do not submit "pure agent" PRs. The human submitter is responsible for reviewing all changed lines, validating behavior end-to-end, and running relevant tests.
145
+- Attribution preserves legal clarity and community trust. Contributors must disclose AI assistance in pull requests and mark commits with appropriate trailers (e.g. `Co-authored-by:`).
146
+- Avoid one-off "busywork" PRs (single typo, isolated style cleanup, one mutable default fix, etc.). Bundle mechanical cleanups into a clear, systematic scope.
147
+
148
+!!! warning
149
+ These topics are outlined for agents in [AGENTS.md](../../AGENTS.md) with instructions for how to autonomously implement them.
150
151
### Slack
152