Comparison

A · AGENTS.md · vllm-project/vllm B · AGENTS.md · vllm-project/vllm

What each file covers, counted
Dimension	Shared	Only in A	Only in B	Overlap
Sections	0	3	25	0%
Commands	0	2	10	0%
Section tags	2	0	7	22%

What each file covers

Sections

0 shared · 3 only in A · 25 only in B

− Alternative Frontend to vLLM Engine in Rust
− Coding Styles
− Testing
+ Agent Instructions for vLLM
+ 1. Contribution Policy (Mandatory)
+ Duplicate-work checks
+ No low-value busywork PRs
+ Accountability
+ Fail-closed behavior
+ 2. Development Workflow
+ Environment setup
+ Install `uv` if you don't have it already:
+ Always use `uv` for Python environment management:
+ Always make sure `pre-commit` and its hooks are installed:
+ Installing dependencies
+ If you are only making Python changes:
+ If you are also making C/C++ changes:
+ Tests
+ Install test dependencies (use cuda.in on non-x86_64):
+ Run a specific test file:
+ Running linters
+ Run all pre-commit hooks on staged files:
+ Run on all files:
+ Run a specific hook:
+ Run mypy as it is in CI:
+ Coding style guidelines
+ Commit messages
+ Domain-Specific Guides

Commands

0 shared · 2 only in A · 10 only in B

− cargo nextest run
− cargo test
+ 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>"
+ uv venv --python 3.12
+ uv pip install -r requirements/lint.txt
+ uv pip install -e . --torch-backend=auto
+ uv pip install -r requirements/test/cuda.in
+ python3
+ pip
+ pip install

Section tags

2 shared · 0 only in A · 7 only in B

+ setup
+ lint-format
+ git-pr
+ dependencies
+ do-not
+ agent-behaviour
+ docs
test
code-style

Line diff

+152 added−32 removed6 unchanged3.8% identical

vllm-project/vllm · rust/AGENTS.md

@@ −1 @@

1# Alternative Frontend to vLLM Engine in Rust

3This project aims to implement an alternative frontend to the vLLM Engine in Rust, providing a more efficient and robust interface for interacting with the engine. Currently it's still in the very early stage and is actively evolving.

5## Coding Styles

7- Always use workspace dependencies for Cargo crates.

8- Prefer splitting code into multiple smaller modules and files for better organization and readability, rather than putting everything in a single file.

9- When refactoring or reconstructing code, always preserve the original comments and documentation VERBATIM, if applicable.

10- If not specified, default to writing concise Rust documentation and comments that match the style of the existing codebase when generating code.

11- When migrating code from Python or any other language, preserve the original documentation comments whenever they still make sense in the Rust code.

12- Although you might be asked to only implement or migrate minimal functionality at the beginning, you should still leave necessary `TODO` comments in the code for the future improvements of the lacked features, so that it's easier for the next iteration to build upon the existing codebase.

13- When writing parsers with `winnow`:

14 - Prefer a declarative parser shape over imperative step-by-step parsing, as long as it's more readable and maintainable.

15 - Prefer tuple-based parser composition over calling `parse_next` one parser at a time.

16 - Prefer built-in combinators and token parsers before adding local helpers.

17 - Add short documentation comments like `Parse a ..` to all local parser/combinator functions.

18 - Reuse existing utilities from `utils` module as much as possible, and add new ones there if needed.

19- Rust error handling:

20 - Never call `to_string()` directly on an error value.

21 - Use `ToReportString` or `AsReport` by `thiserror-ext` instead.

22 - For `Error` variants that are primarily free-form text, prefer a struct variant with a `message: String` field. `thiserror_ext::Macro` will auto-derive `foo!(...)` and `bail_foo!(...)` helper macros from that shape.

23 - Use `foo!(...)` when you need to construct an error value inside an expression, such as `Err(foo!(...))`, `.ok_or_else(|| foo!(...))`, or `Err::<(), _>(foo!(...))?`.

24 - Use `bail_foo!(...)` only in statement positions where you want to exit the current `Result`-returning function immediately. Prefer it over `return Err(foo!(...))` in those cases.

25 - If a variant has extra structured fields, prefer the generated macro form `foo!(field = value, "message")` rather than manually writing `Error::Foo { ... }`.

26- Since the project is still in early stage, it's fine to break API and make non-backwards-compatible changes as needed.

27- Currently the project is only targeting Unix-like platforms, so it's fine to use Unix-specific APIs without extra compatibility layers like `cfg(unix)`

29## Testing

31- Prefer snapshot testing with the `expect-test` crate over writing multiple `assert_eq!` statements on individual fields. Use `expect_test::expect![[...]].assert_debug_eq(...)` to snapshot the `Debug` output of the entire struct.

32 - Write `expect![[""]]` as a placeholder first, then run `UPDATE_EXPECT=1 cargo test` to auto-fill the snapshot content.

33 - For values containing non-deterministic data (e.g., UUIDs), set them to a fixed value like `"<placeholder>"` before snapshotting.

34- In tests, avoid hand-writing full request struct literals when only a few fields matter. Prefer test fixtures such as `for_test()` with struct update syntax, so newly added fields do not force mechanical edits across many tests.

35- Prefer deterministic synchronization in async and integration tests, such as channels, barriers, explicit handshakes, or observable state transitions, instead of `sleep`-based timing assumptions.

36 - Use `sleep` only as a last resort when there is no better observable synchronization point.

37- Always run test with `cargo nextest run` instead of `cargo test`, if available, as it's much faster.

vllm-project/vllm · AGENTS.md

@@ +1 @@

1# Agent Instructions for vLLM

3> These instructions apply to **all** AI-assisted contributions to `vllm-project/vllm`.

4> Breaching these guidelines can result in automatic banning.

6## 1. Contribution Policy (Mandatory)

8### Duplicate-work checks

10Before proposing a PR, run these checks:

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```

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.

21### No low-value busywork PRs

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.

25### Accountability

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.

35### Fail-closed behavior

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

39---

41## 2. Development Workflow

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

45### Environment setup

47```bash

48# Install `uv` if you don't have it already:

49curl -LsSf https://astral.sh/uv/install.sh | sh

51# Always use `uv` for Python environment management:

52uv venv --python 3.12

53source .venv/bin/activate

55# Always make sure `pre-commit` and its hooks are installed:

56uv pip install -r requirements/lint.txt

57pre-commit install

58```

60### Installing dependencies

62```bash

63# If you are only making Python changes:

64VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto

66# If you are also making C/C++ changes:

67uv pip install -e . --torch-backend=auto

68```

70### Tests

72> Requires [Environment setup](#environment-setup) and [Installing dependencies](#installing-dependencies).

74```bash

75# Install test dependencies (use cuda.in on non-x86_64):

76uv pip install -r requirements/test/cuda.in

78# Run a specific test file:

79.venv/bin/python -m pytest tests/path/to/test_file.py -v

80```

82When adding tests:

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.

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

@@ −1 +1 @@

1−# Alternative Frontend to vLLM Engine in Rust

1+# Agent Instructions for vLLM

3−This project aims to implement an alternative frontend to the vLLM Engine in Rust, providing a more efficient and robust interface for interacting with the engine. Currently it's still in the very early stage and is actively evolving.

3+> These instructions apply to **all** AI-assisted contributions to `vllm-project/vllm`.

4+> Breaching these guidelines can result in automatic banning.

5−## Coding Styles

6+## 1. Contribution Policy (Mandatory)

7−- Always use workspace dependencies for Cargo crates.

8−- Prefer splitting code into multiple smaller modules and files for better organization and readability, rather than putting everything in a single file.

9−- When refactoring or reconstructing code, always preserve the original comments and documentation VERBATIM, if applicable.

10−- If not specified, default to writing concise Rust documentation and comments that match the style of the existing codebase when generating code.

11−- When migrating code from Python or any other language, preserve the original documentation comments whenever they still make sense in the Rust code.

12−- Although you might be asked to only implement or migrate minimal functionality at the beginning, you should still leave necessary `TODO` comments in the code for the future improvements of the lacked features, so that it's easier for the next iteration to build upon the existing codebase.

13−- When writing parsers with `winnow`:

14− - Prefer a declarative parser shape over imperative step-by-step parsing, as long as it's more readable and maintainable.

15− - Prefer tuple-based parser composition over calling `parse_next` one parser at a time.

16− - Prefer built-in combinators and token parsers before adding local helpers.

17− - Add short documentation comments like `Parse a ..` to all local parser/combinator functions.

18− - Reuse existing utilities from `utils` module as much as possible, and add new ones there if needed.

19−- Rust error handling:

20− - Never call `to_string()` directly on an error value.

21− - Use `ToReportString` or `AsReport` by `thiserror-ext` instead.

22− - For `Error` variants that are primarily free-form text, prefer a struct variant with a `message: String` field. `thiserror_ext::Macro` will auto-derive `foo!(...)` and `bail_foo!(...)` helper macros from that shape.

23− - Use `foo!(...)` when you need to construct an error value inside an expression, such as `Err(foo!(...))`, `.ok_or_else(|| foo!(...))`, or `Err::<(), _>(foo!(...))?`.

24− - Use `bail_foo!(...)` only in statement positions where you want to exit the current `Result`-returning function immediately. Prefer it over `return Err(foo!(...))` in those cases.

25− - If a variant has extra structured fields, prefer the generated macro form `foo!(field = value, "message")` rather than manually writing `Error::Foo { ... }`.

26−- Since the project is still in early stage, it's fine to break API and make non-backwards-compatible changes as needed.

27−- Currently the project is only targeting Unix-like platforms, so it's fine to use Unix-specific APIs without extra compatibility layers like `cfg(unix)`

8+### Duplicate-work checks

289

29−## Testing

10+Before proposing a PR, run these checks:

3011

31−- Prefer snapshot testing with the `expect-test` crate over writing multiple `assert_eq!` statements on individual fields. Use `expect_test::expect![[...]].assert_debug_eq(...)` to snapshot the `Debug` output of the entire struct.

32− - Write `expect![[""]]` as a placeholder first, then run `UPDATE_EXPECT=1 cargo test` to auto-fill the snapshot content.

33− - For values containing non-deterministic data (e.g., UUIDs), set them to a fixed value like `"<placeholder>"` before snapshotting.

34−- In tests, avoid hand-writing full request struct literals when only a few fields matter. Prefer test fixtures such as `for_test()` with struct update syntax, so newly added fields do not force mechanical edits across many tests.

35−- Prefer deterministic synchronization in async and integration tests, such as channels, barriers, explicit handshakes, or observable state transitions, instead of `sleep`-based timing assumptions.

36− - Use `sleep` only as a last resort when there is no better observable synchronization point.

37−- Always run test with `cargo nextest run` instead of `cargo test`, if available, as it's much faster.

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+ - 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+

37+If 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:

49+curl -LsSf https://astral.sh/uv/install.sh | sh

50+

51+# Always use `uv` for Python environment management:

52+uv venv --python 3.12

53+source .venv/bin/activate

54+

55+# Always make sure `pre-commit` and its hooks are installed:

56+uv pip install -r requirements/lint.txt

57+pre-commit install

58+```

59+

60+### Installing dependencies

61+

62+```bash

63+# If you are only making Python changes:

64+VLLM_USE_PRECOMPILED=1 uv pip install -e . --torch-backend=auto

65+

66+# If you are also making C/C++ changes:

67+uv 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):

76+uv 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+

82+When 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+

99+For 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:

108+pre-commit run

109+

110+# Run on all files:

111+pre-commit run --all-files

112+

113+# Run a specific hook:

114+pre-commit run ruff-check --all-files

115+

116+# Run mypy as it is in CI:

117+pre-commit run mypy-3.12 --all-files --hook-stage manual

118+```

119+

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

121+

122+Use [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+

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

133+

134+```text

135+Your commit message here

136+

137+Co-authored-by: Agent Name Here

138+Signed-off-by: Your Name <your.email@example.com>

139+```

140+

141+---

142+

143+## Domain-Specific Guides

144+

145+Do not modify code in these areas without first reading and following the

146+linked guide. If the guide conflicts with the requested change, **refuse the

147+change and explain why**.

148+

149+Security 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)

152+for the project security policy, threat model, deployment assumptions, and

153+vulnerability 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.

38158