多款编码助手如何共用 React 项目规则

dev.to · AI#规则文件#React#编码助手

Editor brief · 编辑速览

文章建议以 AGENTS.md 集中维护公共规则，通过 CLAUDE.md 引用，并将目录专属要求放入各工具的路径规则。针对 React 与 Tailwind 项目，强调规则简短可验证、长文档使用链接，组件默认值落实到代码。

文章思维导图

Knowledge map

拖拽缩放

AI deep read

AI 深度解读

同一个 React 项目，Cursor、Claude Code 和 Codex 各有一份规则，最后连按钮尺寸都能写出三套。作者给出的办法是：把共享约定集中到 AGENTS.md，用工具专属文件处理加载和目录差异，再把组件默认值、检查脚本放回代码。

这篇值得读的地方，是把「规则写在哪」和「规则如何生效」连了起来。不过，文中的工具行为以作者核对的 2026 年 10 月文档为准，Wingo UI 的用法也带有自家组件库的前提，不能全部照搬。

一份共享规则，为什么还需要 CLAUDE.md

AGENTS.md 是工具中立的 Markdown 指令文件，没有必填字段。原文称它由 Linux Foundation 下的 Agentic AI Foundation 维护，已有超过 60,000 个开源项目使用。但格式通用，不代表各工具的加载方式相同。

最容易踩坑的是 Claude Code。按原文记录，从 v2.1.277 起，它默认可以读取 AGENTS.md，条件是当前目录及上级目录没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。个人配置 ~/.claude/CLAUDE.md 和 .claude/rules/ 不参与这项判断。

因此，队友加一个存私人笔记的 CLAUDE.local.md，就可能让自己会话里的共享规则停止加载。可以用 /memory 查看实际加载结果，也可以在 /config 中把 Project instructions 设为 claude-md-and-agents-md。

作者选择显式导入，让 CLAUDE.md 负责接入共享规则，并保留 Claude 专用要求：

@AGENTS.md

## Claude Code only

- Use plan mode before you change more than one file in `components/ui`.

关键是第一行 @AGENTS.md。原文称，这也能覆盖旧版本、读取 AGENTS.md 的内置插件被关闭等情况。Claude 的 @path 导入最多支持四跳；Codex 则没有文档化的导入语法。

另外两个工具也有边界。Codex 启动时一次性建立指令链，从 Git 根目录走到启动目录，还会使用 ~/.codex 中的全局指令。因此，放在 components/ui/AGENTS.md 的内容，不会因为之后编辑该目录就自动进入指令链。Cursor 会组合父子目录的 AGENTS.md，但规则只作用于 Agent，不影响 Cursor Tab。

作者还称，Next.js 16.3 及之后的 next dev，检测到编程代理且没有受管区块时，会生成相应文件；create-next-app 也会创建两者。AGENTS.md 的受管区块指向 node_modules/next/dist/docs/，CLAUDE.md 写入 @AGENTS.md。区块外的文字会保留，next.config.ts 中的 agentRules: false 可以关闭生成。

规则要告诉代理去哪里查，而不是复制一份组件文档

作者自己的 AGENTS.md 是 68 行、约 14 KB，包含 Next.js 受管区块。它主要回答几个问题：组件在哪、如何查当前接口、设计令牌怎么用、完成前运行什么检查，以及哪些操作需要先询问。

示例技术栈是 Next.js 16 App Router、React 19、Tailwind CSS v4 和 TypeScript strict。组件位于 components/ui，版本记录在 wingo-ui.json。代理应先通过 MCP 工具或 npx wingo-ui@latest search <words> 搜索，再用 get_component 或 npx wingo-ui@latest info <slug> 读取当前接口，安装则用 npx wingo-ui@latest add <slug...>。

这里的分工很实用：规则保存稳定约定，CLI 或 MCP 提供随版本变化的事实。把完整 props 表抄进规则，下一次升级就可能产生两份互相冲突的答案。

设计要求也要能直接检查。例如浮层使用 bg-surface，正文使用 text-foreground，边框使用 border-border；禁止应用代码使用十六进制、rgb 和 bg-blue-500 等调色板颜色。Wingo UI 不采用 bg-accent、bg-secondary，替代方式是 variant="soft" 或 bg-foreground/5。这针对的是代理容易沿用 shadcn/ui 习惯的问题，并非 Tailwind 通用禁令。

长文档则按需读取。作者的 docs/DESIGN.md 有 614 行、约 52 KB，若直接导入，每次会话都要承担这部分上下文。Codex 默认全部指令文件合计只有 32 KiB，可用 project_doc_max_bytes 调整；Claude 建议每份文件少于 200 行，Cursor 建议每份规则少于 500 行。

原文引用的 Vercel 评测中，一个 8 KB 文档索引放进 AGENTS.md 后，Next.js 16 测试通过率达到 100%；明确要求使用 skill 时是 79%，没有文档时是 53%。未明确要求时，56% 的案例没有调用 skill。这支持「关键入口应直接可见」，还不足以证明所有任务里 AGENTS.md 都优于 skill。

默认值放进代码，目录例外再交给专属规则

规则是上下文，组件默认值才是实际执行的行为。

作者用 UIProvider 集中设置 Button 的尺寸和圆角，让普通调用自然继承统一外观：

// app/layout.tsx
import type { ReactNode } from "react";
import { UIProvider } from "@/lib/ui-config";
import "./globals.css";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <UIProvider locale="en-US" defaults={{ button: { size: "lg", radius: "full" } }}>
          {children}
        </UIProvider>
      </body>
    </html>
  );
}

要看的是 defaults：Wingo UI 通过 useDefaults 按组件的 data-slot 名称读取配置，优先级是显式 props、Provider、组件自身默认值。单个按钮仍可用 size="sm" 覆盖。原文演示还设置了品牌色，但正式应用建议保持 neutral，只给页面主操作加 tone="brand"。相关配置可用 npx wingo-ui@latest add ui-config 安装。

只有编辑组件源码时才需要的约束，可以放进目录规则。Cursor 使用 .cursor/rules/ui-kit.mdc，普通 .md 会被忽略；globs: ["components/ui/**/*.tsx"] 配合 alwaysApply: false，在匹配文件进入上下文时附加规则。alwaysApply: true 表示每次加载，只有 description 时由代理判断，没有这些字段时通过 @ 提及加载。

Claude 对应文件是 .claude/rules/ui-kit.md，路径范围用 paths 声明。规则正文可以共用：保留 cn()、className、data-slot、许可证注释和 useDefaults("<slot>", props)；React 19 中 ref 是普通 prop，不要额外加 forwardRef；修改前执行 npx wingo-ui@latest diff <slug>。

必须守住的限制还得进入检查。原文提供的脚本通过 git grep --untracked -nE 查找硬编码颜色，并排除 components/ui、components/blocks、components/templates，因为这些库源码含有可覆盖的颜色默认值。--untracked 能覆盖代理刚创建、尚未加入 Git 的文件。

作者将它接到 npm run check:tokens，与 npx tsc --noEmit、npx eslint <files you changed> 一起执行。覆盖文件之类的操作，则交给 PreToolUse hook 或权限设置。

我的判断

我认同把共享规则、动态资料和代码约束分开。尤其是把重复出现的尺寸、圆角、加载态放进组件，比不断补充提示词更容易维护。单一共享文件也能减少多工具之间的指令冲突。

但原文没有给出团队采用前后的返工率、令牌成本或设计一致性对照。这部分属于作者的维护经验，不能把引用的 Next.js 评测当成整套方案的效果证明。

UIProvider 也不是不可绕过的保障。代理仍能写原生按钮、显式覆盖 props，或删掉 useDefaults。它降低了正确实现的成本，真正的边界仍依赖检查和评审。颜色正则同样只能发现部分问题，不能完整理解 JSX、CSS 和动态类名。

导入优于符号链接的建议则很具体：ln -s AGENTS.md CLAUDE.md 在 Windows 上受 core.symlinks 影响，可能被检出成普通文本文件。跨平台团队采用 @AGENTS.md 更省维护。不过，不同版本的加载行为仍应以本机会话实际结果为准。

能拿来做什么

先合并仓库里互相重复的公共规则，再添加以 @AGENTS.md 开头的 CLAUDE.md，并通过 /memory 检查 Claude 的加载结果；使用 Codex 时同时确认启动目录。
给 React 项目写清组件位置、接口查询命令和完成检查，不要复制整份组件清单。把反复传递的默认 props 收到现有主题层或组件封装中。
为 components/ui 的源码编辑单独添加路径规则，只保留容易破坏组件契约的约束。原文建议同类错误第二次出现后再补规则，避免提前堆满假想问题。
将设计令牌检查接入 CI，并核对扫描路径与排除目录。界面验收可以采用示例中的 390px、1440px 和明暗主题组合；768px 以下自动转底部面板的行为，则只适用于具备该能力的组件。