执行摘要

本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）扩展到工具和流程优化，反映团队对开发效率的重视。