shadcn/lint 教程：shadcn 官方 Agent 优先设计系统 Linter，让 AI 编码遵守你的 UI 规范

📌 项目地址：github.com/shadcn-ui/lint | 星数：1,722+ | 协议：MIT | 语言：TypeScript | 要求：Tailwind v4 · ESLint 或 Oxlint

📋 项目简介

当 AI 编码 Agent 批量生成界面代码时，最头疼的不是它写不对，而是它不守规矩：给 Button 乱加 padding、随意改组件形状、把设计系统当摆设。shadcn 作者在 2026 年 9 月开源了官方答案：@shadcn/lint——一个 agent-first（Agent 优先）的 Tailwind 设计系统 linter。核心思路一句话：你定义设计系统里什么允许、什么禁止，Agent 违反规则时，报错本身就是一份基于你的组件、变体和主题写成的修复指南。项目发布两周即收获 1,700+ 星，同时提供 ESLint 和 Oxlint 支持，兼容任意 Tailwind v4 项目（不要求用 shadcn/ui）。如果你在给团队搭 Agent 编码工作流，这类"约束 Agent 输出"的配套工具和FrontierAgent运行时一样值得研究。

💡 为什么 TypeScript 类型管不住 AI，而它能

README 里给了一个精准对比。假设 Button 组件允许外部设置 margin 和 width，但 padding 由组件自己控制。用 TypeScript 可以约束 style prop：

<Button style={{ padding: 16 }}>Submit</Button>
// TS2353: 'padding' does not exist in type 'Pick<CSSProperties, "margin" | "width">'

规则生效了，但这条报错只告诉 Agent"padding 不行"，没告诉它该怎么调整尺寸。换成 @shadcn/lint，同样的规则输出变成：

"p-4" is not allowed on <Button>: <Button> owns its spacing.
Use a size (sm, lg), or margin here or gap on the parent for space around it.
Add a size in components/ui/button.tsx only if the design explicitly calls for one.

报错里包含三段信息：规则原因（Button 拥有自己的间距）、替代方案（用 size 变体或父级 gap）、例外路径（确实需要新尺寸去哪个文件加）。这就是 agent-first 的含义——把设计系统的"部落知识"编码进诊断信息，让 Agent 自我修正而不是反复试错。

🚀 快速上手

官方推荐的安装方式就是给编码 Agent 发一段提示词：

Read https://github.com/shadcn-ui/lint/blob/main/SETUP.md
and set up @shadcn/lint in this project.

Agent 读完 SETUP.md 会自己完成安装与配置。手动配置的核心是两块：

// eslint.config.js 核心配置
{
  "settings": {
    "shadcn": { "ui": "./components/ui" }  // 指向你的组件目录
  },
  "rules": {
    "shadcn/no-restyle": ["error", {
      "allow": ["layout"],
      "contracts": [
        { "pattern": "^Button$", "allow": ["w-full", "mt-*", "mb-*"] }
      ]
    }]
  }
}

shadcn/no-restyle 是旗舰规则：通过 contracts 声明每个组件的契约——Button 只允许 w-full 和 margin 类，其余样式类一律报错。配置不改组件 API，纯声明式，无需重构现有设计系统。

🏢 Monorepo 场景

共享组件库的团队会遇到典型问题：组件源码目录里改样式是合法的，应用目录里不允许。用 ESLint 的 overrides 解决：

"overrides": [{
  "files": ["packages/ui/src/components/**"],
  "rules": { "shadcn/no-restyle": "off" }
}]

linter 会通过 TypeScript paths 和 package exports 解析各应用引用的组件——只要每个应用的 components.json 已指向共享 UI 包，可以省略 settings.shadcn.ui，各应用保留自己的主题配置。

✅ 适用与注意

• 适合：用 AI Agent 写 Tailwind 界面的团队（收益立竿见影）；多人协作想统一设计规范；shadcn/ui 用户（官方同源）
• 注意：项目 2026-09-02 创建、迭代很快，规则集还在扩充期，锁定版本使用；Tailwind v3 项目需先升级

把设计规范变成 Agent 可执行的约束，再配合记忆系统让它跨会话记住项目约定（可参考agent-memory长期记忆运行时教程），一套"懂规矩的 AI 前端工程师"就成型了。