# PR #47784 完整报告

- 仓库：`vllm-project/vllm`
- 标题：AGENTS MD: Add suggestion on how to incorporate tests
- 合并时间：2026-07-07 23:16
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/47784

---

# 执行摘要

- 一句话：AGENTS.md 新增 AI 代理测试编写指南
- 推荐动作：建议阅读此 PR，它展示了如何有效设计 AI 代理指导文档，平衡详细性和简洁性，并体现了如何通过 review 迭代优化内容。

# 功能与动机

作者观察到越来越多的 PR 由 AI 代理创建测试文件，因此需要在 AGENTS.md 中提供明确的测试编写规范，确保测试的一致性和有效性。PR 描述：“I have seeing more PRs with newly created test files by agents.”

# 实现拆解

1. 重新组织 Tests 小节：将原有的“Running tests”和新增的“Adding tests”合并为统一的“Tests”部分，保留基本的运行测试命令，并添加新的测试指导原则。
2. 添加六条测试原则：包括设计先行（Design before you write）、复用现有（Reuse before create）、意图测试（Test behavior with intent）、保持最小（Keep it minimal）、禁止单次内核基准（No one-off kernel benchmarks in tests/）以及要求模型评估（Run model evals for model-affecting changes）。每条原则都附有简短说明。
3. 简化编码风格指南：将原有的四条规则压缩为更精炼的表述，移除冗余说明如“Code should be self-documenting”，改为“Match existing code style”和“Minimize use of comments”等。
4. 根据 review 反馈迭代：采纳了 AndreasKaratzas 的“Design before you write”和“Keep it minimal”两条核心原则，摒弃其他扩展建议以保持文档简短；采纳了 benchislett 关于编码风格简化的建议；同时回应 chatgpt-codex-connector 关于需要偏移新增内容的提醒，通过精简编码风格部分实现了长度平衡。
5. 调整 Commit 示例部分：删除了原有的 commit 示例块，进一步压缩文件长度。

关键文件：
- `AGENTS.md`（模块 代理指南；类别 docs；类型 documentation）: 这是本 PR 唯一修改的文件，核心变更为添加 AI 代理测试编写指导，并精简编码风格部分。

关键符号：未识别


# 评论区精华

主要讨论点如下：
- chatgpt-codex-connector 指出新增测试部分需要偏移压缩，最终通过精简编码风格实现。
- AndreasKaratzas 提出多项测试原则建议，simon-mo 要求保持简短，最终只保留“Design before you write”和“Keep it minimal”两条。
- benchislett 建议简化编码风格指南，被采纳。

- 新增测试内容需要偏移压缩 (design): 通过精简编码风格指南和删除 commit 示例实现偏移。
- 测试原则的选择与精简 (design): 采纳两条核心原则，其他放弃。
- 编码风格指南简化 (style): 采纳简化版本。

# 风险与影响

- 风险：纯文档变更，不影响代码逻辑，风险极低。但需确保指导原则措辞清晰，避免 AI 代理误解。
- 影响：影响范围限于阅读 AGENTS.md 的 AI 代理和人类贡献者。影响程度中等，规范了测试编写实践，有望提升测试质量和一致性，减少审查工作量。
- 风险标记：暂无

# 关联脉络

- 暂无明显关联 PR