React Router 仓库 AI 协作开发指南CLAUDE.md 与 AGENTS.md 的项目指令体系【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router本文以 CLAUDE.md 为核心解析 React Router 官方仓库如何为 AI 编码代理设计一套“会话启动协议 单一事实来源”的机器可读开发规范。读完你能掌握该仓库的构建与测试命令体系、五种运行模式Declarative/Data/Framework/RSC Data/RSC Framework的界定方法、pnpm monorepo 的包结构以及单元测试与 Playwright 集成测试的分层策略从而在贡献代码或让 Agent 参与开发时做到“不猜命令、不猜模式、不猜路径”。CLAUDE.md面向 Agent 的会话启动协议CLAUDE.md 是 React Router 仓库根目录下专门写给 AI 编码代理以 Claude Code 为代表的指令入口。它的正文很短但定义了三条硬性规则会话启动Session Start每次会话开始代理**必须REQUIRED**读取 AGENTS.md。CLAUDE.md 明确指出 AGENTS.md 包含项目架构与关键文件、五种 React Router 模式、构建/测试命令Jest 单元测试、--project chromium的 Playwright 集成测试、测试模式与惯例、文档指南。Skills 符号链接如果仓库中存在 .agents/skills 目录需要将其中的 skills 软链到.claude/skills以便 Claude 能发现并使用这些技能。该目录被 git 忽略目的是让“规范化技能canonical skills”统一维护在.agents/skills下避免多份副本。工作中随时查阅During Work凡是需要运行测试/构建、判断某个功能适用于哪种模式、定位关键文件、理解测试模式时一律查阅 AGENTS.md禁止凭猜测执行命令。这套设计体现了一个清晰的工程原则入口文件只做“路由”不做“内容”。CLAUDE.md 是协议层AGENTS.md 是内容层。当前仓库中.agents/skills/下确实维护了react-router、fix-bug、implement-rfc、create-pr、finish-line、prepare-release-notes等技能目录见 .agents/skills且 .gitignore 末尾显式忽略了.claude/skills与.claude/settings.local.json与 CLAUDE.md 描述的符号链接约定完全对应。更值得注意的是这套 skills 体系不止服务于贡献者本机create-react-router包的打包脚本 copy-agent-skills.mjs 会在prepack阶段把.agents/skills/react-router复制到dist/agent-skills/react-router/随 CLI 包一起发布——也就是说用户新建 React Router 应用时也会携带这份技能定义让任何项目的 Agent 都能按官方模式识别规则Framework/Data/Declarative/RSC来处理应用。命令体系构建、测试、文档生成AGENTS.md 的 Commands 一节给出了仓库级命令全部基于 pnpm workspace根 package.json 声明packageManager: pnpm11.7.0、engines.node 22.22.0用途命令构建全部包pnpm build等价pnpm run --filter./packages/**/* build构建单个包pnpm run --filter package buildJest 单元测试全量pnpm testJest 单元测试单包/单文件/按名pnpm test packages/package/、pnpm test packages/react-router/__tests__/router/fetchers-test.ts、pnpm test -- -t action fetchPlaywright 集成测试含构建pnpm test:integration --project chromiumPlaywright 集成测试仅测试pnpm test:integration:run --project chromium集成测试单文件/按名pnpm test:integration:run integration/middleware-test.ts --project chromium、pnpm test:integration:run --project chromium -g middleware类型检查 / Lintpnpm run typecheck、pnpm run lintAPI 文档生成pnpm run docs从 JSDoc 再生成docs/api/类型生成仅 Framework Modepnpm run typegen清理pnpm run clean即git clean -fdX对照根 package.json 中的 scripts 定义可以确认这些命令的底层实现test实际以node --experimental-vm-modules启动 JestESM 模式test:integration会先执行pretest:integration: pnpm build再运行playwright test --config ./integration/playwright.config.ts测试结束后posttest:integration:run会调用integration/helpers/cleanup.mjs清理 fixture 残留。AGENTS.md 因此给出两条配套约定集成测试始终使用chromium项目除非明确说明仅在首次运行或改动过packages/源码后才需要重新构建纯测试文件改动不需要。五种模式任何功能改动先判定适用范围AGENTS.md 最强调的一条规则是“五种互不相同的模式Declarative、Data、Framework、RSC Dataunstable、RSC Frameworkunstable。永远先识别一个功能适用于哪些模式。”DeclarativeBrowserRouter、Routes、Route组件式路由。DatacreateBrowserRouter()配合loader/action与RouterProvider。FrameworkVite 插件 routes.ts Route Module API路由模块导出loader、action、default等 类型生成 SSR/SPA。RSC DataunstableRSC 运行时 API手工 bundler 配置运行时路由配置。RSC FrameworkunstableFramework Mode 加上unstable_reactRouterRSCVite 插件。两种 RSC 模式的差异在 AGENTS.md 中有专门小节RSC Framework 使用unstable_reactRouterRSC插件与vitejs/plugin-rsc入口点与打包格式不同RSC Data 则是手工 bundler、运行时路由配置通常放在src/routes.ts、使用unstable_RSCRouteConfig与不同的运行时 API测试走 integration/rsc/ 下的setupRscTest。仓库的目录结构印证了这一划分核心包 packages/react-router 同时包含lib/router/模式无关的路由器、lib/dom/、lib/components.tsx、lib/hooks.tsx声明式/Data 共用的 React 绑定以及独立的lib/rsc/目录RSC 运行时工具链包 packages/react-router-dev 则区分了 vite/plugin.tsFramework与 vite/rsc/plugin.tsRSC Framework两套 Vite 插件外加 typegen/ 目录。.agents/skills/react-router/SKILL.md 进一步给出了“模式识别”的操作清单例如看到react-router.config.ts、app/routes.ts、types导入即判定为 Framework Mode看到createBrowserRouter判定为 Data Mode看到unstable_RSCRouteConfig判定为 RSC——这与 AGENTS.md 的模式定义一一对应。Monorepo 架构与关键文件AGENTS.md 的 Architecture 一节说明仓库是 pnpm workspace monorepo包位于packages/。其 Key Files 表格给出了各模块的定位结合仓库实际目录可以逐一验证目的位置仓库根相对路径Router 核心packages/react-router/lib/router/router.tsReact APIpackages/react-router/lib/components.tsx、packages/react-router/lib/hooks.tsxVite 插件Frameworkpackages/react-router-dev/vite/plugin.tsRSC Vite 插件packages/react-router-dev/vite/rsc/plugin.ts类型生成packages/react-router-dev/typegen/单元测试packages/react-router/tests/集成测试integration/决策文档decisions/关键包职责react-router承载全部模式的核心实现react-router/dev是 Framework 工具链Vite 插件 类型生成react-router/node、react-router/cloudflare、react-router/express是三套服务端适配层react-router/serve提供 Framework Mode 的最小服务器react-router/fs-routes提供文件系统路由能力flatRoutes()。测试分层Jest 单元测试与 Playwright 集成测试AGENTS.md 的 Testing 一节明确了两套测试的分工边界单元测试packages/react-router/tests/使用 Jest覆盖“纯路由逻辑、纯服务端运行时行为、路由器状态、React 组件行为”无需构建。四条常用命令pnpm test # 全部包 pnpm test packages/react-router/ # 单个包 pnpm test packages/react-router/__tests__/router/fetchers-test.ts # 单个文件 pnpm test -- -t action fetch # 按名称匹配集成测试integration/使用 Playwright覆盖 Vite 插件、构建流水线、SSR/水合、RSC、类型生成等端到端行为。该目录包含 80 余个*-test.ts文件如 middleware-test.ts、single-fetch-test.ts并配套 playwright.config.ts 与 fixture 基建。组织惯例为通过createFixture()→createAppFixture()→PlaywrightFixture三层创建测试应用见 integration/helpers/ 下的create-fixture.ts、fixtures.ts、playwright-fixture.ts模板位于 integration/helpers/如vite-7-template/、vite-8-template/、rsc-vite/、rsc-vite-framework/、vite-plugin-cloudflare-template/共享行为要跨多个模板迭代测试例如[vite-7-template, rsc-vite-framework]RSC 特性只针对 RSC 模板测试引入 future flag 时必须同时测试开启与关闭两种状态。Framework Mode 的 routes.ts 与文件系统路由约定AGENTS.md 的 routes.ts 一节规定Framework Mode 在app/目录使用routes.ts绝大多数测试采用flatRoutes()做文件系统路由// app/routes.ts import { type RouteConfig } from react-router/dev/routes; import { flatRoutes } from react-router/fs-routes; export default flatRoutes() satisfies RouteConfig;文件系统约定app/routes/下_index.tsx→/索引路由about.tsx→/aboutblog.$slug.tsx→/blog/:slugURL 参数settings.profile.tsx→/settings/profile.产生嵌套_layout.tsx→ 无路径的布局路由pathless layout也可以手写路由配置替代flatRoutes()import { index, route, layout } from react-router/dev/routes; export default [ index(./home.tsx), route(about, ./about.tsx), layout(./auth-layout.tsx, [route(login, ./login.tsx)]), ];仓库中这些约定有真实落地示例playground/framework/ 与 playground/rsc-vite-framework/ 均包含app/与react-router.config.ts文件系统路由的实现来自react-router/fs-routes包packages/react-router-fs-routes/flatRoutes.ts集成测试 fs-routes-test.ts 则验证了完整路由表生成行为。文档、Future Flags 与变更文件规范AGENTS.md 的 Documentation 一节给出四条硬性约定不要手改生成文件docs/api/由 JSDoc 生成pnpm run docs底层为 TypeDoc scripts/docs.ts.react-router/types/由 typegen 生成。修改 API 文档的正确姿势是编辑 packages/react-router/lib/ 中的 JSDoc 后重新生成。模式标注每篇文档需要[MODES: framework, data, declarative]标记供人类和 Agent 判断文档是否适用于当前应用模式.agents/skills/react-router/SKILL.md中明确说明只应用模式标记匹配的文档。不稳定特性函数名前缀unstable_、frontmatter 中加unstable: true并附警告块。Future flags 与 Unstable flags 的区分vX_*形式的 future flags 用于下一个大版本的稳定破坏性变更unstable_*则可能随时变动future flags 必须开/关双态测试且“不要在没有 flag 的情况下破坏现有行为”。Change Files 一节规定凡影响用户的改动须在packages/package/.changes/type.unique-meaningful-name.md创建变更文件type取patch/minor/major/unstable若迭代一个尚未发布的改动应更新既有变更文件而不是新建。文件格式为“一句话概述 可选的补充细节列表”。配套的发布脚本位于 scripts/changes/add.ts、pr.ts、version.ts、publish.ts、validate.ts与 DEVELOPMENT.md 描述的自动发布流程release.yml工作流检测 change files → 生成版本化发布分支 → 发布并打 tag相衔接。Branching 一节定义了分支模型main为活跃开发分支v7/v6为对应版本的维护分支代码与文档改动都从main拉分支。License 一节则声明贡献即接受 MIT 授权对应仓库根 LICENSE.md。小结为什么这套“双层指令”值得借鉴React Router 仓库把开发者文档CONTRIBUTING.md、DEVELOPMENT.md与 Agent 指令做了明确分工CLAUDE.md 仅 26 行负责“何时必须读什么、如何装配 skills、禁止猜测命令”三条元规则AGENTS.md 承载全部事实内容——命令表、模式划分、包结构、测试分工、routes.ts约定、文档与变更文件规范、分支策略且所有关键文件路径都在仓库内可逐一验证。对 LLM 与搜索引擎而言这种“入口协议 单一事实来源 模式标记[MODES: ...] skills 随包分发”的结构让 Agent 在任意会话中都能以最低歧义地定位命令、模式与文件是大型 monorepo 引入 AI 协作时可直接参考的组织范式。【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考