我给 Cursor 写了一个项目级 Skill，让 AI 直接产出符合团队规范的代码

Qlly
0 阅读9分钟

起因

我们的项目是一个中大型的企业管理平台，React + antd 6.x + ProComponents + SCSS Modules 技术栈。经过长时间迭代，团队沉淀了一套完整的工程体系：170 多个 SCSS 设计变量、4 份代码规范文件、8 个 Selector 组件、14 个表格列工厂函数、13 个表单项工厂函数。

团队用无数次 Code Review 磨出来的东西。

但我们开始大量用 Cursor 做 AI 辅助开发后，发现 AI 根本不知道这些规范的存在。

到底有多痛？

让 AI "帮我做一个任务列表页面"，它写出来的代码大概长这样：

const TaskTable: React.FC<Props> = ({ data }) => {         // React.FC 项目禁止使用
  const [loading, setLoading] = useState(false);             // ProTable 能自动管理
  const [tableData, setTableData] = useState([]);

  useEffect(() => { fetchData(); }, []);                     // 完全多余

  return (
    <div style={{ padding: 24, background: '#f8fafc' }}>    {/* inline style 项目禁止 */}
      <Table
        columns={[
          { title: '进度', render: (_, r) =>                 // 有 createProgressColumn
            <Progress percent={r.progress * 100} /> },
          { title: '时间', render: (v) =>                    // 有 createTimestampColumn
            dayjs(v * 1000).format('YYYY-MM-DD HH:mm') },
        ]}
        dataSource={tableData}
        loading={loading}
      />
    </div>
  );
};

一个页面，七八个规范问题。然后开发者要花半小时甚至更久去修正——把 React.FC 改掉，把 inline style 搬到 SCSS Modules，把硬编码颜色换成变量，把手写列定义换成工厂函数，把 useState/useEffect 换成 ProTable 的 request 属性。

做了一段时间之后，我开始觉得不对劲：这些修正工作高度重复，而且问题的根源很清楚——AI 不知道我们项目的规矩。

那能不能让 AI 一开始就知道？

思路：给 AI 一个"项目适配层"

Cursor 有一套 Skill 机制，本质上就是给 AI 加载一份指令文件。市面上已有通用的设计类 Skill（我们项目里也装了一个叫 ui-ux-pro-max 的，内置 700 多条设计规则），但通用 Skill 的问题是——它不知道你的项目用什么技术栈，不知道你有哪些组件可以复用，不知道你的 SCSS 变量叫什么名字。

它会推荐你用 Tailwind、Google Fonts、自定义组件。而你的项目用的是 antd + SCSS Modules + 工厂函数。

所以我做了一个适配层：在通用设计知识和项目实际规范之间搭一座桥。

整个架构是这样的：

开发者："帮我做一个风险评估列表页"
        │
        ▼
┌─── 项目专属 Skill ────────────────────────┐
│  1. 识别需求（列表页、管理后台场景）          │
│  2. 从通用知识库搜索设计建议                 │
│  3. 翻译成项目规范（Token 映射 + 组件选择）   │
│  4. 产出代码（工厂函数 + SCSS Modules）     │
│  5. 对照检查清单自查                        │
└──────┬──────────┬──────────┬─────────────┘
       │          │          │
  通用设计库   antd API    代码规范
  (700+规则)   (v6查询)    (审查清单)

通用知识负责回答"列表页一般怎么设计"，项目适配层负责把答案翻译成"我们项目里列表页该怎么写"。

具体做了什么

最终产出了一个 Skill 目录，总计约 1300 行，分为四个部分。

1. 主指令文件 SKILL.md

这是 AI 读到的第一份文件，约 280 行。它定义了 5 步工作流程，以及几张最关键的映射表。

Token 映射表——告诉 AI "你想用的那个颜色/间距/圆角，在我们项目里叫什么"：

你想表达的我们项目里写
主色$primary-color
页面间距$spacing-md
卡片圆角$border-radius-lg
按钮 hover 过渡$animation-duration-fast + $ease-base-out
页面背景$background-color-base

组件选择表——告诉 AI "你想手写的那个组件，我们已经有了"：

你想写的我们已有的
<Table> + useState + useEffect<ProTable> + request
手写列 { title, render }createTimestampColumn() 等工厂函数
<Select> + 搜索逻辑<UserSelector> 组件
手管 Modal open/close/datauseModal() Hook
style={{ marginBottom: 24 }}className={styles.section}

还有一份 14 项规范检查清单，AI 在产出代码前会逐项自查。

2. 设计 Token 快查表

约 330 行，完整收录了项目 170 多个 SCSS 变量。按颜色、间距、圆角、阴影、字体、布局、动画分类，附带使用场景说明。

同时包含了 antd ConfigProvider 的主题配置摘要，以及 SCSS 变量与 antd Token 的对应关系。

这份文件我觉得挺有意思——它不只是给 AI 看的，团队新人拿来查 Token 也很方便。之前大家要自己去 variables.scss 里翻，170 行变量混在一起，现在按类别分好了表格，查起来快得多。

3. 组件模式速查

约 420 行，把项目里的组件开发模式都整理了出来：

  • Headless/Presentational 分离模式（项目选择器组件统一使用这个模式）
  • 工厂函数完整清单（14 个列工厂 + 13 个表单项工厂，每个附使用示例）
  • 4 种标准页面结构模板（简单列表页、复杂 section 页、多级详情页、工作台页）
  • Hook 设计模式模板（CRUD Hook、筛选 Hook、聚合编辑 Hook）
  • 全部公共组件和 Hooks 的列表

4. 业务场景推理规则

一份 CSV 文件，12 条规则，覆盖了项目所有核心业务模块。每条规则告诉 AI：这个业务场景推荐什么布局、用什么配色、注意什么交互、避免什么反模式。

比如"风险评估仪表盘"这条规则会说：用 ProTable + 风险等级 Tag，配色用红/橙/黄/绿四级语义色，要加统计卡片做概览，避免复杂动画。

效果

同样的需求"帮我做一个任务列表页面"，现在 AI 产出的代码变成了这样：

export function TaskListPage() {
  const handleRequest = async (params: ParamsType) => {
    const res = await listTasks({
      page: { page: params.current || 1, page_size: params.pageSize || DEFAULT_PAGE_SIZE },
    });
    return { data: res.items || [], total: res.pagination?.total || 0, success: true };
  };

  return (
    <div className={styles.container}>
      <ProTable
        columns={getColumns()}
        rowKey="id"
        request={handleRequest}
        pagination={{ defaultPageSize: DEFAULT_PAGE_SIZE, showSizeChanger: true }}
      />
    </div>
  );
}

// columns.tsx
export function getColumns() {
  return [
    createProgressColumn<ITask>({ dataIndex: 'progress', title: '进度', width: 150 }),
    createTimestampColumn<ITask>({ dataIndex: 'created_at', title: '创建时间' }),
    createUserColumn<ITask>({ dataIndex: 'owner', title: '负责人' }),
  ];
}

ProTable + request，工厂函数，CSS Modules，没有 React.FC，没有 inline style，没有 useState/useEffect 手动管理数据。直接提交 Code Review 能过。

这件事到底有什么用

说完技术实现，聊聊我真正想说的——这件事的价值在哪里。

对开发者：少做机械劳动

之前用 AI 写一个页面，AI 出代码 3 分钟，我改规范问题 30 分钟。改的全是 inline style 换 className、硬编码换变量、手写列换工厂函数这种机械活。

现在 AI 一次出的代码就能过规范检查，我只需要审业务逻辑对不对。一个页面省下来的时间，保守估计半小时。

另一个好处是不用记那么多东西了。170 多个 SCSS 变量、27 个工厂函数、4 种页面结构模板——这些知识现在都在 Skill 里，我只要说"做一个 XX 页面"，AI 自己去查。

对团队：规范真的被执行了

写规范文档容易，让人遵守难。我们有 4 份规范文件，加起来上千行，但坦白说——能把每条都记住的人可能不多（会主动看的人其实都很少）。

这个 Skill 换了个思路：规范不是给人看的文档，而是 AI 每次工作时都要执行的指令。每天团队成员用 AI 写代码的时候，这些规范都在被执行。改了 Skill 文件，全团队立刻生效，不用发通知、不用开会。

还有一个没想到的副作用——references 目录里的三份文件（Token 速查、组件模式、antd 用法），新人拿来当入门文档效果意外地好。之前新人要自己去翻代码和规范文件，现在三份文档就把"项目怎么写代码、用什么组件、样式怎么处理"说清楚了。

对 Code Review：审查者可以看业务逻辑了

我统计了一下，我们 Code Review 中最频繁的十类问题——inline style、React.FC、硬编码值、没用工厂函数、ProTable 手动管状态、any 类型、console.log、空 catch 块、类型文件命名错误、魔法数字——这个 Skill 的检查清单全覆盖了。

这意味着 Reviewer 不再需要花时间在格式问题上纠缠，可以集中精力审查业务逻辑是否正确、边界条件是否覆盖、数据流是否合理。这对 Review 质量的提升是实质性的。

几个设计上的取舍

做这个东西的过程中，有几个决策值得说一下。

为什么要分层，而不是把所有规则写在一个文件里？

一开始我确实想过直接把所有规范塞进一个大文件。但 Cursor Skill 有个建议：SKILL.md 控制在 500 行以内。1300 行内容一次性灌进去，AI 的上下文窗口会被占满，留给实际业务逻辑的空间就少了。

所以拆成了主文件 + 3 个参考文件。主文件放工作流程和映射表（约 280 行），详细的 Token 列表、组件清单、antd 用法按需加载。需要查颜色的时候才去读 Token 文件，不需要的时候不占上下文。

为什么还要接通用设计知识库？

如果只有项目规范，AI 知道"怎么写符合规范的代码"，但不知道"这个页面应该怎么设计"。通用知识库提供设计理论支撑——比如管理后台的列表页一般怎么布局、统计数据适合用什么图表、交互反馈的最佳时长是多少。

项目适配层再把这些通用建议翻译成项目代码。两层各管各的，通用知识可以独立升级，项目规范也可以独立调整。

还可以怎么玩

这个方案本质上是"项目规范的结构化表达 + AI 执行引擎"。如果你的项目也有类似的情况——一堆规范文档没人看、AI 生成代码全是规范问题、新人上手慢——可以考虑用类似的思路。

核心步骤：

  1. 把项目的设计 Token 从 SCSS / CSS Variables / Tailwind config 里提取出来，做成结构化表格
  2. 把项目的组件库和公共 Hooks 整理成清单，附上使用场景
  3. 写一份 SKILL.md，定义工作流程和映射规则
  4. 如果有通用设计知识库，做一层 Token 映射把通用建议翻译成项目规范

不需要很复杂，一份 Token 映射表 + 一份组件清单 + 一份检查清单，就够 AI 产出合规代码了。

如果这篇文章让你有所收获，帮忙点个赞~

avatar
文章
阅读
粉丝