Motrix 的 AI 编码代理协作治理AGENTS.md、CLAUDE.md 与路径作用域规则体系详解【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix本文以 AGENTS.md 为核心解读 MotrixElectron Node/Web 双壳下载管理器如何用一套“官方规则 规则路由 自动化质量门”的机制让 Claude Code、Codex 等不同 AI 编码代理在同一仓库中遵守同一套工程约束。读完本文你能掌握代理进场前的规则加载顺序、全局规则与paths作用域规则的区分方式、多来源指令的冲突裁决优先级以及这套治理如何与 scripts/check-boundaries.mjs、提交门commit gate和 CI 工作流形成闭环。一、AGENTS.md 的定位官方代理指引的单一入口AGENTS.md 全文只有 18 行但它承担的不是“内容”而是“路由”职责。文件开篇即声明核心设计决策Claude Code rules are the canonical agent guidance for this repository. Codex inherits them instead of maintaining a second copy.也就是说仓库不维护两套代理规则Claude Code 的规则CLAUDE.md 加.claude/rules/下的 13 个规则文件是唯一事实来源canonical sourceCodex 等其他兼容 AGENTS.md 约定的代理直接继承避免规则双副本漂移。这与 CLAUDE.md 开头的项目画像呼应——Motrix 是一个 Electron 与 Node/Web 双壳下载管理器src/core/必须保持宿主中立host-neutral以便同时被两个 shell 复用并可独立替换而架构边界、命令清单、规则路由表全部沉淀在 CLAUDE.md 中。从源码结构看这是当前开源社区应对“多代理协作”的典型模式AGENTS.md作为跨代理通用入口只写“指路 裁决规则”把具体工程约束留在各代理原生位置.claude/由入口文件统一收口。二、规则加载顺序检查或修改文件之前必须读什么AGENTS.md 给出的强制前置流程Before inspecting or changing files, read是一个三步加载顺序先读 CLAUDE.md——获得项目画像、核心命令、架构边界总则与规则路由表再读所有没有pathsfrontmatter 的.claude/rules/*.md——这些是全局规则对任何改动都生效最后读paths模式命中的规则——即其pathsglob 匹配当前正在检查或修改的文件的规则。其中第 2、3 步依赖一个关键机制规则文件使用 YAML frontmatter 的paths字段声明作用域。仓库中 13 个规则文件.claude/rules/正好分为两类全局规则无paths字段改动任何文件都需加载规则文件作用.claude/rules/commit-and-quality.md提交必过的三道检查与按改动类型的条件校验.claude/rules/git-workflow.mdConventional Commits、分支命名、PR、发布安全.claude/rules/language-and-docs.md代码/注释/提交一律英文面向用户的文档以英文 zh-CN双语成对发布路径作用域规则仅在paths命中时才加载规则文件paths命中的典型范围.claude/rules/architecture.mdsrc/**/*.ts(x)、scripts/check-boundaries.mjs.claude/rules/code-style.mdsrc/**/*.ts(x)、src/**/*.css、*.config.ts.claude/rules/domain-model.mdsrc/shared/**、src/core/**.claude/rules/electron-vite.mdelectron-builder.json、pnpm-workspace.yaml、package.json、Dockerfile、vite.*.config.ts及打包脚本.claude/rules/renderer.mdsrc/renderer/**.claude/rules/panel-layout.mdsrc/renderer/routes/**、布局与 panel 组件.claude/rules/i18n.mdsrc/core/i18n/**、src/shared/locales/*.json、scripts/check-i18n.mjs 等.claude/rules/plugins.mdsrc/core/plugin/**、src/main/plugin/**、src/server/plugin/**、scripts/fetch-builtins.mjs 等.claude/rules/plugin-registry.mdsrc/shared/schemas/registry*、插件注册表与安装链路.claude/rules/bridge.mdsrc/core/bridge/**、src/main/bridge/**、packages/native-host/**等 MDXP 桥接链路这套分工在 CLAUDE.md 的 “Rule Routing” 一节有明确表述“Rules withoutpathsfrontmatter are global. Load path-scoped rules only when their patterns match the files under inspection or modification.”AGENTS.md 还补充了两条动态规则构成完整的加载语义范围扩展即补载“If the scope expands, load the newly matching rules before continuing.”——任务从src/renderer/扩到src/core/时必须先加载domain-model.md等新增命中规则再继续动手不预载无关规则“Do not load unrelated path-scoped rules by default.”——改src/renderer/时不应把electron-vite.md、plugins.md全部读进来避免上下文污染与规则冲突面扩大。三、冲突裁决优先级五级顺序当多个来源给出矛盾指令时AGENTS.md 给出固定的裁决链Conflicts resolve in this order1. current user instructions 当前用户指令最高 2. this file (AGENTS.md) 入口文件本身 3. CLAUDE.md 项目级总则 4. matching .claude/rules/*.md 命中的路径作用域规则 5. default agent behavior 代理自身默认行为最低这个顺序有两个值得注意的工程含义用户指令永远最高——代理不能拿仓库规则拒绝用户明确要求责任边界清晰入口文件高于 CLAUDE.md——AGENTS.md 中如果有与 CLAUDE.md 冲突的表述以 AGENTS.md 为准这保证了“入口优先”的一致性入口是代理最先读的文件其声明应当压过下游细节文档。同时规则文件自身也通过 frontmatter 的description字段声明职责边界例如architecture.md是 “Architecture boundaries for the shared desktop and server app”配合 CLAUDE.md 中的规则路由表代理可以在加载前判断某条规则是否与当前改动相关减少误读。四、单一事实来源原则只改 Claude 规则不复制指引AGENTS.md 的最后一句是维护原则Update the canonical Claude rules rather than duplicating guidance here.含义是任何需要补充的代理指引都应写进 CLAUDE.md 或对应的.claude/rules/*.md而不是在 AGENTS.md 里再抄一份。这让 AGENTS.md 保持极简、稳定避免“两处维护、一处漂移”的经典问题。从当前仓库状态看这一原则执行得很彻底AGENTS.md 只含加载顺序与裁决链没有任何具体命令或架构条款。五、治理规则如何与仓库自动化机制互证规则文件的价值不止于“写给代理看”Motrix 把大量规则同时落实成了可执行的自动化检查代理遵守规则与 CI 检查形成闭环。以下对照均来自仓库实际文件5.1 提交门Commit Gate.claude/rules/commit-and-quality.md 规定每次提交前必须跑满三道检查并修复失败pnpm run check:boundaries pnpm run lint pnpm exec tsc --noEmit这三个命令在 package.json 的scripts中均可逐一落实check:boundaries指向node scripts/check-boundaries.mjslint指向biome check .与 CI 执行完全同构规则明确要求不得换用更窄的路径列表、不得用管道丢弃退出码tsc --noEmit为 TypeScript 类型检查。该规则还要求只暂存目标文件、提交前检查git diff --staged、不得因某个 CI job 是 non-blocking 就隐藏失败。5.2 按改动类型的条件校验commit-and-quality 规则把“改什么就验什么”写成了清单例如行为/逻辑改动pnpm exec vitest run test-path聚焦测试跨切面改动用pnpm test浏览器/Electron 用户流有 E2E 覆盖时跑pnpm test:e2eplaywright.config.ts e2e/ 目录i18n 资源或行为pnpm run check:i18n新增/重命名文件pnpm run check:file-names对应 scripts/check-file-names.mjs落实 code-style.md 的 kebab-case 命名约定插件清单契约pnpm run check:schema-parity依赖/许可元数据pnpm run check:third-party-noticesNative host Rust 代码packages/native-host/cargo fmt/cargo clippy -- -D warnings/cargo test三连。5.3 架构边界规则 → 自动化扫描CLAUDE.md 声明的架构边界src/core/永不 importelectron或src/main/src/renderer/永不 importcore/main/serversrc/shared/只做纯跨层契约与 architecture.md 的分层矩阵一致而 scripts/check-boundaries.mjs 把它们变成了机器可查的正则扫描例如core must not import electron/core must not import fastifyshared must not use Node-specific APIs or globals禁止node:前缀导入、process.、NodeJS.renderer must not import core or main、server must not import electron等。规则文件也诚实地标注了自动化的边界“check:boundariesis an automated baseline, not a complete architecture proof. Review changed imports againstarchitecture.mdas well.”——即脚本是基线代理仍需对照架构规则人工复核变更的导入。5.4 分支与发布规则 → 受保护工作流git-workflow.md 规定开发在受保护的main上进行master为冻结的 Electron 22/Vue 2 遗留代码分支命名type/snake_case_topic_YYYYMMDD功能 PR 默认 squash merge发布以仓库内检入的工作流为唯一权威package.json设为严格 SemVer 后打受保护的vversion标签由 .github/workflows/release.yml 触发签名、校验与制品组装禁止人工上传、复用未验证制品或覆盖不可变的容器 tag。CLAUDE.md 的 “Core Commands” 一节pnpm start、pnpm start:server、pnpm test、pnpm build、pnpm build:server、pnpm test:e2e等并要求用pnpm exec而非npx则为代理提供了可直接执行的命令事实来源且全部能在 package.json 中一一对应。六、实践启示把“代理规则”当配置管理对读者无论是人类协作者还是接入该仓库的编码代理而言AGENTS.md 体系给出的可复用经验有三条入口极简、细节分片入口文件只保留加载顺序与冲突裁决具体规则按模块分片成 13 个文件并用pathsfrontmatter 声明作用域加载成本随改动范围线性增长而非全量预载规则必须可执行化每条重要规则尽量落到一个check:*脚本或 CI 检查上scripts/ 目录下即有数十个check-*.mjs/verify-*.mjs验证器使“代理守规矩”与“CI 过不过”成为同一件事单一事实来源优先新代理如 Codex通过 AGENTS.md 继承既有规则而不是复制规则规则演进只改一份从机制上杜绝多代理规则漂移。需要说明的前提本文所有命令、脚本名与规则条款均以当前仓库实际内容为准.claude/rules/*.md的具体条目可能随版本演进使用时以仓库内检入版本为最终依据。【免费下载链接】MotrixA full-featured download manager.项目地址: https://gitcode.com/GitHub_Trending/mo/Motrix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考