让 Claude 按项目组件库正确写界面

Claude Code 能写出看起来像 shadcn/ui 的代码，却未必用对项目里那一版组件。再接入第三方 registry，同名文件、不同 props 和安装工具的差异，会让「能生成」与「能运行」之间出现更多问题。

原文的结论是：可靠的配置需要 MCP、skill、registry 清单、项目规则和 CLI 各司其职。它最有用的部分，是作者用实际冲突说明了为什么只接一个 MCP 还不够。以下测试基于作者在 2026 年 10 月使用的 shadcn 4.21.4、skills CLI 1.7.1 和 Wingo UI 1.7.0，不能直接当成所有版本的行为保证。

MCP 负责找组件，谁来保证装对、用对？

作者把配置拆成五部分：shadcn MCP 查询真实组件仓库，skill 提供项目上下文，components.json 登记 registry，CLAUDE.md 规定使用边界，CLI 最后写文件。

先在项目根目录连接 MCP：

npx shadcn@latest mcp init --client claude

要注意 --client claude：作者测试中，这会写入 .mcp.json，并把 shadcn 安装为开发依赖。重启 Claude Code 后，用 /mcp 检查连接。项目配置可以提交到仓库，团队成员各自批准一次；个人配置则可用 claude mcp add shadcn -- npx shadcn@latest mcp，默认进入 local scope。

接入 MCP，只解决了模型从哪里找信息，没有自动解决它该怎么做。

shadcn 4.21.4 提供七个只读工具，能列出 registry、搜索条目、查看元信息、取示例、生成安装命令和获取检查清单。真正安装仍要执行 Bash。作者还发现，view_items_in_registries 对测试的 Button 和 Dialog 没有返回 props 或源码；示例依赖仓库发布 -demo 条目，第三方仓库未必提供。

因此，搜到组件之后，还得读安装文件或组件库自己的文档。库自己的 MCP 可以补充 API 信息，例如 Wingo UI 的 get_component，但这是可选的第六部分。

skill 则通过 npx skills add shadcn/ui --agent claude-code 安装。作者得到 shadcn、migrate-radix-to-base 两个 skill，以及 skills-lock.json。19.5 KB 的 SKILL.md 不会一开始全部进入上下文，触发 UI 任务后才加载；它会执行 npx shadcn@latest info --json 获取框架、Tailwind 版本、别名和已安装组件。

这里还有个权限细节：原文称 skill 的 allowed-tools 会放行该轮中的 npx shadcn@latest 命令，包含 add --overwrite。所以「安装通常会询问」不能替代明确的覆盖规则。

两个 registry 共存，先解决目录和 API 归属

第二个 registry 要登记在 components.json。Wingo UI 的公开地址模板是 https://wingo-ui.com/r/{name}.json；私有访问可配置 Authorization: Bearer ${WINGO_UI_API_KEY}。

作者确认 shadcn CLI 能从环境变量或 .env.local 读取密钥，但 Claude Code 展开 MCP 配置中的变量，依赖启动时的环境。两处能读到变量，不能只验证一处。

没有密钥时，也别提前放上 header 配置。作者测试中，MISSING_ENV_VARS 会让跨 registry 搜索整体失败，连公开的 shadcn 结果也不返回。搜索本身还可能很宽：login 在两个仓库里命中 173 项，单独 @shadcn 为 7 项，因此示例把 limit 设为 4。4.21.4 另有安装命令显示成 [object Promise] 的问题，需要调用 get_add_command_for_items 取得真实命令。

更棘手的是文件冲突。

作者向已有 shadcn Button 的项目安装 Wingo Dialog，Wingo CLI 保留了原来的 components/ui/button.tsx，同时写入 Dialog 和 Drawer，结果类型检查失败：后两者使用 radius="full"，shadcn Button 没有这个 prop。

覆盖也不行。shadcn 的 variant="default"、"secondary"、"destructive"，不能直接用于 Wingo Button。后者使用 solid、soft、outline、ghost、link，危险状态通过 tone="danger" 表达。

作者的处理是运行 npx wingo-ui@latest init，再把 wingo-ui.json 的 aliases.ui 改为 @/components/wingo。随后 npx wingo-ui@latest add dialog 会把相关文件装进独立目录，并改写内部 import。

使用库自己的 CLI 还有样式原因：作者称其 init 会合并设计 token，add 会补 Drawer 过渡样式，而 shadcn 格式的 registry JSON 不携带这些 token。缺少它们，z-modal、shadow-modal 即使出现在代码里，也没有对应效果。

CLAUDE.md 要写清边界，提示词要指定来源

官方 shadcn skill 的规则适用于 shadcn/ui，却不能自动推广给所有 registry。

例如，它会先运行 npx shadcn@latest docs <component>，但这个命令只认识 shadcn/ui；查询 docs @wingo-ui/dialog，作者得到的是找不到组件。它还指导模型用 FieldGroup、Field 组织表单，按钮图标使用 data-icon，加载状态通过 Spinner 和 disabled 组合。

这些做法放到 Wingo UI 未必合适。其 Button 已有 loading，负责替换标签、保持宽度、设置 aria-busy 并忽略点击，再手写一套容易重复。

所以 CLAUDE.md 至少应说明：components/ui 属于谁，components/wingo 属于谁；分别用什么工具查询、什么 CLI 安装和更新；shadcn skill 与 shadcn docs 只约束哪些文件；覆盖前必须询问，更新前先展示 diff 或发布说明。作者还要求只用语义 token，并检查 390px、1440px 下的明暗主题。

提示词也要延续这个边界：先指定 @shadcn 或 @wingo-ui，搜索候选，再安装，最后读取实际 API、做类型检查与 lint。get_audit_checklist 只有六条通用检查，真正发现错误 prop 的仍是类型检查。

对于完整页面 block，还要追踪默认行为。Wingo Login Page 自带模拟 handler，漏接 onVerifyCode 时，验证码视图仍会接受 123456。页面看起来能走通，不代表认证已经接入。

更新同样应先看报告。Wingo 的操作示例是：

npx wingo-ui@latest outdated        # installed items vs the latest release
npx wingo-ui@latest diff dialog     # your file vs upstream
npx wingo-ui@latest update dialog   # 3-way merge that keeps your edits

注意最后一行的 update dialog：作者称它依靠安装时保存的原始副本做三方合并。shadcn 对应的 npx shadcn@latest add button --diff 用于查看差异，--overwrite 则会连本地修改一起替换，两套更新方式不能混用。

我的判断

我认同作者把「查找、约束、写入」拆开的思路。对前端项目而言，组件同名并不代表 API 相同，文件归属比笼统地告诉模型「遵循最佳实践」更有价值。

但这也是 Wingo UI 作者介绍自家产品的文章。文件冲突、环境变量失败、类型检查，以及针对 1.7.0 的示例验证，都有具体观察；整套配置能让 AI 少犯多少错、比其他方案节省多少时间，作者没有给对照数据，属于经验之谈。

独立目录是合理选择，但不能隔离全局 CSS 和设计 token，原文的安装流程恰好会修改 app/globals.css。而「registry 有就绝不手写」也偏强，团队仍需判断依赖、维护成本和实际需求。只使用 shadcn/ui 的项目，先接 MCP、skill 并写清安装与覆盖规则即可，没必要为了配置完整而增加第二套库。

能拿来做什么

• 给现有 React 项目补一段组件归属规则，明确目录、import 路径和安装命令，让 Claude 根据实际导入文件读取 API。
• 把 UI 任务拆成搜索与实现两步，先要求列出 registry、候选组件和安装命令，再进入代码修改。
• 接入登录 block 时逐个核对 on* handler，把 onSignIn、onVerifyCode 接到真实接口，并列出仍保留模拟默认值的回调。
• 更新前先索取 diff 和发布说明，按组件来源使用对应 CLI，完成后运行类型检查、lint，并验证移动端与明暗主题。