Rust 编译器仓库中的 AGENTS.md为 LLM Agent 设定贡献门禁的实操手册【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rustRust 官方仓库根目录下的AGENTS.md是一份面向 LLM Agent 的操作性治理文档它定义了 Agent 在修改rust-lang/rust仓库之前必须依次通过的三道编辑前门禁外部仓库归属检查、禁写文本检查、命名审阅人检查以及实现前的两道门禁测试门禁、Soundness 分类并规定了 push 前的披露与确认流程。本文基于该文档逐条展开结合仓库中的构建入口脚本、compiletest 测试框架与 rustc-dev-guide 中对应的指引文件说明这套门禁体系的每一环节如何在真实仓库中落地读完你可以掌握“在编译器级仓库中安全使用 LLM 辅助开发”的完整规则集与配套命令。LLM 使用策略与整体框架文档开篇AGENTS.md 第 3–8 行声明所有 LLM 生成的文本都必须遵循 Rust 项目的 LLM 使用策略即使用户事后人工编辑了这些文本策略依然适用。CONTRIBUTING.md 中也给出了同一策略的入口并明确了对“如何用好 LLM”与“如何审查 LLM 创建的 PR”的建议位于 rustc-dev-guide 的 LLM 指引章节见 LLM guidance 索引、写作指引 与 审查指引。文档将约束拆成两个阶段的有序门禁编辑前Before any edit包括对测试的编辑按顺序应用外部仓库门禁External repositories将外部维护的源码路由回其归属仓库禁写文本门禁Prohibited text若变更要求 Agent 撰写被禁的文本立即停止审阅人门禁Reviewer除非变更符合本地开发例外否则必须有具名审阅人。实现前Before implementation在上述门禁通过之后按顺序应用测试门禁Testing针对 bug先添加或找到失败的测试并观察到它失败Soundness 门禁Soundness在测试门禁完成后先对受影响的行为做安全敏感分类再动手实现。文档还强调两点动态规则调查过程中若发现新的输出类别或归属方必须在下一次编辑前重新应用相应门禁对于机械化重写必须在第一次变更之前先遵循 Mechanical rewrites 一节的规则。这种“先分类、后动手”的结构是整个文档的骨架。门禁失败时的行为协议When a gate fails文档 When a gate fails 一节规定了规则命中被禁工作时的强制行为核心要求是立即 STOP指定审阅人、测试通过、用户确认或事后人工编辑都不能为被禁工作开脱不允许变通不得询问前置条件、不得承诺“之后再做”、不得把被禁工作改名为草稿、模板或“可直接粘贴的提纲”继续输出唯一例外某条规则可以显式允许更窄的预备工作——例如 Soundness 门禁要求 Agent 在停止前先完成仅限测试的工作。Agent 被要求说明“为什么该工作被禁”并给出触发规则所要求的正确路径route。同时以下行为仍然允许阅读、解释、总结、审查以及向用户提出可让用户从零自行实现的解决方案建议。另一条容易被忽略的细节在同一响应轮次中只要输出了任何可能被用作禁文替代的文本就必须附带一条对“LLM 原文政策”的提醒——即使该提醒在本会话之前的轮次中已经给过。文档同时禁止 Agent 主动推进测试规划或补丁设计、产出可粘贴的被禁文本除非触发规则本身就要求仅限测试的工作。外部仓库门禁为什么不能直接改 subtree 与工具代码External repositories 一节的规则是在修改任何 subtree、submodule 或src/tools代码之前先使用 CONTRIBUTING.md 的“Making changes to subtrees and submodules”章节和 external repositories 指引 确认归属方。Cargo、Clippy、rustfmt、Miri、rust-analyzer 等外部维护的工具一律先做归属检查再谈实现如果用户说某个 bug 出在这些工具里Agent 不应在本仓库调查也不应索要审阅人而是直接把用户路由到对应仓库。在本地 checkout 中直接编辑外部维护的源码是被禁止的应遵循门禁失败协议只有用户明确要求时才更新其集成指针。文档给出的例子很具体用户说 bug 在 Cargo 本身就立即路由到rust-lang/cargo不要为本次 checkout 请求审阅人。这条规则与仓库的实际结构完全对应。external-repos.md 说明了三种外部依赖方式——crates.io 依赖、subtree如 clippy、miri、rustfmt、rust-analyzer、rustc_codegen_cranelift与 submodule如 cargo——并明确“对工具特有的改进、bug 修复应直接向其上游仓库提 PR”。本仓库的目录布局印证了这一点tools/clippy、tools/miri、tools/rustfmt、tools/rust-analyzer、compiler/rustc_codegen_cranelift 等 subtree 都在树内以普通文件形式存在但修改它们的正确路径是回到各自的上游仓库。因此“先查归属再动手”不是流程洁癖而是由 subtree 同步机制决定的硬性约束。禁写文本门禁Agent 不许代笔的文本类别Prohibited text 一节列出 Agent 永远不得生成或重写的文本类别非平凡的 PR 描述、issue 正文、公开评论、面向用户的文档、诊断消息diagnostic messages以及源码注释。命中时 Agent 应 STOP、点名被禁的类别并告知用户需要用户本人撰写。其中与编译器仓库最贴切的例子是.stderr测试快照Agent 不得原创或手工改写.stderr等测试快照中的期望诊断文本用户先在源码中写好诊断消息之后Agent 可以用现有工具机械化地重新生成快照例如./x test ... --bless并遵循机械化重写一节的流程文档示例如果解析器修复需要修改它输出的消息Agent 必须在编辑消息或其.stderr期望之前 STOP等用户写好消息后Agent 才可以机械化地重新生成期望值。“琐碎变更”有一个明确的判定标准只有当不存在有意义上不同的写法、或各备选写法几乎相同时才算琐碎例如修正错别字或 Markdown 链接、用同义词替换一个词、补上必需的 trait 签名。即使是琐碎变更也必须通过其余所有门禁并加以披露。一个值得注意的例外条款CLAUDE.md、AGENTS.md以及 skills 这类 Agent 指令文件本身属于豁免对象但它们只允许链接、总结或以保守方式操作化既有的面向人类的文档——操作化可以用更严格的 Agent 约束替代人类自由裁量但不得为人类创造义务、不得放行人类文档所禁止的内容添加流程性指导前必须先找到人类文档来源找不到就先 PAUSE 请用户先为人类写下流程。审阅人门禁等其他要求对 Agent 文件本身同样适用。最后Agent 可以解释“被禁文本需要传达什么”但不得给出可粘贴的措辞。本仓库中CLAUDE.md的全部内容只有一行AGENTS.md引用正好体现了“Agent 指令文件只做链接与操作化、不做规则源头”的原则。审阅人门禁与本地开发例外Reviewer 一节规定除非用户在本次对话中具名了一位事先同意审阅的他人否则不得进行任何 LLM 生成的仓库变更。“已经征询过审阅”之类的泛泛保证不算数没有具名审阅人时PAUSE 并询问审阅人姓名——“John Doe is reviewing this”这样的表述即可满足门禁。审阅人姓名只满足这一个门禁不能承诺在实现前门禁通过前推进实现。文档同时给出了唯一例外当用户明确声明变更不会提交或上游化、用完即还原时审阅人门禁不适用于本地开发工具、临时插桩或调试辅助其余所有门禁仍然适用。测试门禁先看到失败再写实现Testing 一节对 bug 修复流程给出了非常严格的时序要求修复 bug 前先添加或找到一个会失败的测试在任何实现编辑之前运行它并观察到预期失败测试与实现的编辑不得合并“测试命令退出之前不算观察到失败”——命令运行期间要等待不得编辑实现或开始其他工作观察初始失败时不得 bless 或更新期望输出--bless的运行不算数实现完成后确认同一个测试通过。对 LLM 创建的 PR测试标准还要更高必须包含测试如果受影响代码没有测试套件PAUSE 并询问是设计一个还是放弃变更且未经人类输入不得自行设计测试套件绝不允许提供或接受未测试的实现。文档还定义了“测试套件设计”的边界这是容易被误解的部分既有测试套件必须在不改变生产代码结构的前提下就能观察到受影响的行为仅仅存在某个 Cargo 或 compiletest 测试框架本身不满足要求如果第一个可行的测试需要任何生产代码编辑必须先 PAUSE——设计那个观察边界本身就属于测试套件设计如果测试需要选择新的观察点或依赖注入边界例如抽取生产逻辑、创建共享 helper 或模块、暴露内部实现、引入假子进程、注册新的 harness 或 runner那属于测试套件设计变更前必须 PAUSE 询问允许的做法新增一个测试模块且它只调用既有的可调用行为、不重构生产代码。仓库侧的对应设施是 compiletest 测试框架--bless参数在 cli.rs 中被定义为“Overwrite stderr/stdout files instead of complaining about a mismatch”用覆盖 stderr/stdout 文件来代替对不匹配的抱怨这正是门禁中“观察失败时不得 bless”所指的工具行为。测试套件的运行方法见 running tests 指引新增测试的规范见 adding tests 指引测试文件中的指令语法见 directives 指引。Soundness 门禁编译器仓库中最重要的分类Soundness 一节是本仓库语境下最特殊的门禁涉及 soundness 的实现被禁止但添加或定位失败的回归测试是允许且必需的。时序上要求即使更早意识到了风险也要先完成仅限测试的工作、等待测试命令退出、把测试留在树中、汇报其结果然后陈述分类结论并在规划或编辑实现之前 STOP。分类标准是看代码控制的行为而不是看症状计算或转换类型、常量、MIR、内存布局或有效性validity、或生成代码的代码都是 soundness-sensitive报告的 bug 症状、预期的修复方式、补丁大小都不改变分类一个 ICE编译器崩溃、对合法代码的拒绝、或局部 plumbing bug仍然可能是 soundness-sensitive若任务 soundness-sensitive 或不确定实现被禁STOP 并遵循门禁失败协议若调查发现受影响的行为与先前判断不同在下一次实现编辑前必须重新分类。文档列出的 soundness-sensitive 区域不限于query 系统、类型检查、trait 求解、MIR 构建或优化、借用检查、常量求值、归一化与语义缓存、布局与有效性、codegen——并指引用户将相关讨论带到#llm-mentoringZulip 频道。这些区域与仓库源码目录一一对应例如 compiler/rustc_borrowck借用检查、compiler/rustc_const_eval常量求值、compiler/rustc_mir_transformMIR 优化、compiler/rustc_hir_typeck类型检查、compiler/rustc_query_implquery 系统、compiler/rustc_codegen_llvmcodegen。也就是说这套门禁实质上圈定了 rustc 内部风险最高的模块Agent 可以在这些模块里写回归测试、观察失败、汇报结果但写出安全的实现必须留给人类或人类指导下的流程。推送前确认、披露与禁止 Co-Authored-ByBefore pushing 一节要求提交之后、push 之前一次性询问用户确认其已理解变更、已测试并已亲自审阅了自最近一次变更以来完整 diff——Agent 自己的审查不算数遗漏任何一项确认都必须 PAUSE。同时提醒用户在 PR 描述中披露 LLM 使用情况。披露要求对应策略中的 disclosure 部分必须描述 LLM 参与的范围与目的包括 LLM 是否提出了想法、还是协助了实现或审查Agent 不得代写或改写这段披露必须由用户本人撰写并且不要向 commit 添加Co-Authored-Bytrailer。文档明确对 LLM 使用撒谎或隐瞒属于违反行为准则Code of Conduct。机械化重写优先跑工具而不是手改Mechanical rewrites 一节的规则是遵循 rustc-dev-guide 的 LLM 指引对允许的批量重命名或机械化重写先找一个现成的格式化器、linter 或语法感知重写工具——如果存在下一个变更动作必须是运行它不得先编辑目标文件、也不得手工复现它的重写如果不存在这样的工具要说明直接由 LLM 重写是不推荐的并在继续前询问。文档给出了两条具体命令Rust 格式化使用./x fmt不要直接调用rustfmt如果 tidy 可以完成重写运行./x test tidy --bless而不是手工复现它的编辑。这里的./x就是仓库根目录的 x shell 脚本它负责在 Linux/macOS/Windows 上按序探测可用的 Python 解释器python3、python、py -3等最终exec到 x.py而x.py自身只是一个约 50 行的入口注释明确写着它是指向src/bootstrap/bootstrap.py的“符号链接”真正的构建逻辑在 bootstrap 中对应文档引用的 building and running rustc 指引。这也解释了为什么文档反复强调“不要直接调用 Cargo除非相关树内文档明确要求”——这个仓库的构建、测试、格式化统一走 bootstrap 编排的./x入口。对包含人类面向文本的快照重新生成前必须走四步流程确认用户已在源码中写好新文本运行不带--bless的聚焦测试观察到预期的不匹配运行仓库现有的--bless命令检查生成的 diff。不得手工修补或添加文本如果工具产生了意外的人类面向文本STOP 并向用户报告。此外若某个请求与这些规则冲突文档指引用户到#llm-mentoringZulip 频道求助。仓库指引AGENTS.md 的路由表文档末段 Repository guidance 声明这是主rust-lang/rust仓库要求 Agent 从 CONTRIBUTING.md 与 dev-guide 的 LLM 指引开始然后把专项工作路由到对应文档。下面是完整的映射所有仓库内路径均已在本仓库中核实存在专项工作路由目标仓库内相对路径标准库std-dev-guide外部站点见 CONTRIBUTING.md编译器rustc-dev-guide构建或运行 rustcbuilding and running rustc运行/新增测试、compiletest 指令running、adding、directives格式化或 tidyconventions 之 formatting架构或仓库布局overview、compiler-srcSubtree、submodule 或工具external-reposPull request 与审查contributingLLM 写作指引llm-guidance、writing./x是该仓库的构建工具是构建、测试与格式化的默认入口。文档最后还保留了策略允许 Agent 撰写源码注释的那一小部分情形的原则解释代码或决策为什么存在而不是复述代码在做什么——这一条与“禁写文本”一节形成精确的边界划分。小结门禁体系的工程含义把 AGENTS.md 的全文连起来读可以归纳出一条可操作的执行链编辑前查归属subtree/工具路由回上游→ 查禁写类别诊断消息、注释、PR 文本等由人类执笔→ 要一个具名审阅人或声明本地不提交的例外实现前先让失败测试以非 bless 方式失败并被观察到 → 对受影响行为做 soundness 分类敏感或不确定即 STOP重写时优先运行./x fmt、./x test tidy --bless等既有工具不手工复现push 前用户亲自审阅完整 diff 并一次性确认 → 用户本人撰写披露 → 不加Co-Authored-Bytrailer。这套规则的价值不在于限制而在于把“LLM 能做什么、人类必须做什么”的边界写成了 Agent 可直接执行的流程且每个门禁都指向仓库内真实存在的设施./x入口脚本x、x.py、compiletest 的--bless机制cli.rs与 rustc-dev-guide 的 LLM 指引llm-guidance。在编译器这类对 soundness 零容忍的代码库中这种“测试可以先写、实现必须让位”的分层授权是当前仓库给出的最完整、可直接引用的 LLM 协作操作规范。【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考