Hydra 仓库开发规范解读为 AI 编码 Agent 量身定制的 AGENTS.md 全指南【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra导读AGENTS.md是 Hydra 仓库根目录下专为 AI 编码 Agent以及任何遵循自动化协作流程的贡献者编写的一份开发协作规范旨在降低 LLM 编码过程中的常见失误。本文以该文档为核心骨架逐条解读其行为准则、验证流程、lint 工具链、VCS 约定与 news fragment 机制并结合仓库内的 noxfile.py、pyproject.toml、pytest.ini、CONTRIBUTING.md 以及 website/docs/development 下的开发者文档说明每一项规则在 Hydra 实际工程中的落地方式。读完本文你将掌握在该仓库中安全、高效地改动代码、运行测试、通过 lint、提交 PR 的完整工作流。一、行为准则减少 LLM 编码失误的默认规则AGENTS.md开头即点明其定位Repo-specific directives for coding agents working in this project。它强调行为默认值偏向谨慎而非速度并允许在真正琐碎的任务上行使判断力。以下五条准则是所有后续仓库级规则的基础。1. 动手前先思考Think before coding不要臆测Do not assume不要隐藏困惑Do not hide confusion暴露取舍Surface tradeoffs当假设对实现有影响时明确陈述假设存在多种合理解释时呈现它们而不是默默挑选一种存在更简单的方案时直接说出来在必要时提出反对意见遇到重大不明或风险时停下来、说出困惑点并提问而不是猜测。这条规则直接呼应 Hydra 这类复杂配置框架的特性配置组合、默认值列表defaults list、插件发现等机制都有大量隐性约定盲目猜一个实现往往会产生看似合理实则错误的改动。2. 简单性优先Simplicity first用完成任务所需的最少代码解决问题不加未要求的功能不为单次使用的代码做抽象不引入未被请求的灵活性或可配置性不为上下文中实际上不可能出现的场景写错误处理如果方案对任务而言过度设计先简化再收尾如果写了 200 行而 50 行就能达到同样结果重写自问资深工程师会说这过度复杂吗如果是就简化。Hydra 是一个以优雅配置复杂应用为目标的框架其自身代码也遵循这一哲学——从 hydra/core 下 config_loader、config_store、default_element 等模块的拆分可以看出每个抽象都服务于明确的配置加载与组合职责。3. 外科手术式改动Surgical changes只触碰请求所需的代码除非改动必需否则不要顺带清理相邻代码、注释、格式或结构除非用户要求更大范围的重构否则匹配代码库现有风格与模式发现无关的死代码或问题提出来而不是顺手修复移除你的改动导致不再使用的 import、变量、函数或产物未经要求不删除无关的既有死代码每一行改动都应能直接追溯到用户请求。4. 优先使用聚焦工具而非临时 shellPrefer focused tools over ad hoc shell文档要求文件操作使用仓库感知的检查与编辑工具shell 命令仅保留给真正需要 shell 执行的场景slSapling命令、gh、依赖安装或用于测试、lint 及其他仓库工具的nox/pytest/python。同时规定用rg做文本搜索、用rg --files做文件发现避免在专用工具或标准 CLI 工具可胜任时使用内联 Python 片段python -c ...用jq等结构化工具解析 JSON 输出而不是管道给 Python。这与 Hydra 仓库的实际工具布局一致仓库自带 tools 目录configen、copyright、landscape、release 等大量自动化工作由 nox session 封装而非依赖临时脚本。5. 目标驱动执行Goal-driven execution把请求转化为可验证的具体成功标准修 bug先用测试或其他可靠手段复现问题再修复重构先通过检查证明重构前后行为一致多步任务保持简短计划每步验证后再继续用具体目标替代模糊目标例如添加校验 → 为非法输入写测试然后让它们通过修复 bug → 用测试或可靠检查复现再让它通过重构 X → 重构前后验证行为。这套测试先行的目标分解方式与下文 Verification 一节中两层验证的要求一脉相承。二、文档地图快速定位仓库文档体系AGENTS.md给出了仓库文档的索引原文档中使用的是相对于 AGENTS.md 自身的链接本文统一转换为仓库根目录相对路径内容仓库路径网站与文档源码website/当前文档website/docs/开发者文档website/docs/development/插件文档website/docs/plugins/版本化文档website/versioned_docs/其中与 Agent 开发最相关的是 website/docs/development/overview.md环境搭建与HYDRA_FULL_ERROR1调试技巧、website/docs/development/testing.mdnox/pytest 测试矩阵与 website/docs/development/release.md发布流程。仓库还保留了 0.11 到 1.3 各版本的版本化文档website/versioned_docs/对应 website/versioned_sidebars 中的侧边栏配置。三、复现文件约定统一放在 temp/当需要为某个 issue 创建复现材料时AGENTS.md规定统一放在temp/目录下单文件复现temp/issue_number.py多文件复现temp/issue_number/这一约定便于维护者快速定位问题复现脚本同时将临时产物与仓库主体隔离。值得注意的是noxfile.py 的 bandit 安全检查命令把./temp/**明确加入了排除列表见_bandit_cmd中的--exclude参数说明temp/已被仓库工具链视为可忽略的临时区域pyproject.toml 的 ruff 配置同样将temp列入extend-exclude。四、Stop and ask何时必须停下来提问文档列出了两种必须停下询问的情况受跟踪文件出现意外变化如果发现仓库跟踪的文件被意外重命名、移动、重新生成、删除或以其他方式改变在还原、重建、重新归类或暂存该变化之前必须先停下询问禁止擅自扩大范围除非请求明确包含该范围否则不得修改支持的 Python 版本、CI 矩阵、打包元数据、发布自动化或工作流触发器。第二点与 CONTRIBUTING.md 的 PR 要求相呼应——非平凡特性、API 变更或用户可见行为变更需要先开 issue 或设计讨论并等待维护者反馈而不是直接开始大规模实现。这实际上把变更影响面的判断前置到了编码之前。五、验证pytest 与 nox 的两层测试AGENTS.md要求任何新增或修改的功能在可行时进行两层验证用pytest path/to/test_file.py运行相关聚焦测试运行相关 nox session 确保无回归。同时给出三条补充规则Hydra 核心测试从仓库根目录用pytest运行插件测试需要在安装插件后从插件目录运行或通过nox -s test_plugins执行验证单个插件时用PLUGINSplugin_dir_name配合 nox如果更广泛的测试套件与聚焦测试结论不一致以更广的结果为准不要宣称改动已通过验证若当前环境阻塞了实机验证可以请求升级escalation以解除阻塞否则停下询问。pytest 的仓库级配置pytest.ini 提供了核心测试的入口配置testpaths覆盖build_helpers与testsnorecursedirs排除了.nox、build、website、plugins、examples/plugins、examples、tests/standalone_apps、tools——这些目录分别由 nox session 单独测试filterwarnings error将警告视为错误另有针对 Optuna/SQLAlchemy 与工作目录变更未来行为的白名单。nox session 的全貌noxfile.py 是 Hydra 所有自动化任务的统一入口核心 session 包括session作用test_core在 [3.10, 3.11, 3.12, 3.13, 3.14] 全部支持版本上测试核心test_plugins按插件参数化安装并测试单个插件test_plugins_vs_core安装全部兼容插件后重跑核心测试验证插件未破坏核心test_tools测试 tools/ 下的工具configen、release、landscape 等test_jupyter_notebooks用 nbval 校验 notebooklint/lint-core/lint-plugins全量 lint见下一节coverage覆盖率报告--fail-under80门槛插件选择逻辑由环境变量控制对应 website/docs/development/testing.md 中的示例PLUGINShydra_colorlog只选该插件SKIP_PLUGINS显式排除SKIP_CORE_TESTS跳过核心测试NOX_PYTHON_VERSIONS覆盖测试的 Python 版本矩阵。例如只测单个插件PLUGINShydra_colorlog nox -s test_plugins-3.10六、Lint 与格式化完整工具链AGENTS.md规定大规模改动时通过nox -s lint lint_plugins运行 lint并说明仓库的 lint session 包含格式化、import 排序、类型检查、代码风格、YAML lint 与安全检查。聚焦的本地检查则使用与 noxfile 相同的工具ruff format . # 格式化加 --check 仅检查 ruff check . # lint 检查加 --fix 自动修复 pyrefly check --config pyproject.toml # 类型检查 yamllint --strict . # YAML lint bandit --exclude ./.nox/** -ll -r . # 静态安全扫描各工具在仓库中的实际配置ruffpyproject.toml 中line-length 88、target-version py310lint 选择 E/F/I/W/CPY 规则集开启 previewflake8-copyright 规则要求文件头匹配Copyright (c) Facebook, Inc...或SPDX-FileCopyrightText: Contributors to Hydra这与 CONTRIBUTING.md 的版权头要求一致isort 将hydra、hydra_app设为 known-first-party。pyrefly同文件的[tool.pyrefly]定义project-includesnoxfile、setup.py、build_helpers、hydra、tests与project-excludesgrammar 生成代码、standalone_apps 等并对antlr4、nevergrad、rq等外部依赖忽略缺失 import。yamllintCORE_YAML_LINT_PATHS覆盖.github、lgtm.yml、examples、hydra、tests、tools等全部 YAML 来源--strict模式要求零警告。banditCORE_BANDIT_PATHS覆盖核心源码、examples、tests 与工具目录排除.nox、.sl、.venv、build、temp、website等生成/临时区域。noxfile 还针对 CI 做了适配在 GitHub Actions 环境下ruff、yamllint、bandit、pyrefly 都会附加--output-format github把问题直接映射为 GitHub 错误注解。FIX1环境变量可让 ruff 进入自动修复模式。七、环境与钩子.venv 优先AGENTS.md的环境规则很明确默认从仓库本地.venv运行命令优先使用.venv/bin/python、.venv/bin/pip、.venv/bin/pytest、.venv/bin/nox如果.venv缺失且需要安装依赖用python -m venv .venv创建然后安装 requirements/dev.txt 与可编辑安装只有在测试特定受支持的 Python 版本或复现环境特定问题时才使用单独的环境。CONTRIBUTING.md 给出了对应的开发者环境搭建流程python -m venv .venv source .venv/bin/activate pip install -r requirements/dev.txt pip install -e .requirements/dev.txt 列出了完整工具链attrs、bandit、ruff0.15.22、pyrefly1.1.1、nox、pytest9.1.1、yamllint、towncrier、twine、pre-commit等。文档还强调验证贡献者环境、shell 初始化或钩子行为时应从开发者实际使用的同一环境如普通 shell 会话或sl commit验证而不能只在临时沙箱环境中验证并优先使用不依赖复杂用户环境工具的钩子。八、版本控制与 PRsl / git 双工作流Hydra 的部分 worktree 使用 Saplingsl检出另一些则是普通 Git 克隆——当前仓库实例即为 Git 检出根目录存在.git而非.sl。AGENTS.md对此的处理原则使用与当前检出匹配的 VCS 工具本地 status、log、diff、commit、amend、stack 检查优先用检出原生的工具Sapling 检出中用sl进行常规本地 VCS 操作升级escalated的 VCS 命令保持最小化、单一目的不把暂存、环境引导、依赖安装、提交创建捆绑进一条升级 shell 命令除非别无选择VCS 操作需要升级时只请求需要的具体动作除非用户明确要求不得 force-push、submit 或更新远端分支使用底层回退命令如 Sapling 检出中的git --git-dir .sl/store/git之前先停下说明常规工作流为何不够用。九、发布与 news fragments外发动作的边界外发动作红线除非用户明确要求不 commit、push、merge、publish 或以其他方式把改动发送到本地工作树之外如果改动影响发布自动化、工作流触发器、部署行为等外部可见机制在任何 commit、push、merge、publish、部署动作前要求显式的用户评审检查点发布由用户负责不要编辑版本号、创建发布文件、汇编发布说明除非被明确要求正式的发布流程记录在 website/docs/development/release.md不要即兴发挥手动发布流程。news fragment 机制所有非平凡的、用户可见的改动都应附带 news fragment核心 Hydra 的 fragment 放在news/下插件相关的放在对应插件的news/目录文件名遵循issue_or_pr_number.category模式支持的类别为api_change、feature、bugfix、docs、config、maintenancefragment 文本必须简洁、面向用户、使用句子大小写sentence case最好不超过 80 字符仅影响开发者工具、仓库维护或 CI 的改动不需要 fragment除非它们改变了对外发布的产品体验。仓库 news/ 目录提供了大量真实样例例如news/2577.feature内容为Honor _recursive_ on non-target config nodes during instantiation.news/2119.api_change、news/1899.bugfix等也遵循同一命名模式。这些 fragment 由 towncrier 汇总进 NEWS.md其类型映射定义在 pyproject.toml 的[tool.towncrier]中渲染模板为 news/_template.rst。一个 PR 可以创建多个 fragment 覆盖多个类别如同时1234.feature与1234.api_change发布工具会去重。十、评审review 的覆盖范围当被要求评审一个 commit、PR 或 diff 时AGENTS.md要求覆盖四方面正确性correctness完整性completeness文档documentation内部一致性internal consistency。并且要核实每个用户可见的改动都带有合适的 news fragment且 fragment 与实现和文档匹配。这条规则把review从代码正确性检查扩展为对改动是否完整闭环实现 测试 文档 变更记录的全面审视。结语AGENTS.md的价值在于把 Hydra 这个大型开源项目数年的工程约定压缩成一份 AI Agent 可以直接遵循的操作手册从先思考、再动手的心智默认值到 temp/ 复现目录、pytest/nox 两层验证、ruff/pyrefly/yamllint/bandit 工具链、.venv 环境约定、sl/git 双工作流、news fragment 机制与评审标准。对任何打算在 Hydra 仓库中工作的 Agent 或贡献者而言按这份文档执行等于以最低的试错成本接入项目的真实工程流程——它比任何单一工具文档都更接近在这个仓库里正确做事的完整答案。【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Hydra 仓库开发规范解读：为 AI 编码 Agent 量身定制的 AGENTS.md 全指南
Hydra 仓库开发规范解读为 AI 编码 Agent 量身定制的 AGENTS.md 全指南【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra导读AGENTS.md是 Hydra 仓库根目录下专为 AI 编码 Agent以及任何遵循自动化协作流程的贡献者编写的一份开发协作规范旨在降低 LLM 编码过程中的常见失误。本文以该文档为核心骨架逐条解读其行为准则、验证流程、lint 工具链、VCS 约定与 news fragment 机制并结合仓库内的 noxfile.py、pyproject.toml、pytest.ini、CONTRIBUTING.md 以及 website/docs/development 下的开发者文档说明每一项规则在 Hydra 实际工程中的落地方式。读完本文你将掌握在该仓库中安全、高效地改动代码、运行测试、通过 lint、提交 PR 的完整工作流。一、行为准则减少 LLM 编码失误的默认规则AGENTS.md开头即点明其定位Repo-specific directives for coding agents working in this project。它强调行为默认值偏向谨慎而非速度并允许在真正琐碎的任务上行使判断力。以下五条准则是所有后续仓库级规则的基础。1. 动手前先思考Think before coding不要臆测Do not assume不要隐藏困惑Do not hide confusion暴露取舍Surface tradeoffs当假设对实现有影响时明确陈述假设存在多种合理解释时呈现它们而不是默默挑选一种存在更简单的方案时直接说出来在必要时提出反对意见遇到重大不明或风险时停下来、说出困惑点并提问而不是猜测。这条规则直接呼应 Hydra 这类复杂配置框架的特性配置组合、默认值列表defaults list、插件发现等机制都有大量隐性约定盲目猜一个实现往往会产生看似合理实则错误的改动。2. 简单性优先Simplicity first用完成任务所需的最少代码解决问题不加未要求的功能不为单次使用的代码做抽象不引入未被请求的灵活性或可配置性不为上下文中实际上不可能出现的场景写错误处理如果方案对任务而言过度设计先简化再收尾如果写了 200 行而 50 行就能达到同样结果重写自问资深工程师会说这过度复杂吗如果是就简化。Hydra 是一个以优雅配置复杂应用为目标的框架其自身代码也遵循这一哲学——从 hydra/core 下 config_loader、config_store、default_element 等模块的拆分可以看出每个抽象都服务于明确的配置加载与组合职责。3. 外科手术式改动Surgical changes只触碰请求所需的代码除非改动必需否则不要顺带清理相邻代码、注释、格式或结构除非用户要求更大范围的重构否则匹配代码库现有风格与模式发现无关的死代码或问题提出来而不是顺手修复移除你的改动导致不再使用的 import、变量、函数或产物未经要求不删除无关的既有死代码每一行改动都应能直接追溯到用户请求。4. 优先使用聚焦工具而非临时 shellPrefer focused tools over ad hoc shell文档要求文件操作使用仓库感知的检查与编辑工具shell 命令仅保留给真正需要 shell 执行的场景slSapling命令、gh、依赖安装或用于测试、lint 及其他仓库工具的nox/pytest/python。同时规定用rg做文本搜索、用rg --files做文件发现避免在专用工具或标准 CLI 工具可胜任时使用内联 Python 片段python -c ...用jq等结构化工具解析 JSON 输出而不是管道给 Python。这与 Hydra 仓库的实际工具布局一致仓库自带 tools 目录configen、copyright、landscape、release 等大量自动化工作由 nox session 封装而非依赖临时脚本。5. 目标驱动执行Goal-driven execution把请求转化为可验证的具体成功标准修 bug先用测试或其他可靠手段复现问题再修复重构先通过检查证明重构前后行为一致多步任务保持简短计划每步验证后再继续用具体目标替代模糊目标例如添加校验 → 为非法输入写测试然后让它们通过修复 bug → 用测试或可靠检查复现再让它通过重构 X → 重构前后验证行为。这套测试先行的目标分解方式与下文 Verification 一节中两层验证的要求一脉相承。二、文档地图快速定位仓库文档体系AGENTS.md给出了仓库文档的索引原文档中使用的是相对于 AGENTS.md 自身的链接本文统一转换为仓库根目录相对路径内容仓库路径网站与文档源码website/当前文档website/docs/开发者文档website/docs/development/插件文档website/docs/plugins/版本化文档website/versioned_docs/其中与 Agent 开发最相关的是 website/docs/development/overview.md环境搭建与HYDRA_FULL_ERROR1调试技巧、website/docs/development/testing.mdnox/pytest 测试矩阵与 website/docs/development/release.md发布流程。仓库还保留了 0.11 到 1.3 各版本的版本化文档website/versioned_docs/对应 website/versioned_sidebars 中的侧边栏配置。三、复现文件约定统一放在 temp/当需要为某个 issue 创建复现材料时AGENTS.md规定统一放在temp/目录下单文件复现temp/issue_number.py多文件复现temp/issue_number/这一约定便于维护者快速定位问题复现脚本同时将临时产物与仓库主体隔离。值得注意的是noxfile.py 的 bandit 安全检查命令把./temp/**明确加入了排除列表见_bandit_cmd中的--exclude参数说明temp/已被仓库工具链视为可忽略的临时区域pyproject.toml 的 ruff 配置同样将temp列入extend-exclude。四、Stop and ask何时必须停下来提问文档列出了两种必须停下询问的情况受跟踪文件出现意外变化如果发现仓库跟踪的文件被意外重命名、移动、重新生成、删除或以其他方式改变在还原、重建、重新归类或暂存该变化之前必须先停下询问禁止擅自扩大范围除非请求明确包含该范围否则不得修改支持的 Python 版本、CI 矩阵、打包元数据、发布自动化或工作流触发器。第二点与 CONTRIBUTING.md 的 PR 要求相呼应——非平凡特性、API 变更或用户可见行为变更需要先开 issue 或设计讨论并等待维护者反馈而不是直接开始大规模实现。这实际上把变更影响面的判断前置到了编码之前。五、验证pytest 与 nox 的两层测试AGENTS.md要求任何新增或修改的功能在可行时进行两层验证用pytest path/to/test_file.py运行相关聚焦测试运行相关 nox session 确保无回归。同时给出三条补充规则Hydra 核心测试从仓库根目录用pytest运行插件测试需要在安装插件后从插件目录运行或通过nox -s test_plugins执行验证单个插件时用PLUGINSplugin_dir_name配合 nox如果更广泛的测试套件与聚焦测试结论不一致以更广的结果为准不要宣称改动已通过验证若当前环境阻塞了实机验证可以请求升级escalation以解除阻塞否则停下询问。pytest 的仓库级配置pytest.ini 提供了核心测试的入口配置testpaths覆盖build_helpers与testsnorecursedirs排除了.nox、build、website、plugins、examples/plugins、examples、tests/standalone_apps、tools——这些目录分别由 nox session 单独测试filterwarnings error将警告视为错误另有针对 Optuna/SQLAlchemy 与工作目录变更未来行为的白名单。nox session 的全貌noxfile.py 是 Hydra 所有自动化任务的统一入口核心 session 包括session作用test_core在 [3.10, 3.11, 3.12, 3.13, 3.14] 全部支持版本上测试核心test_plugins按插件参数化安装并测试单个插件test_plugins_vs_core安装全部兼容插件后重跑核心测试验证插件未破坏核心test_tools测试 tools/ 下的工具configen、release、landscape 等test_jupyter_notebooks用 nbval 校验 notebooklint/lint-core/lint-plugins全量 lint见下一节coverage覆盖率报告--fail-under80门槛插件选择逻辑由环境变量控制对应 website/docs/development/testing.md 中的示例PLUGINShydra_colorlog只选该插件SKIP_PLUGINS显式排除SKIP_CORE_TESTS跳过核心测试NOX_PYTHON_VERSIONS覆盖测试的 Python 版本矩阵。例如只测单个插件PLUGINShydra_colorlog nox -s test_plugins-3.10六、Lint 与格式化完整工具链AGENTS.md规定大规模改动时通过nox -s lint lint_plugins运行 lint并说明仓库的 lint session 包含格式化、import 排序、类型检查、代码风格、YAML lint 与安全检查。聚焦的本地检查则使用与 noxfile 相同的工具ruff format . # 格式化加 --check 仅检查 ruff check . # lint 检查加 --fix 自动修复 pyrefly check --config pyproject.toml # 类型检查 yamllint --strict . # YAML lint bandit --exclude ./.nox/** -ll -r . # 静态安全扫描各工具在仓库中的实际配置ruffpyproject.toml 中line-length 88、target-version py310lint 选择 E/F/I/W/CPY 规则集开启 previewflake8-copyright 规则要求文件头匹配Copyright (c) Facebook, Inc...或SPDX-FileCopyrightText: Contributors to Hydra这与 CONTRIBUTING.md 的版权头要求一致isort 将hydra、hydra_app设为 known-first-party。pyrefly同文件的[tool.pyrefly]定义project-includesnoxfile、setup.py、build_helpers、hydra、tests与project-excludesgrammar 生成代码、standalone_apps 等并对antlr4、nevergrad、rq等外部依赖忽略缺失 import。yamllintCORE_YAML_LINT_PATHS覆盖.github、lgtm.yml、examples、hydra、tests、tools等全部 YAML 来源--strict模式要求零警告。banditCORE_BANDIT_PATHS覆盖核心源码、examples、tests 与工具目录排除.nox、.sl、.venv、build、temp、website等生成/临时区域。noxfile 还针对 CI 做了适配在 GitHub Actions 环境下ruff、yamllint、bandit、pyrefly 都会附加--output-format github把问题直接映射为 GitHub 错误注解。FIX1环境变量可让 ruff 进入自动修复模式。七、环境与钩子.venv 优先AGENTS.md的环境规则很明确默认从仓库本地.venv运行命令优先使用.venv/bin/python、.venv/bin/pip、.venv/bin/pytest、.venv/bin/nox如果.venv缺失且需要安装依赖用python -m venv .venv创建然后安装 requirements/dev.txt 与可编辑安装只有在测试特定受支持的 Python 版本或复现环境特定问题时才使用单独的环境。CONTRIBUTING.md 给出了对应的开发者环境搭建流程python -m venv .venv source .venv/bin/activate pip install -r requirements/dev.txt pip install -e .requirements/dev.txt 列出了完整工具链attrs、bandit、ruff0.15.22、pyrefly1.1.1、nox、pytest9.1.1、yamllint、towncrier、twine、pre-commit等。文档还强调验证贡献者环境、shell 初始化或钩子行为时应从开发者实际使用的同一环境如普通 shell 会话或sl commit验证而不能只在临时沙箱环境中验证并优先使用不依赖复杂用户环境工具的钩子。八、版本控制与 PRsl / git 双工作流Hydra 的部分 worktree 使用 Saplingsl检出另一些则是普通 Git 克隆——当前仓库实例即为 Git 检出根目录存在.git而非.sl。AGENTS.md对此的处理原则使用与当前检出匹配的 VCS 工具本地 status、log、diff、commit、amend、stack 检查优先用检出原生的工具Sapling 检出中用sl进行常规本地 VCS 操作升级escalated的 VCS 命令保持最小化、单一目的不把暂存、环境引导、依赖安装、提交创建捆绑进一条升级 shell 命令除非别无选择VCS 操作需要升级时只请求需要的具体动作除非用户明确要求不得 force-push、submit 或更新远端分支使用底层回退命令如 Sapling 检出中的git --git-dir .sl/store/git之前先停下说明常规工作流为何不够用。九、发布与 news fragments外发动作的边界外发动作红线除非用户明确要求不 commit、push、merge、publish 或以其他方式把改动发送到本地工作树之外如果改动影响发布自动化、工作流触发器、部署行为等外部可见机制在任何 commit、push、merge、publish、部署动作前要求显式的用户评审检查点发布由用户负责不要编辑版本号、创建发布文件、汇编发布说明除非被明确要求正式的发布流程记录在 website/docs/development/release.md不要即兴发挥手动发布流程。news fragment 机制所有非平凡的、用户可见的改动都应附带 news fragment核心 Hydra 的 fragment 放在news/下插件相关的放在对应插件的news/目录文件名遵循issue_or_pr_number.category模式支持的类别为api_change、feature、bugfix、docs、config、maintenancefragment 文本必须简洁、面向用户、使用句子大小写sentence case最好不超过 80 字符仅影响开发者工具、仓库维护或 CI 的改动不需要 fragment除非它们改变了对外发布的产品体验。仓库 news/ 目录提供了大量真实样例例如news/2577.feature内容为Honor _recursive_ on non-target config nodes during instantiation.news/2119.api_change、news/1899.bugfix等也遵循同一命名模式。这些 fragment 由 towncrier 汇总进 NEWS.md其类型映射定义在 pyproject.toml 的[tool.towncrier]中渲染模板为 news/_template.rst。一个 PR 可以创建多个 fragment 覆盖多个类别如同时1234.feature与1234.api_change发布工具会去重。十、评审review 的覆盖范围当被要求评审一个 commit、PR 或 diff 时AGENTS.md要求覆盖四方面正确性correctness完整性completeness文档documentation内部一致性internal consistency。并且要核实每个用户可见的改动都带有合适的 news fragment且 fragment 与实现和文档匹配。这条规则把review从代码正确性检查扩展为对改动是否完整闭环实现 测试 文档 变更记录的全面审视。结语AGENTS.md的价值在于把 Hydra 这个大型开源项目数年的工程约定压缩成一份 AI Agent 可以直接遵循的操作手册从先思考、再动手的心智默认值到 temp/ 复现目录、pytest/nox 两层验证、ruff/pyrefly/yamllint/bandit 工具链、.venv 环境约定、sl/git 双工作流、news fragment 机制与评审标准。对任何打算在 Hydra 仓库中工作的 Agent 或贡献者而言按这份文档执行等于以最低的试错成本接入项目的真实工程流程——它比任何单一工具文档都更接近在这个仓库里正确做事的完整答案。【免费下载链接】hydraHydra is a framework for elegantly configuring complex applications项目地址: https://gitcode.com/GitHub_Trending/hyd/hydra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考