Cypress 仓库 CLAUDE.md 深度解读面向 AI 代理的 Monorepo 工作编排规范【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypressCypress 开源仓库根目录的 CLAUDE.md 是一份专门写给 AI 编码代理Claude Code 等的“工作编排规范”它用 5 条工作流原则、1 条核心原则和 3 条硬性工作约束规定了 AI 代理在这个包含 50 工作区的测试框架 Monorepo 中如何计划、如何并行、如何自纠错、如何验证以及哪些操作边界不可逾越。读懂这份文件你不仅能掌握一套可迁移的“AI 辅助开发 SOP”还能顺着它与 AGENTS.md、根 package.json 的联动关系看清 Cypress Monorepo 真实的工程底座Yarn 1 Lerna V8 Snapshot 的构建链路以及提交前必须通过的check-ts、lint、单测三道关卡。CLAUDE.md 在仓库中的定位与文档链结构CLAUDE.md 只有 48 行但它是刻意“短小精悍”的文件主体只放跨目录通用的行为规则结尾用一行AGENTS.md引用把 monorepo 级别的架构与命令细节交给同目录的 AGENTS.md 承载。这种“薄 CLAUDE.md 厚 AGENTS.md”的分层结构在仓库内是系统性的。从源码结构看每个关键工作区都有自己的一对文档文档位置示例职责CLAUDE.mdCLAUDE.md、cli/CLAUDE.md、npm/CLAUDE.md、packages/CLAUDE.md工作流编排、行为约束、环境特殊说明AGENTS.mdAGENTS.md、各包内的AGENTS.md目录职责、包架构、代码约定、常用命令例如 cli/CLAUDE.md 全文仅两行——# CLI加AGENTS.md即把 CLI 包的所有上下文委托给 cli/AGENTS.md。根级 CLAUDE.md 中“After ANY correction from the user: update the closest relevantCLAUDE.mdfile”自我改进循环这一条正是配合这种分层树设计的每次被纠正后AI 代理应把教训写回离犯错位置最近的那份文档而不是都堆到根文件里。因此阅读 CLAUDE.md 的正确姿势是把它当作“行为宪法”再沿AGENTS.md引用链读到 AGENTS.md才能拼出完整的上下文AGENTS.md 覆盖了工作区划分cli/、packages/、npm/、tooling/、system-tests/、scripts/、完整命令表、32 个内部包 15 个公开包的架构说明、代码规范与运行时代码最低版本Runtime targets等内容。工作流编排五原则Workflow OrchestrationCLAUDE.md 的第一章 “Workflow Orchestration” 给出五条原则逐条拆解如下。1. 计划模式默认开启Plan Mode Default原文四条规则任何非平凡任务3 步以上或涉及架构决策默认先进入计划模式一旦事情偏离预期立刻停下来重新规划而不是硬推着继续做计划模式不仅用于“构建”也用于验证步骤提前写出详细规格spec以减少歧义。这四条针对的是 AI 代理最常见的失败模式接到多步任务后不建计划、一路执行中途出偏后又在错误的轨道上叠加更多错误。Cypress 仓库的复杂度放大了这种风险——lerna.json 声明的packages字段列出了cli、packages/*、npm/*、tooling/*、system-tests、scripts六个包目录一次看似简单的改动可能横跨 driver、server、electron 多个包。2. 子代理策略Subagent Strategy大胆使用子代理保持主上下文窗口干净把研究、探索、并行分析全部下放给子代理复杂问题就“用更多算力换正确性”throw more compute at it一个子代理只做一个任务保证执行聚焦。在 monorepo 场景下这条原则非常实用例如排查一个跨包问题可以让一个子代理只读 packages/driver 的命令实现另一个子代理只查 packages/server 的服务端编排逻辑主上下文只保留结论。这与 AGENTS.md 中对各包的职责划分driver 负责浏览器内cy.*命令执行、server 负责测试运行编排、proxy 负责流量拦截等是配套的——包边界天然就是子代理的任务边界。3. 自我改进循环Self-Improvement Loop用户每次纠正之后都必须更新最相关的CLAUDE.md文件为自己写下防止重犯同样错误的规则。这是把“会话级经验”固化为“仓库级规则”的机制。由于 CLAUDE.md/AGENTS.md 随仓库版本化管理AI 代理的每次纠错最终都会沉淀成所有后续会话包括人类协作者可见的文档。4. 完成前验证Verification Before Done不允许在“证明它工作”之前把任务标记为完成相关时对比 main 分支与你的改动之间的行为差异diff behavior自问“一位 staff engineer 会批准这个改动吗”只运行相关测试、检查日志、演示正确性。注意第四条的“Run relevant tests only”——不是无脑全量跑测试而是与改动相关的测试子集。这一点在 Cypress 仓库有现实依据全量测试链路很重AGENTS.md 专门推荐使用带作用域的测试命令见下文“三道关卡”一节。5. 要求优雅但保持平衡Demand Elegance, Balanced非平凡改动要暂停自问“有没有更优雅的方式”如果某个修复感觉很 hack就按“我现在已经知道了一切重新用优雅的方式实现”来重做但简单明显的修复要跳过这条不要过度工程化呈现工作成果前先自我挑战一遍。这一条用“Balanced”做了刻意限定避免 AI 代理陷入无休止的重构。配合 AGENTS.md 中 “Minimal Impact / Prefer no code comment / 只解释 why 不解释 what” 的代码规范两条规则指向同一个工程审美改动小、注释少、意图清晰。核心原则最小影响Minimal ImpactCLAUDE.md 的 “Core Principles” 只有一条Minimal Impact——改动只应触碰必要的部分避免引入 bug。放在 Cypress 这样的 monorepo 中这条原则的约束力更强。从源码结构看lerna.json 的packages列表覆盖cli、packages/*32 个核心包、npm/*15 个公开发布包、tooling/*、system-tests、scripts而根 package.json 的全量test脚本会跨 20 个包执行yarn lerna exec yarn test --scopecypress --scopepackages/{...} --scopetooling/{...}。任何超出必要的跨包改动都会让验证成本构建、V8 快照、跨平台 CI成倍上升。这也是 CLAUDE.md 把工作约束单独成章、与行为原则分开表述的原因。工作约束Working Constraints三条硬性边界CLAUDE.md 的 “Working Constraints” 是全文中最“工程化”的三条每一条都直接对应仓库里的真实机制约束一Worktree 必须完整yarn安装禁止软链node_modulesWorktrees must use a fullyarninstall in the worktree. Do not symlinknode_modulesor packages back to another checkout.原因与 Cypress 的构建链路有关。本地执行yarn会触发 package.json 中的postinstallnode ./scripts/run-postInstall.js而 scripts/run-postInstall.js 在本地环境依次执行patch-package \ yarn workspace packages/server sync-cloud-validations \ yarn-deduplicate --strategyhighest \ lerna run rebuild-better-sqlite3 --scope packages/server \ yarn build \ yarn build-v8-snapshot-dev即应用 patches/ 下的 patch-package 补丁 → 去重依赖 →针对当前目录重编译 better-sqlite3 原生模块→ 全量构建 → 生成开发态 V8 快照。原生模块的编译产物与 V8 快照都依赖具体 check out 目录内的node_modules如果 worktree 软链回另一个 checkoutrebuild-better-sqlite3与 V8 快照就会和源码状态错位。AGENTS.md 的 “Cursor Cloud specific instructions” 也印证了这一点postinstall 耗时约 4–5 分钟构建 V8 快照生成若yarn中途被打断需要重新完整执行且yarn --frozen-lockfile失败时应回退到普通yarn。约束二E2E 与打包二进制集成测试不在沙箱运行E2E and packaged-binary integration tests do not run in the sandbox. When they are needed, provide the exact commands and ask the user to run them.这与 AGENTS.md 对 CI 的描述一致仓库的二进制级测试由 CircleCI 的多平台矩阵Linux x64/ARM64、macOS x64/ARM64、Windows执行二进制构建在 npm 发布后另行触发。AI 代理能做的是给出精确命令并请求用户执行而不是尝试在受限环境中自运行。system-tests/目录yarn test-system就是这套“针对已构建二进制的完整 E2E 测试套件”属于明确被排除在沙箱之外的那一类。约束三提交前必须本地通过三道关卡Before committing or pushing,yarn check-ts、yarn lint、relevant unit tests must pass locally.CI currently does not block expensive e2e jobs when these fail.这是全文信息密度最高的一句话它告诉 AI 代理CI 上昂贵的 E2E 任务不会因为类型检查/lint/单测失败而被阻断所以这三项只能由本地自觉保证。三个命令在根 package.json 中都有对应实现// 摘自 package.json scripts check-ts: yarn lerna run check-ts, // 各包级 TS 检查 lint: lerna run lint --no-bail --concurrency 2, // 全 monorepo lint并发 2、不中断 type-check: yarn lerna exec yarn type-check --scopetooling/system-tests node scripts/type_check, test: yarn lerna exec yarn test --scopecypress --scopepackages/{...} --scopetooling/{...}配套细节还有本项目不使用 Prettier格式化全部由 ESLint 强制AGENTS.md 明确指出.prettierignore排除了所有文件yarn lint:fix只会自动修复npm/下公开发布的cypress/*包范围代码风格基线单引号、无分号semi: never、2 空格缩进、多行尾逗号、禁止var、禁止console、类型导入必须用import type、测试中禁止.onlymocha/no-exclusive-tests、.skip必须带NOTE:/TODO:/FIXME:注释。验证闭环从原则到可执行命令把 CLAUDE.md 的“完成前验证”原则落到 Cypress 仓库实际的动作序列就是 AGENTS.md 命令表的子集。CLAUDE.md 要求“Run relevant tests only”而 AGENTS.md 恰好提供了按粒度递进的测试命令族# 只跑某个包的测试优先于裸 yarn test yarn test --scope packages/server # 指定单个 vitest spec 文件使用 vitest 的包 yarn workspace packages/config test -- path-to-spec # 用 glob 模式指定 vitest spec yarn workspace packages/net-stubbing test -- glob-pattern # 指定 mocha spec 文件使用 mocha 的包 yarn workspace packages/server test-unit -- path-to-spec # 按名称模式过滤 mocha 测试 yarn workspace packages/server test-unit -- --grep pattern # 类型检查与 lint yarn check-ts yarn lintAGENTS.md 还记录了两个“预期内失败”避免 AI 代理把它们误判为代码 bug 而反复返工packages/network等测试套件需要特权端口443在无特权容器里报 EACCES 属预期packages/config有 2 个测试断言cypressBinaryRoot包含cypress当工作区目录名不是cypress例如/workspace时会失败——这是已知的路径依赖问题不是代码缺陷。这类“环境噪音说明”正是 CLAUDE.md 式文档最有价值的部分它把一次性排查得到的经验固化下来直接服务于“Verification Before Done”原则中的“检查日志、判断失败原因”环节。环境与运行目标约束背后的事实底座CLAUDE.md 的约束能落地前提是环境事实清晰。AGENTS.md 的 “Prerequisites” 与 “Runtime targets” 章节提供了这些事实Node以.node-version为准当前为24.15.0用nvm use管理包管理器Yarn 1yarn1.22.22根 package.json 的packageManager字段与engines双重锁定禁用 npm/pnpmLerna作为 devDependency 安装由根脚本编排见 lerna.jsonElectron二进制构建时由packages/electron自动处理。“Runtime targets” 一节进一步划出了四类运行时及其各自最低 JS/Node API 版本线要求写代码前必须先确认目标文件跑在哪个运行时、所用 API 是否在该版本线之上且不能假设开发机 Node 版本开发工具 / gulp / 构建脚本——.node-version指定的 Node打包后的 Electron 主进程——根 package.json 中锁定的 Electron 版本所内嵌的 Node/V8配置/插件子进程packages/server 的lib/plugins/child/require_async_child.ts由ProjectConfigIpcfork与cypressCLIcli/——运行在用户的 Node上受 cli/package.json 的engines.node约束这条版本线最低是这类代码的约束项浏览器分发的 bundlepackages/app、packages/frontend-shared、packages/driver——受支持浏览器的最近 3 个大版本约束由于 Safari 大约每年才出一个大版本这是最保守的一条线。对 WebKit 而言Cypress 跑的是随playwright-webkit依赖捆绑的 WebKit而非用户系统的 Safari所以版本线跟随该依赖。周边文档链接CLAUDE.md / AGENTS.md 引用到的仓库文件CLAUDE.md 本身不直接引用文件但它引用的 AGENTS.md 构成了一个文档网络其中可追溯到的仓库文件包括CONTRIBUTING.md——PR 规范的事实来源包含决定下一个版本号的 semantic-release 标题前缀cli/CHANGELOG.md——面向用户的变更需在此追加条目写法见 guides/writing-the-cypress-changelog.md.github/PULL_REQUEST_TEMPLATE.md——PR 模板必须完整填写不相关章节写N/A而不是删除否则不予评审.circleci/AGENTS.md——说明何时要把分支加入 full-CI 白名单二进制测试、Windows 任务、v8 快照验证。CI/CD 层面的事实来自 AGENTS.md “CI/CD” 一节与 CLAUDE.md 约束二、三互为印证主 CI 为 CircleCI配置以模块化方式存放在.circleci/src/并编译为.circleci/packed/pipeline.ymlGitHub Actions 承担安全扫描Snyk、SBOM 生成、浏览器版本自动更新与 PR 校验所有 PR 目标基线分支是develop发布分支遵循release/X.Y.Zready-to-release聚合作业全绿之后npm-release才会执行外部贡献者 PR 需经approve-contributor-pr人工批准后才触发 CI。小结这份文档回答了什么问题问题CLAUDE.md 给出的答案AI 代理接到多步任务第一步做什么进入计划模式先写清规格原则 1上下文快满了怎么办探索与研究下放给子代理一任务一代理原则 2被用户纠正后如何避免再错更新最近的 CLAUDE.md写下防重犯规则原则 3什么时候可以说“完成了”证明它工作、diff 行为、通过 staff engineer 标准自审原则 4什么时候该重做而不是凑合非平凡且修复很 hack 时简单修复则跳过原则 5改动的边界在哪Minimal Impact 三条工作约束worktree 完整安装 / E2E 交还用户 / 三道本地关卡具体环境事实去哪查AGENTS.md引用链AGENTS.md 的 Prerequisites、Common Commands、Runtime targets、CI/CD对阅读者而言CLAUDE.md 的价值有两层对 AI 代理它是一份可直接执行的行为协议把“先计划、再并行、被纠正即沉淀、完成必验证、优雅有度”变成了硬性流程对人类开发者它反向暴露了 Cypress Monorepo 的工程红线——Yarn 1 Lerna 的构建链、postinstall 中 better-sqlite3 重编译与 V8 快照生成、check-ts/lint/单测作为提交前最后一道人工闸门、以及 CI 多平台矩阵与develop基线的发布流程。顺藤摸瓜读完AGENTS.md引用链即可把这套“AI 工作流规范”与仓库的真实构建、测试、CI 体系一一对上号。【免费下载链接】cypressFast, easy and reliable testing for anything that runs in a browser.项目地址: https://gitcode.com/GitHub_Trending/cy/cypress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考