让 AI 按企业标准写前端代码——AI 编程的企业规则层实践

让 AI 按企业标准写前端代码------AI 编程的企业规则层实践

一句话版：企业级 AI 编程的瓶颈不在模型能力，而在上下文工程。我用配置驱动的思路做了一个 npm 包，把企业的 UI 标准、交互标准、字段命名标准、组件库规范结构化成 AI 可读的规则文件，让 Cursor/Trae 在生成代码前先读规则、按规则产出；还能从已有代码反向诊断，自动生成规范草稿。

一、开篇：一个真实的痛点场景

团队这几年开始用 Cursor、Trae 这类 AI 编程工具写前端。效率确实上来了，但很快发现一个尴尬的现象：AI 写得很快，写的却经常"不对"。

UI 标准不达标。 设计系统里主色是 --color-primary-500，AI 给你写 bg-blue-500；间距规范是 4 的倍数设计 token，AI 张口就来 p-4、p-3、rounded-lg，全凭感觉。

交互标准不统一。 同一个搜索框，AI 这次生成 SearchBar，下次生成 SearchInput；同一类列表页，这次是"顶部搜索 + 表格 + 分页"，下次是"侧边筛选 + 表格"，团队里每个人审出来的页面长得都不一样。

字段命名混乱。 同样是"用户"，AI 时而叫 user、时而叫 account、时而叫 member；同一个"加载中"文案，团队代码里并存着"加载中""正在加载""加载中..."三种写法。

组件复用靠运气。 公司早就有封装好搜索、筛选、分页的 SearchableTable，但 AI 不知道，每次都重新造轮子，甚至 import 了被明确禁用的组件。

文案不一致。 "查询""搜索""检索"混用，按钮一会儿"确定"一会儿"确认"。

这些问题单独看都不大，但合在一起就是一句话：AI 生成代码的速度，被"不规范"悄悄吃掉了大半回报。

于是我们开始找方案，结果发现现有手段都不好使：

.cursorrules 模板集合 ：零散、不可维护、没有版本化、无法校验。更要命的是，这套机制本身已经被官方淘汰了------.cursorrules 自 Cursor 0.43 起弃用，而 .traerules 根本不被 TraeCode 加载（这个坑后面细说，它差点要了项目的命）。
design system 文档：写得挺好，但不是针对 AI 优化的，AI 读了也不一定遵守。
纯 prompt 工程：把一堆规范塞进提示词里，质量方差极大，而且无法机器校验。
内部 Lint 工具：只能事后纠错，不能在 AI 生成的那一刻就规范。

看清楚这些之后，我心里冒出的问题愈发具体：

如何让 AI 编程工具稳定、可校验地按企业的 UI 标准、交互标准、字段命名标准、组件库规范生成代码？

这就是这个项目的起点。

二、核心思路：配置驱动的 AI 规则层

2.1 项目是什么

一句话定义：以 npm 包 + .ais/ 配置层的形态，把企业的四大标准（UI / 交互 / 字段命名 / 组件库）结构化为 AI 可读的规则文件，让 Cursor/Trae 在生成代码前先读规则、按规则产出。

它叫 @ai-coding-spec/core，本质上是一套 CLI，核心命令是 init、sync、component、analyze、ui 五个。技术栈不算花哨：TypeScript + commander（CLI）、ts-morph 和 @vue/compiler-sfc（AST 分析）、zod（配置校验）、vitest（测试）。ui 这块用的是原生 node:http，零新增运行时依赖。

2.2 核心机制：配置驱动 + 规则编译

项目最核心的设计，是一套"单一真相源 → 派生产物"的编译链路：

text 复制代码

.ais/config.json                    企业统一配置（唯一真相源）
      │  ai-coding-spec sync
      ▼
.ais/knowledge/*.md                 AI 可读的知识库（四大标准）
.ais/theme/tokens.css               CSS 变量
.ais/theme/tailwind.config.js
      │  ai-coding-spec init（首次 / npm 安装时自动执行）
      ▼
.trae/rules/ai-coding-spec.md       IDE 官方规则文件（frontmatter alwaysApply，
.cursor/rules/ai-coding-spec.mdc      指引 AI 生成前先读知识库）
      │  IDE 自动加载规则 → AI 读取知识库
      ▼
AI 生成的代码符合企业标准

关键设计：企业只维护一份 config.json，其余产物全部由 CLI 同步生成。 这从根上避免了规则散落在多处导致漂移的问题------规则只有一份来源，改一处，sync 一下，所有知识库、样式令牌、规则文件全部对齐。

2.3 三条设计原则

配置驱动 ：企业只维护一份 .ais/config.json，规则文件由 sync 命令编译生成，而不是手写维护。
零侵入：不修改宿主项目的构建配置和业务源码，装完即用，删掉即走。
包与资产分离 ：npm 包只提供 CLI 能力，项目专属的规则资产存放在 .ais/ 目录里，随项目 git 提交、团队共享。

2.4 核心洞察

做完之后我回头看，突然明白了这件事的本质：

这个项目的整个存在意义，就是喂规则给 LLM。

.trae/rules/*.md、.cursor/rules/*.mdc、.ais/knowledge/*.md，这些文件全是给 LLM 读的。sync 生成 design-tokens.md 让 LLM 按设计 Token 写代码，和让 LLM 按 glossary.md 用正确的字段命名，是同一套机制的不同应用------本质都是在解决"如何把企业规范可靠地注入进 AI 的上下文"。

想通这一点之后，后面很多纠结的设计决策就都顺理成章了。

三、四大标准的工程化落地

这是项目的技术主体。四大标准各对应一类规则文件，逐一说清楚。

3.1 UI 标准：design-tokens.md + tokens.css

问题：AI 写 bg-blue-500、p-4、rounded-lg，不符合企业设计系统；硬编码的色值一旦要换肤，就要全局搜索替换。

方案：config.json 定义 theme，sync 编译生成 tokens.css + design-tokens.md。AI 读到之后，生成的是：

html 复制代码

<div class="bg-[var(--color-primary-500)] p-[var(--space-4)]">

而不是硬编码的 bg-blue-500 p-4。色值、间距、圆角全部走 CSS 变量，和设计系统的 token 一一对应，换肤只改一处。

3.2 交互标准：component-patterns.md

问题：AI 写列表页一会儿"顶部搜索 + 表格 + 分页"，一会儿"侧边筛选 + 表格"，交互模式五花八门。

方案：config.json 定义 patterns 分类，sync 生成 component-patterns.md。AI 写列表页时会主动参考企业认可的交互模式，比如"列表页统一采用标题条 + 筛选区 + 表格 + 分页 + 右上角新建按钮"的骨架。

3.3 字段命名标准：glossary.md

问题：AI 把"用户"叫 user 还是 account 还是 member 全凭运气，同一个业务概念在不同页面名字对不上，联调、检索都痛苦。

方案：config.json 定义 glossary.domains 术语表 + glossary.propHints 文案规范，sync 生成 glossary.md。AI 生成代码时变量命名严格对齐术语表（"质量规则" → qualityRule），文案复用标准的 propName（"请输入规则名称" → namePlaceholder）。

3.4 组件库标准：component-library.md

问题：AI 不知道企业已有 SearchableTable，每次重新造轮子，甚至用上被禁用的组件。

方案：component add 注册已有组件（自动解析 Props + JSDoc），sync 生成 component-library.md，含 Props 表格和使用说明。AI 生成时优先使用已注册组件，避开 forbidden 清单。这一环实际上是"把 AI 的选型权，收回到企业手里"。

3.5 代码风格：{react|vue}/coding-standards.md

问题：React 函数组件有的用 function 有的用箭头函数；TypeScript 类型有的用 interface 有的用 type。

方案：init 自动检测框架，复制对应的编码规范模板到 .ais/knowledge/{react|vue}/coding-standards.md。这部分看似琐碎，却是"代码里能不能顺畅接上"的基础。

3.6 闭环：postinstall 自动初始化

为了让"装上即生效"，npm 安装后 postinstall 会自动跑 init，确保规则文件就位。但自动执行有风险------万一在 CI 里、在别人依赖里被触发怎么办？我加了四道安全闸：INIT_CWD 校验、node_modules 内跳过、.ais/ 已存在跳过、失败非阻塞。这样既保证开发环境一键就位，又不污染 CI/CD。

这条链路后来经过了真实回归验证：npm pack → tarball 安装 → postinstall 自动初始化 → .ais/ 与官方规则文件一次就位。

四、反向诊断：从已有代码反推规范

init/sync 解决的是"已经有规范，怎么让 AI 遵守"。但更常见的场景是------团队根本说不清自己有什么规范。

4.1 为什么需要 analyze

新团队接手老项目，第一件事是"摸清现状"：有哪些硬编码文案？哪些组件被高频复用？哪些外部包实际在用？这些问题人工梳理成本高、极易遗漏。我决定加一个 analyze 命令，做"反向诊断"。

4.2 analyze 做什么

bash 复制代码

npx ai-coding-spec analyze

它扫一遍 src/ 下所有组件，做两件事：

文案聚合：提取所有硬编码中文文案，按频率统计，标记冲突项（"加载中" vs "正在加载"），并附建议的 propName。
import 分析：统计外部包引用（分类为组件/工具/样式），识别本地高频组件（引用 ≥3 次保留为候选注册项）。

草稿隔离 是这里的关键设计：所有结果写入独立的 .ais/analyze-draft.json，不直接污染 config.json 的正式字段 。这个设计是用一次真实翻车换来的------早期版本把草稿写进 config 的 _draft 字段，在真实项目上跑一次，config 直接膨胀到 16.5MB。现在草稿独立成文件，config 保持干净。

4.3 人工确认流程

text 复制代码

analyze 生成草稿（.ais/analyze-draft.json）
  ↓ 人工审核：认可的移入 config.json 正式 glossary / components，不认可的删除
  ↓ sync 重新生成知识库
  ↓ AI 读到最新规范

关键设计：不自动转正。 保留用户最终控制权------AI 帮你"看到"规范，但"决定"规范的是人。

4.4 与 component add 的协同

analyze 发现 @/components/SearchableTable 被 12 个文件引用 → 人工确认后跑 component add --name SearchableTable --path ... 正式注册 → sync 生成 component-library.md → AI 后续生成时优先使用。

诊断和注册打通了：从"我不知道有什么"到"AI 知道该用什么"，形成闭环。

五、可视化配置：让"写配置"门槛归零

前面几章的前提是"企业维护一份 config.json"，听起来很美好，但落地时我很快撞上一堵现实的墙------配置驱动再优雅，改配置的人还是会被 JSON 劝退。色阶 20+ 个色值、间距/圆角/阴影/字号全是键值对，让设计师或前端挨个敲 JSON，既不友好也容易出错。这是"配置驱动"的最后一公里，不解决，前面的机制再漂亮也推不动。

5.1 方案：`npx ai-coding-spec ui`（试用版）

我加了一个 ui 命令：本地起一个 HTTP 服务（原生 node:http，零新增运行时依赖 ），自动开浏览器进配置页，可视化编辑 .ais/config.json 的 theme 部分。

说明：可视化配置目前是试用版（v1），能力边界是只编辑 theme 现有字段，schema 与 sync 零改动。它会在大家的使用反馈中持续迭代------你觉得缺什么、哪不顺手，都欢迎提出来（反馈方式见文末 8.4 节）。

bash 复制代码

npx ai-coding-spec ui              # 默认端口 5300，被占用自动递增
npx ai-coding-spec ui --port 8080

分区	能力
色彩	取色器 + hex 文本双向同步（非法红边不落盘）；色阶组折叠 / 重命名 / 增删 shade
字体	fontFamily 文本框；fontSize 支持 `[size, { lineHeight }]` 元组与纯字符串双形态
间距 / 圆角 / 阴影	键值行编辑器；阴影带每行应用方块的即时预览
预览	色板 / 字号阶梯 / 圆角 / 阴影 / 间距标尺随输入实时刷新，并与左侧 tabs 联动高亮

5.2 两个关键设计决策

保存即落盘，且保存即生效 。浏览器里的静态页无权写本地文件，本地服务就是保存通道：保存 → PUT /api/config → zod 校验 → 写回 config.json，非法 400 拦截零污染。v1 最初保存后还要手动跑 sync，真实用户反馈"不友好"，于是改成落盘成功后自动触发 POST /api/sync，"已保存并同步生效"一步到位。
schema / sync 零改动 。v1 严格守住红线------配置字段不加、version 不动、sync 不改。可视化只是数据源的可视化入口，不改"config.json 是单一真相源"这件事本身。

5.3 实测反馈

ui-mng 首轮实测暴露 6 个真问题（非法输入被静默吞掉、zod 重序列化导致 _comment 移位、node 16 报错不友好等），全部修复，单测从 129 增至 140 用例全绿。

这一节想说明一件事：配置驱动要真正落地，"写配置"的体验和"生成规则"的机制同样重要。

六、踩坑实录

如果说前面几节是"设计图纸"，这一节就是"工地现场"。真实工程最有说服力的部分，永远是那些差点翻车的坑。

5.1 【头条】P0：规则写得再好，进不了 AI 上下文等于零

这是整个项目里最刺痛我的一次失败。

正向编码验证（TC-6）首跑时，我让 AI 按规范新建一个页面，结果 7 项评分全挂，而且生成前根本没读任何规范文件。

排查结论让我倒吸一口凉气：.traerules 根本不被现行 TraeCode 加载。官方机制是 .trae/rules/*.md + frontmatter alwaysApply: true；Cursor 则是 .cursor/rules/*.mdc（注意，.md 扩展名会被 Cursor 忽略）。

也就是说，规范文件压根没进过 AI 的上下文------根本不是模型不遵守，是我的注入链路从一开始就是断的。

迁移到官方规则目录后复测：TC-6a 新建页面 7/7 达标（生成前主动读 .ais/knowledge/*.md、复用已注册组件、文案/样式/命名全部合规），TC-6b 存量页面改造义务也生效了。

这个故事直接证明了本文的核心论点：企业级 AI 编程的瓶颈在上下文工程，而上下文工程的第一公里是"注入链路"------规则内容写得再好，通道断了全是零。

5.2 fixtures 与真实企业项目的差距：一次实测爆出 5 个 P1

单元测试一直很绿，fixture 是 <script setup> + TS 的小样例。可拿到真实企业项目（ui-mng：Vue 3 + ant-design-vue 4 + 纯 JS Options API，180 个 .vue，大量中文业务文案）一跑，直接连爆 5 个 P1：

现象	根因	修复后
文案冲突假阳性率 92.7%	fallback 同桶互标	0%（0/970）
config.json 膨胀至 16.5MB	analyze 草稿写入正式配置	6.3KB（草稿独立为 analyze-draft.json）
72 条非中文标识符混入文案聚合	无"用户可见文案"过滤	0 条（统一 `isUserFacingText`，三采集点接入）
Options API props 解析为 0	只支持 `defineProps<{...}>` 泛型	三路径解析（TS 泛型/运行时对象/Options API）
extract 产物语法损坏（双冒号、标签截断）	字符串替换误伤动态绑定	AST 重写 + 落盘前 SFC parse 校验底线（0 错误）

这堂课的教训很直接：fixture 驱动开发的天花板------小样例全绿不代表真实项目可用；规范工具必须在真实企业项目上过关才算数。

还有一个值得记一笔的亮点：extract 的"落盘前校验"底线机制，在修复根源之前，就先拦截了损坏产物（49 个语法错误、不写盘、退出码非零）。"先不产出坏东西"，比"产出完美东西"优先级更高------这个底线设计被真实数据验证了价值。

5.3 开发期坑（简记）

Vue 编译器注入污染 ：@vue/compiler-sfc 的 compileScript 会注入 __returned__、__isScriptSetup 等内部语句，被 ts-morph 误判成业务代码，加过滤跳过。
Props 命名聚合 ：最初每个硬编码文本提取成独立 Prop（label1/label2/label3），后来按语义聚合为 items 这样的结构化 Prop。
postinstall 四道安全闸 ：INIT_CWD / node_modules 跳过 / .ais/ 已存在跳过 / 失败非阻塞。npm 8 下 postinstall 日志对用户不可见（需 --foreground-scripts），只能靠产物证明执行。
sync 不消费 propHints：analyze 推断的文案规范写进了 config，却没渲染进 glossary.md，价值断链，补"文案规范（Prop Hints）"章节才接上。

七、转型思考：为什么前端转 AI 应用开发要做这个项目

最后说点个人的。这个项目对我而言，不只是个工具，更是"前端转 AI 应用开发"这条路上的一个坐标。

8.1 转型最大的坑

前端做 AI 有个尴尬的处境：前端做不动 AI，AI 又不懂前端工程。 纯 LLM 应用，前端背景没有优势；纯前端项目，又接触不到 AI。两头都不靠。

8.2 这个项目踩在转型交叉点上

回头看，这个项目恰好落在两条路的交叉点：

转型能力点	项目对应实现
AST 与代码静态分析	ts-morph / @vue/compiler-sfc
配置驱动架构	config.json → sync → 知识库
AI 产品化思维	草稿隔离（analyze-draft.json）+ 人工确认 + sync 生效
工程化能力	CLI、monorepo、postinstall、zod 校验
真实项目验证	ui-mng（180 个 .vue）实测：8 issue 修复、两轮回归、TC-6 正向编码 7/7 达标；ui 可视化页 6 反馈全修复、140 单测全绿

它不是一个"调 LLM API 的玩具"，而是用前端工程能力（AST、CLI、配置系统）去解决 AI 编程的真实问题------LLM 在这里是增强，不是核心；真正的护城河还是前端工程功底。

8.3 项目演进即转型路径

这个项目的迭代节奏，本身就是一条清晰的转型叙事：

MVP（配置驱动 + sync 生成规则文件）→ 转型初期投递
一阶段（component + analyze）→ 能讲组件库治理和反向诊断
二阶段（ui 可视化 + lint + MCP server）→ 能讲 AI 工程化和产品化

8.4 给同样在转型的同学的建议

不要做纯 LLM 玩具项目，前端背景在纯 LLM 领域真没优势。
把前端工程能力当护城河，LLM 是增强不是核心。
项目要可讲------能讲清楚，比代码本身更重要。
写博客是核心，不是附属，这也是我写下这篇的原因。

八、结语与展望

8.1 项目当前状态

已完成 ：init/sync 配置驱动、四大标准规则文件、component 组件注册、analyze 反向诊断、ui 可视化配置页 、React+Vue 双框架支持、规则机制迁移（.trae/rules/ + .cursor/rules/ 官方目录）。
已验证 ：真实企业项目（ui-mng，Vue 3 + ant-design-vue 4，180 个 .vue）全链路实测------8 个 issue 修复、单测 140 用例全绿 、从 npm 打包安装开始的两轮回归、TC-6 正向编码 7/7 达标；ui 可视化页 6 条实测反馈全部修复。
规划中 ：lint 模板校验、analyze --apply 半自动转正、MCP server。

8.2 对 AI 编程工具的思考

做完这一轮，我愈发确信一个判断：

AI 编程工具的下一步，不是更强的模型，而是让 AI 理解上下文。

企业级 AI 编程的瓶颈不在模型能力，在上下文工程------把企业标准结构化为 AI 可读的规则，比单纯堆模型参数有效得多。模型的"聪明"是普惠的，而"懂你的项目"这件事，才是真正需要工程去补的缺口。

8.3 开源计划

项目定位为"早期开源、寻求反馈"。如果你所在的企业也在为 AI 生成代码不规范而头疼，或者你对"上下文工程"这条线感兴趣，欢迎来交流------尤其是企业用户和 AI 工具厂商，你们的一线反馈会决定它下一步往哪长。

8.4 试用与反馈

整个项目目前处于早期试用阶段 ，尤其是可视化配置（ui 命令）刚随 v0.2.0 发布，是第一版试用。它一定还有不成熟的地方------交互不顺手、缺能力、边界场景没覆盖，都很正常。我特别希望大家试用后把建议砸过来：哪些分区好用、哪些反直觉、想编辑 theme 之外的什么字段、预览还缺什么......可视化配置会根据这些建议不断完善，你的反馈直接决定它下一版长什么样。

安装（Node ≥ 18）

bash 复制代码

npm install @ai-coding-spec/core
# 或
pnpm add @ai-coding-spec/core

安装后 postinstall 会自动执行一次 init，生成 .ais/ 配置目录和官方规则文件；没自动跑也不用慌，手动补一条即可：

bash 复制代码

npx ai-coding-spec init

基础使用

bash 复制代码

# 根据 config.json 生成本次所有知识库与规则文件
npx ai-coding-spec sync

# 扫描现有代码，反向生成规范草稿（写入 analyze-draft.json，不污染正式配置）
npx ai-coding-spec analyze

# 注册企业已有组件，让 AI 优先复用；list 查看已注册组件
npx ai-coding-spec component add --name SearchableTable --path src/components/SearchableTable.vue
npx ai-coding-spec component list

# 起可视化配置页（试用版，本地服务 + 自动开浏览器），保存即落盘并自动 sync 生效
npx ai-coding-spec ui

框架支持说明 ：目前仅在一个 Vue 3（Options API）真实项目上做过完整验证。React 侧因为已经不再涉及模板提取，逻辑上不受影响，但同样尚未在真实项目上实测------如果试用中遇到问题，欢迎反馈：19564107@qq.com。

让 AI 按企业标准写前端代码——AI 编程的企业规则层实践