# PR #5846 完整报告

- 仓库：`verl-project/verl`
- 标题：[misc] feat: add agent instructions, skills & improve CI for easier tests
- 合并时间：2026-04-01 22:09
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/5846

---

## 执行摘要
本 PR 添加了一个框架无关的 AI 代理指令系统，包括项目范围的规则文档和共享技能，同时将健全性检查从 CI 迁移到 pre-commit，形成代理辅助开发的闭环流程。该变更旨在标准化 AI 代理贡献，提高开发效率，但引入了新的文档维护负担和 CI 配置风险。

## 功能与动机
为什么做这个变更？PR body 明确指出：“Add a framework-agnostic agent instruction system for AI coding agents (Claude Code, Codex, etc.), and consolidate sanity checks into pre-commit to form an initial closed loop for agent-assisted development.” 动机是支持 AI 代理参与项目贡献，通过提供标准化指令和本地验证，减少重复工作并确保代码质量，适应现代 AI 辅助开发趋势。

## 实现拆解
实现主要分为两个部分：
1. **代理指令系统**：
 - 添加 `AGENTS.md`：定义项目范围的贡献政策、环境设置和提交规范，引用现有文件如 PR 模板和 CI 脚本。
 - 创建 `.agent/skills/` 目录：包含共享技能如 `pr.md` 和 `issue.md`，通过符号链接供 `.claude/` 和 `.codex/` 使用。
 - 添加 `CLAUDE.md` 作为 Claude Code 入口点，直接链接到 `AGENTS.md`。
 - 更新相关文档：`CONTRIBUTING.md` 添加 AI 辅助贡献部分，`docs/contributing/editing-agent-instructions.md` 提供维护指南。
2. **CI 改进**：
 - 修改 `.pre-commit-config.yaml`：整合多个健全性检查钩子（如 `check-docs-time-info`、`check-device-api-usage`），合并到单个 `repo: local` 块中。
 - 更新 `.github/workflows/sanity.yml`：移除重复步骤，仅保留需要完整安装的检查，简化 CI 流程。
 - 修改 `tests/special_sanity/check_license.py`：使用 `git ls-files` 来尊重 `.gitignore`，避免检查未被跟踪的文件。
 - 在 `cpu_unit_tests.yml`、`gpu_unit_tests.yml` 和 `npu_unit_tests.yml` 中排除 `tests/special_sanity/` 路径，防止运行时测试干扰。

## 评论区精华
review 讨论中，gemini-code-assist[bot] 指出了两个关键问题：
> “The repository organization is specified as `verl-project`, but the project is currently hosted under `volcengine/verl`... This discrepancy should be corrected.”
> “For Claude Code, the `CLAUDE.md` file serves as the primary system prompt. Simply providing a link to `AGENTS.md` may not be sufficient... It is recommended to use a more explicit instruction.”
这些建议被采纳，修复了路径错误并提高了指令明确性，确保代理能正确执行命令和遵守规则，避免潜在的错误贡献。

## 风险与影响
**技术风险**：
- 代理指令可能不完整或过时，导致代理行为不一致，需定期维护 `AGENTS.md` 和相关文档。
- CI 更改可能引入回归，例如 `.pre-commit-config.yaml` 中添加的新钩子需要验证兼容性，或测试过滤错误导致遗漏检查，具体体现在路径排除逻辑上。
- `check_license.py` 的更改可能遗漏未被 git 跟踪的文件，影响许可证检查的完整性，需要测试覆盖。

**影响分析**：
- 对团队：开发流程更标准化，代理贡献更可控，提高效率；但对代理和贡献者增加了学习曲线，需熟悉新指令和 pre-commit 钩子。
- 对系统：pre-commit 验证更全面，可能增加本地运行时间；CI 流程简化，减少重复检查，加快反馈循环。
- 对用户：无直接影响，但长期看代码质量提升，因代理贡献更规范。

## 关联脉络
从历史 PR 看，近期有多个文档更新 PR（如 #5847、#5850），表明项目在加强文档维护。本 PR 与之相关，共同推动项目基础设施的完善。此外，它引入了代理辅助开发框架，可能为未来更多 AI 驱动贡献铺平道路，如后续 issue #5852 和 #5853 所示。结合同仓库近期 PR 趋势，项目正从核心功能开发（如 megatron、rollout）扩展到工具和流程优化，反映团队对开发效率的重视。