使用 Claude Code 进行前端组件开发时样式冲突的解决经验

上周三下午，我在一个新项目里让 Claude Code 生成一个带搜索功能的下拉选择器组件。逻辑完美，交互流畅，生成速度不到四十秒。我把组件引入公司的中后台管理系统，页面直接崩了，整个侧边栏的字体全部变成 14px 的衬线体，表格的行高塌缩到 20px，连登录按钮都从蓝色变成了灰白色。

F12 打开开发者工具那一刻，我就知道发生了什么：Claude Code 生成的组件样式，没有做任何作用域隔离，直接污染了全局。

这不是 AI 的错。问题出在我自己，我没有给 AI 建立任何样式管理规则。我当时的心态和很多开发者一样：先把组件跑起来再说，样式问题后面再调。但“后面再调”的代价远超预期。那天我花了将近三个小时排查样式链，逐层对比 computed styles，最后发现源头竟然是 AI 写的一条 .container { max-width: 1200px; margin: 0 auto; } 和项目里已有的布局容器类名冲突。

这也是我写这篇文章的原因。过去八个月，我在三个商业项目中深度使用 Claude Code 进行前端组件开发，累计生成了超过 200 个组件，踩过的样式坑足够写一本小册子。这篇文章不是“AI 生成的代码有样式问题怎么办”的通用科普，而是我从实际项目里总结的一套侦察-分类-收编-验证的系统方案。读完你就能理解：为什么 AI 生成的组件总是“水土不服”？如何用 10 分钟排查 90% 的样式冲突？怎样建立一套让 AI 和你的项目和谐共处的样式管理策略？

一、核心结论：样式冲突的本质不是代码问题，而是“沟通协议”缺失

绝大多数开发者在遇到 AI 组件样式冲突时，第一反应是去改 CSS。加 !important、调整选择器优先级、或者干脆重写 AI 的代码。

但这样做忽略了一个更底层的问题。

我统计了过去半年在我个人项目中遇到的 47 次 AI 组件样式冲突事件（这些数据来自我的 GitHub commit history 和项目日志）：

从这个表格可以看出：超过 80% 的冲突，根本原因不是 AI 写的 CSS 本身有问题，而是 AI 生成的代码与项目已有代码之间缺少一个清晰的“沟通协议”。

什么是“沟通协议”？简单说，就是在你让 AI 写组件之前，必须明确告诉它：

• 你的项目用的是哪个 UI 框架（Ant Design / Element Plus / 自研组件库）
• 你的样式方案是什么（CSS Modules / Scoped / styled-components / Tailwind）
• 你的命名规范是什么（BEM / SMACSS / 自定义前缀）
• 哪些全局样式是绝对不能动的（reset.css / 主题变量 / 设计 Token）

Claude Code 本身并不自动了解这些信息。它只会根据你给它的上下文和 Prompt，生成它认为最合理的代码。如果你不给它设定样式边界，它就会按照自己的“理解”去写，这个“理解”通常是最通用、最不设防的 plain CSS。

我曾在两个并行项目里做过对比实验：

• 项目 A：我没有给 Claude Code 任何样式规范提示，让它直接生成组件。结果：每生成 5 个组件，平均有 2.3 个需要手动修复样式冲突。
• 项目 B：我在每次请求前，都会在 Prompt 里附带一个 200 字的样式规范说明（包括命名前缀、UI 库名称、CSS 方案）。结果：每生成 5 个组件，需要修复的数量降到 0.7 个。

这个对比直接说明：解决样式冲突最有效的方法，不是事后修复，而是事前建立规则。

二、建立“样式冲突侦察体系”：3 步定位问题根源

在继续深入之前，我必须先说明一个反常识的观点：你对浏览器开发者工具的掌握程度，直接决定了你解决 AI 样式冲突的效率。

大部分人遇到样式问题，会直接打开 Elements 面板，看某个元素的 Styles 选项卡，然后发现某条被划掉的样式，接着就手动去改。

这么做有两个致命缺陷：

1. 你只看了一个元素，却没有看到这条样式对整个样式链的影响范围。
2. 你只看结果（被覆盖了），却没有看原因（为什么会被覆盖？谁覆盖了谁？加载顺序是什么？）

我总结的“三步侦察法”，是基于在 Chrome DevTools 里对超过 100 次样式冲突的排查经验提炼出来的。这个方法不依赖任何第三方工具，只需要你理解浏览器的样式计算机制。

第一步：用“Computed”面板反推污染源

当页面某个区域样式异常时，不要直接看 Styles 面板。先选中异常元素，打开 Computed 选项卡，找到那个变了值的属性（比如 font-family 从预期的 PingFang SC 变成了 Times New Roman）。

点击这个属性值左侧的小箭头，Chrome 会展开所有为这个属性赋值的选择器，并且按优先级排序。最上面那条就是最终生效的样式。

关键技巧：不要只看最上面那条的选择器名字，要同时看它的来源文件。 如果来源文件是一个你不认识的 <style> 标签或者一个动态注入的样式块，那基本就是 AI 组件引入了内联样式。我在排查侧边栏字体被污染的问题时，就是通过这个技巧发现了一条来自 <style> 标签的 body { font-family: 'Open Sans', sans-serif; }，而这条定义正来自 Claude Code 生成的一个弹窗组件。

第二步：用 Coverage 面板找出“沉睡污染”

这是很多人忽视的一个功能。打开 DevTools → 更多工具 → Coverage，点击录制按钮，然后刷新页面。Coverage 面板会告诉你：在你的所有 CSS 文件中，有多少比例的代码是当前页面实际使用的。

你可能会发现，有些 CSS 文件的使用率只有 15% 甚至更低。但那些 85% 的“未使用代码”并不是无害的，它们依然占用着选择器的优先级位置，可能在你添加新元素时突然被激活。

我在一个使用 Claude Code 密集生成组件的项目里做过一次 Coverage 扫描，结果发现：

• 项目总 CSS 代码量：184KB
• 实际使用率：62%
• 未使用的 38% 中，有 27% 来自 AI 生成的、已经在重构中被替换但未清理的旧组件样式

这些“沉睡样式”就像定时炸弹，你在这个阶段可能没踩到，但下次你让 AI 生成一个新组件时，新选择器和这些旧样式可能会产生你完全没预料到的级联冲突。

我现在的习惯是：每次删除或替换一个 AI 生成的组件时，同步清理它对应的样式代码。 不留在项目里“以防万一”。如果你不确定某段样式是否还在用，Coverage 面板就是最好的判断工具。

第三步：用“Layers”视图识别层级干扰

如果你用的是 Chrome 88+，可以在 Elements 面板看到 CSS Layers 的相关信息。CSS @layer 是最近两年浏览器开始广泛支持的规范，它允许你显式定义样式优先级层级。

但问题是：如果你没有主动使用 @layer，浏览器会默认将所有样式放在同一个“未命名层”里，然后按照“后加载覆盖先加载”的规则处理冲突。这就意味着：AI 生成的组件在什么时候被引入页面，会直接影响它的样式优先级。

我在一个 Next.js 项目里遇到过这样的场景：

• 上午 10 点：我让 Claude Code 生成了一个表格组件，样式正常。
• 下午 3 点：我又让它生成了一个筛选面板，引入后，表格的斑马纹样式突然失效。

排查了 40 分钟才发现：筛选面板在加载时动态注入了一段带有 tbody tr:nth-child(even) 的样式，这段样式后加载，并且选择器特异性跟表格的一样，直接覆盖了表格的背景色定义。

如果我在项目初期就用 @layer 把所有 AI 组件的样式限制在 @layer ai-components 里，并且让这个 layer 的优先级低于项目的 @layer base 和 @layer ui-library，这个冲突根本不会发生。

三、AI 组件样式冲突的 5 种典型场景与根因分析

在我处理过的所有样式冲突中，有 5 种情况反复出现。单独对每一种情况做深度剖析，比给出一个笼统的“解决方案清单”更有价值。

场景一：全局选择器污染（占比 38.3%）

典型案例：Claude Code 生成一个模态框组件时，代码如下：

* {

box-sizing: border-box;

}

body {

font-family: 'Inter', sans-serif;

line-height: 1.6;

}

.container {

max-width: 1200px;

padding: 0 20px;

}

这些样式单独看没有任何问题。但如果你的项目已经有一套全局 reset 和布局系统（比如你用的是 Tailwind 的 preflight，或者团队自定义的 reset.css），这几行代码会直接覆盖你的项目设置。

根因：AI 在生成组件时，倾向于把组件的依赖和组件本身打包在一起。它看到组件需要 box-sizing: border-box，就会自动加上，但不会判断项目是否已经有了这条规则。

我在 GPT-4 和 Claude 的对比测试中发现一个规律：如果 Prompt 里没有明确说明“你已经有了全局 reset”，AI 会在大约 67% 的情况下添加冗余的全局样式重置。这个比例在 Claude 3 Opus 上略低（约 58%），在 GPT-4 上略高（约 71%），但整体差异不大。

场景二：命名冲突（占比 19.1%）

这个场景最隐蔽，因为冲突不一定马上表现出来。

Claude Code 给你的组件生成了一个 .card 类，包含 padding: 16px; border-radius: 8px; background: white;。你的项目里也有一个 .card 类，定义在三个月前写的一个仪表盘组件里，包含 padding: 24px; border-radius: 12px; background: #f5f5f5; box-shadow: 0 2px 8px rgba(0,0,0,0.1);。

如果你幸运，两个 .card 碰巧应用在不同的页面，短期内不会冲突。但万一某个页面把两个组件都引入了，浏览器会怎么处理？它会合并两条规则，而不是覆盖。最终的效果可能是 padding: 16px 和 box-shadow: 0 2px 8px 同时生效，产生一个你完全没见过的、混乱的视觉效果。

这种“规则合并”而不是“命名空间隔离”是 CSS 的基本特性，但也正是这一点让命名冲突如此棘手，它不是简单的覆盖，而是混杂。

场景三：UI 框架变量冲突（占比 25.5%）

如果你用的是 Ant Design 5.x，你会知道它有一套 Design Token 系统，所有组件都依赖 CSS 变量，比如 --ant-primary-color、--ant-border-radius-base 等。

Claude Code 生成的组件可能会：

1. 重新定义这些变量（比如在 AI 组件的 :root 里写了 –primary-color: #1890ff，恰好和 Ant Design 的变量名相似但不同）
2. 使用硬编码的值覆盖了本该由 Token 控制的属性（比如 border-radius: 6px 而不是 border-radius: var(–ant-border-radius-base)）
3. 在一个 Ant Design 组件的特定实例上使用了更高特异性的选择器，导致这个实例和项目中其他同类组件样式不一致

第三种情况尤其容易出现在 AI 生成的“复合组件”中。比如你让 Claude Code 生成一个“带标签的搜索框”，它可能会在一个 Ant Design <Input> 外面包一层 <div>，然后对这个 <div> 里的 <Input> 应用特殊样式。结果是：这个搜索框和项目中其他搜索框的圆角半径不一样。

场景四：作用域机制的“误用”（占比 10.6%）

Vue 的 <style scoped> 和 React 的 CSS Modules 确实是解决样式隔离的有效手段，但前提是你正确地使用了它们。

Claude Code 在处理这些作用域方案时，有两个常见失误：

1. 忘记做深度选择器转换。在 Vue 中，如果你用了 <style scoped>，想要穿透到子组件，必须要用 :deep()。但 AI 可能直接写 .parent .child，这条规则在 scoped 模式下不会生效。
2. 在 CSS Modules 中使用了过于简单的类名过渡。CSS Modules 在编译时会自动把类名加哈希，比如 .button 变成 .button_3s8k2。但在 AI 生成的 JSX 中，它可能写成了 className="button" 而不是 className={styles.button}。

我在使用 Claude Code 三个月后做了个统计：它生成的 Vue SFC 文件中，<style scoped> 的使用率约为 72%（即 72% 的情况它会主动加 scoped），但在加了 scoped 的文件中，约 31% 存在 :deep() 缺失或误用的问题。这个数据来自我审查自己项目仓库中 87 个由 AI 生成或协助编写的 Vue 组件。

场景五：动态样式的逻辑冲突（占比 6.4%）

这是最不好排查的一种。AI 生成的组件通常会包含一些基于状态的样式切换逻辑，比如：

const buttonStyle = {
backgroundColor: isLoading ? '#ccc' : '#1890ff',

cursor: isLoading ? 'not-allowed' : 'pointer',

};

如果这个组件被集成到一个使用 Vuex/Pinia 或 Redux/Zustand 管理的项目里，而 isLoading 状态的来源和你项目的全局 loading 状态产生了命名或逻辑上的重叠，就会导致按钮在你不期望的时候变成灰色。

这类冲突在单一组件测试时几乎不可能发现，只有集成到项目中、多个状态同时作用时才会暴露。

四、给 AI 输出建立“样式规范提示协议”

经过前述分析，可以得出一个清晰的结论：解决冲突的核心，不是在 AI 生成代码后去修改，而是在生成前就建立好规范约束。

我把这套约束称为“样式规范提示协议”（Style Specification Prompt Protocol，简称 S2P2）。它由三层构成：

第一层：项目基础信息声明

这是最基础的一层，包含 4 个信息点：

1. UI 框架及版本：例如“Ant Design 5.12.8”
2. 样式方案：例如“CSS Modules + Less”
3. 命名约定：例如“所有组件类名以 cld- 为前缀（cld = Claude）”
4. 禁止修改的全局样式清单：例如“不要写任何对 body、html、* 选择器的样式声明”

实际使用中，我把这些信息整理成了一段可以直接粘贴到 Claude Code 对话开头的模板：

[项目样式约束]

UI 框架：Ant Design 5.12.8，组件通过 ES Module 引入，样式通过 import 'antd/dist/reset.css' 全局引入

样式方案：本组件使用 CSS Modules，样式文件命名为 [组件名].module.less

命名规范：所有 class 必须使用 cld- 前缀，例如 .cld-CardContainer、.cld-SearchInput

禁止项：不要写 * {}、body {}、html {}、:root {} 这类全局选择器；不要覆盖 Ant Design 的 Design Token 变量；不要使用 !important

这不是一次性的设置。每当你开启一个新的对话窗口、或者上下文窗口被清空时，都需要重新声明这段约束。 我在 Notion 里维护了一个“Claude Code 起始 Prompt”页面，每次开启新对话时直接复制粘贴。

第二层：组件级样式边界定义

第一层解决“不要破坏我的项目”，第二层解决“这个组件自身的样式边界在哪”。

具体来说，你需要在 Prompt 里明确：

• 组件根元素的标签和类名（这样 AI 就知道从哪开始写样式）
• 组件是否需要响应式断点，以及断点值是多少（很多时候冲突来自 AI 生成了一套和你项目不一致的 media query）
• 组件是否依赖父级传入的样式（比如是否接受 className props）

一个实际可用的组件级 Prompt 示例：

[组件需求]

生成一个下拉搜索选择器，组件名：SearchSelect

[样式约束补充]

• 根元素使用 <div className={styles.cld_SearchSelect}>
• 响应式断点与项目一致：768px（平板）、1024px（桌面）
• 组件接受 className props，允许父级覆盖外层容器样式
• 内部元素的最大 z-index 不超过 1000（项目弹窗层 z-index 为 1050）

注意最后一条“z-index 不超过 1000”，这是一个我踩了三次坑才总结出的经验。AI 倾向于给弹窗、下拉菜单等遮罩层设置一个很高的 z-index（比如 9999），但如果你的项目里弹窗系统用的是 1050，AI 生成的下拉菜单 z-index 设成 9999，会导致下拉菜单覆盖在弹窗之上。

第三层：输出格式要求

这一层比较容易被忽略。你需要明确告诉 AI：生成的 CSS 代码必须以什么格式、什么结构输出。

我的要求通常是：

• 如果项目用 CSS Modules，CSS 代码写在 .module.css 或 .module.less 文件中，而不是写在 <style> 标签或 JS 的 style 对象里
• 如果是 Vue 项目，样式代码必须写在 <style scoped> 中，并且所有穿透子组件的选择器使用 :deep()
• 禁止输出内联样式（style={{}}），除非是动态计算的值
• 所有颜色值使用项目的 CSS 变量引用（如 var(--color-primary)），而不是硬编码

这套三层协议在实践中被验证有效。我在 4 个项目中持续使用这套协议，AI 生成组件的“一次通过率”（即不需要修改样式就直接可用的比例）从最初的约 35% 提升到约 78%。

当然，78% 不是 100%。剩下的 22% 不通过的情况，主要出现在：

• 组件交互逻辑特别复杂，样式依赖多个动态状态（占比约 9%）
• 组件需要与第三方库（如图表库、富文本编辑器）的样式深度整合（占比约 7%）
• 项目本身存在技术债，已有样式已经不够规范，AI 难以完全适配（占比约 6%）

对于这 22% 的情况，就需要下一个环节，“后处理策略”。

五、“后处理函数”策略：让代码自动执行样式规约

如果说 S2P2 协议是“预防”，那么后处理函数就是“保险”。

后处理函数的逻辑很简单：在 AI 生成代码并写入文件之后，由脚本自动扫描并修正已知的、可程式化的样式问题。

我在项目中用的是一个不到 200 行的 Node.js 脚本，它主要做 4 件事：

1. 全局选择器检测与剔除

脚本扫描所有 AI 生成的 CSS/SCSS/Less 文件，如果检测到 * {}、body {}、html {}、:root {} 这类选择器，会自动注释掉并插入一个警告标记，同时向开发者发送一个 terminal 通知。

关键代码逻辑：

读取文件 → 正则匹配 /^(\\*|body|html|:root)\\s*\\{/gm → 
如果匹配到 → 在匹配行的上方插入 /* [AI-Style-Guard] 以下全局选择器已被自动注释，如需保留请手动取消注释 */ →

注释掉整个规则块 →

输出警告到 console

这个脚本在前两个月的运行中，自动拦截了 14 次全局选择器污染。其中 12 次确实是误加（AI 生成的无意义全局重置），2 次是 AI 有意为之且被我手动恢复了（一次是需要设置全局 box-sizing，一次是需要定义全局 CSS 变量）。

2. 类名命名空间强制检查

脚本检查所有 AI 生成的类名是否以规定的命名空间（cld-）开头。如果发现不以该前缀开头的类名，会进行两个操作：

• 在类名前面自动拼接前缀（container → cld-container）
• 同步更新对应的 JSX/TSX/Vue 模板中的类名引用

这一步需要脚本具有一定的 AST 解析能力。我用的是 @babel/parser 处理 JSX/TSX，用 @vue/compiler-sfc 处理 Vue 组件，用 postcss 处理样式文件。

这里需要小心一点：不是所有的类名都需要加前缀。 如果 AI 的代码里引用了第三方 UI 库的类名（比如 Ant Design 的 ant-btn），加前缀会破坏功能。所以脚本里有一个“白名单”，包含 ant-、el-、arco- 等第三方前缀，遇到这些前缀直接跳过。

3. z-index 上限控制

这个功能来自我在一个 Dashboard 项目里的惨痛教训。当时 Claude Code 生成了一个气泡提示组件（Tooltip），z-index 被设为 99999，而项目的弹窗 z-index 是 1000。结果是：气泡提示覆盖在弹窗之上，但气泡提示本身不属于弹窗的 DOM 层级，导致弹窗内容无法点击。

后处理脚本会扫描所有 z-index 值，如果发现大于 1000，自动替换为 var(--z-tooltip, 950)（一个在项目中提前约定的 CSS 变量），同时发出警告。

我建议每个团队根据自己的项目实际情况设定一个“z-index 分级表”：

这张表建议写在项目的 README 或团队 Wiki 里，并且作为后处理脚本的 z-index 判断基准。

4. CSS 变量替换

AI 生成的代码中常常包含硬编码的颜色值。后处理脚本会尝试将这些硬编码值替换为项目的 CSS 变量。

这个操作需要谨慎，因为不是所有硬编码值都应该被替换。我的脚本处理逻辑是：

• 如果检测到的颜色值与某个 CSS 变量的默认值完全一致（比如 #1890ff 正好是 Ant Design 5 的 --ant-primary-color 默认值），自动替换为 var(--ant-primary-color)
• 如果检测到的颜色值与任何已知变量都不匹配，保留原值但添加注释提示开发者手动审查
• 脚本维护一个“项目色彩变量映射表”，每个项目可以根据自己的 Design Token 配置

在实际运行中，这个脚本每个月大约能帮我节省 2-3 个小时的手动样式审查时间。更大的价值在于：它把一些容易被忽略的样式问题，从“人工监控”变成了“自动拦截”。

六、与 Vue Scoped 和 CSS Modules 的衔接策略

这部分我打算尽量写具体。很多文章会告诉你“用 CSS Modules 就行”“用 scoped 就行”，但不会告诉你：当你把 AI 生成的代码引入已经使用了这些方案的项目时，到底有哪些细节会出错。

Vue Scoped 的三个坑

第一个坑：AI 不熟悉 :deep() 语法

Vue 的 <style scoped> 为当前组件的所有元素添加了一个唯一的 data-v-xxx 属性，CSS 选择器会被自动改写：

• 你写的 .card { color: red; }
• Vue 编译成 .card[data-v-f3a2b1] { color: red; }

这意味着：如果你在 scoped 样式中写了 .parent .child，Vue 只会给 .parent 加属性选择器，得到 .parent[data-v-f3a2b1] .child。如果 .child 是另一个子组件的根元素，它会因为缺少 [data-v-f3a2b1] 属性而匹配不到。正确的写法是 .parent :deep(.child)，这会编译成 .parent[data-v-f3a2b1] .child，注意，属性选择器只加在 .parent 上，.child 不加。

Claude Code 在生成 Vue 组件时，如果组件内部引用了其他组件（比如一个 UI 库的按钮），它可能会直接写 .search-box .ant-btn { ... }，这在 scoped 模式下不会生效。

我的经验是：在 Prompt 里明确告诉 AI，“如果你需要修改子组件或第三方组件的样式，必须使用 :deep() 包裹目标选择器。”

但仅靠 Prompt 不够。我的后处理脚本也加入了 scoped 检查：如果检测到 <style scoped> 块内存在未被 :deep() 包裹的、包含嵌套选择器的规则（如 .parent .child），脚本会标记警告。

第二个坑：scoped 不阻止字体等继承属性的穿透

即使你用了 scoped，font-family、color（在未显式设置的子元素上）、line-height 这类可继承属性，依然会穿透到子组件。

这意味着：如果你的 AI 组件在 scoped 里写了 font-family: 'Open Sans'，而子组件没有显式声明自己的 font-family，子组件的字体会变成 Open Sans。

这个问题在 scoped 层面无法解决。最佳实践是：在项目层级定义全局字体变量，AI 组件的样式通过 CSS 变量引用，而不是直接写字体声明。 我现在的规范是：所有 AI 生成的组件禁止直接设置 font-family，如果需要特殊字体，通过组件的 props 控制 class 切换。

第三个坑：scoped 对动态生成的内容无效

如果 AI 组件用 v-html 或者 JS 动态插入 DOM 元素，这些元素不会被 Vue 的 scoped 机制添加 data-v-xxx 属性，因此 scoped 样式对它们完全无效。

我在一个使用 Claude Code 生成富文本预览组件的场景中遇到这个问题。组件从 API 获取 HTML 字符串，通过 v-html 渲染。AI 在 <style scoped> 中写了 .content p { margin-bottom: 16px; }，但渲染结果中 <p> 标签并没有被加上 data 属性，样式不生效。

解决方案：将影响 v-html 内容的样式移到全局样式表中，使用命名空间限制作用范围（比如把样式封装在 .cld-RichPreview .content p 下，放在一个专门的 ai-components.css 文件中，不依赖 scoped 机制）。

CSS Modules 与 AI 生成的兼容性

CSS Modules 的隔离机制比 scoped 更彻底，它在编译时把类名完全替换为唯一哈希，从根本上避免了选择器冲突。

但问题在于：AI 需要在 JSX/TSX 中以特定语法引用这些模块化的类名。

React 中，标准的 CSS Modules 使用方式是：

import styles from './Component.module.css';

Claude Code 可能会写成：

// 或

第一种写法在 CSS Modules 项目中不会被正确哈希化；第二种写法使用字符串拼接，在运行时可能导致类型问题。

我在 Prompt 里明确要求 AI：“引用样式的语法统一为 className={styles.类名}，如需组合多个类名，使用 clsx 或 classnames 库，例如 className={clsx(styles.container, isActive && styles.active)}。”

同时，后处理脚本会检查 JSX 文件中是否存在 className="... " 这种字符串形式的类名引用（排除第三方组件名），如果发现有未被导入或未被哈希化的类名，自动标记。

SSR / Next.js 场景下的特殊问题

如果你在 Next.js 项目中使用 Claude Code 生成组件，需要额外注意 SSR 的样式水合（hydration）问题。

Next.js 在服务端渲染时，CSS 的加载顺序和客户端有所不同。如果 AI 组件依赖了一个在客户端才加载的 CSS 文件，首屏渲染可能会出现短暂的“样式闪烁”（Flash of Unstyled Content, FOUC）。

我的解决方案是：要求 Claude Code 生成的 CSS 代码不依赖任何运行时注入，所有样式要么通过 Next.js 的 _app.tsx 中的全局样式引入，要么使用 CSS Modules（Next.js 原生支持），要么放在 <style jsx> 中（但仅限简单场景）。

这个限制让 AI 生成组件的灵活性有所下降，但换来了 SSR 环境的稳定性。

七、与 UI 框架共存的实战策略

大部分使用 Claude Code 快速生成组件的场景，是在一个已经成熟的、使用 Ant Design 或 Element Plus 等项目上进行增量开发。

这种情况下，AI 组件需要和已有组件在视觉上保持一致，并且不能破坏框架的全局变量。

Ant Design 5.x 的共存策略

Ant Design 5 采用 CSS-in-JS（基于 @ant-design/cssinjs），所有样式在运行时生成，并且通过 Design Token 系统统一管理。

这带来两个挑战：

1. AI 生成的组件如何获取和使用 Design Token？
2. AI 组件的样式优先级如何与 antd 的运行时样式协调？

对于第一个问题，我的方案是：在 Ant Design 5 项目中使用 theme.useToken() Hook 获取当前主题的 Token，然后把 Token 对象传给 AI 组件作为 props。

import { theme } from 'antd';

function ParentComponent() {

const { token } = theme.useToken();

return <AISearchSelect token={token} />;

}

AI 组件内部通过 CSS 变量引用这些 Token：

对应 CSS：

.cld-SearchSelect .cld-SearchButton {
background-color: var(--primary-color);

}

这个方案让 AI 组件能够自动跟随 Ant Design 的主题切换，而无需硬编码颜色。

对于第二个问题，关键是要理解 Ant Design 5 的样式优先级机制。Ant Design 组件使用 :where() 伪类来保持较低的基础优先级，这样用户可以方便地覆盖。但如果 AI 组件的样式使用了常规选择器，它会天然高于 Ant Design 的 :where() 包裹的样式。

这意味着：如果你让 AI 写 .cld-SearchInput 的样式，它可能会在不经意间覆盖同页面中 Ant Design Input 的某些默认样式。 解决方法是：要求 AI 在修改 Ant Design 子组件样式时，必须使用和被修改组件相同的优先级策略（要么也用 :where()，要么通过 Ant Design 的 className prop 传递）。

这里有一个我反复试验后总结的技巧：不要尝试让 AI 写覆盖 Ant Design 组件样式的代码，而是让 AI 生成一个包装组件，通过 Ant Design 的 API 来定制样式。 例如，不要写 .cld-Input { border-radius: 0; }，而是让 AI 生成：

className={styles.cld_Input}

styles={{

input: { borderRadius: 0 }

}}

/>

通过 API 控制样式，比用选择器覆盖更稳定，升级 Ant Design 版本时也不容易出问题。

Element Plus 的共存策略

Element Plus 使用 SCSS 变量 + CSS 变量混合方案。与 Ant Design 5 不同，Element Plus 的样式在构建时就确定了，运行时主要通过 CSS 变量控制主题。

这意味着 AI 生成的组件可以比较安全地引用 Element Plus 的 CSS 变量（如 var(--el-color-primary)），因为这些变量在全局 :root 里已经定义好了。

但一个常见问题是：Element Plus 的某些组件（如 el-dialog）在打开时会给 body 添加 overflow: hidden 和 padding-right 来避免页面抖动。如果 AI 生成的组件也包含弹窗逻辑，可能会在这个行为和 Element Plus 产生冲突，例如 AI 组件在关闭弹窗时没有正确恢复 body 的 overflow，导致页面无法滚动。

处理方法是：在 Prompt 中要求 AI 生成弹窗相关组件时，直接复用项目的 UI 框架弹窗，而不是从零开始写弹窗逻辑。 比如明确说：“如果有弹窗需求，使用 Ant Design 的 <Modal> / Element Plus 的 <el-dialog>，不要自己写弹窗 HTML 和遮罩层。”

这个规则在我的实践中减少了大约 60% 的弹窗相关样式冲突。

八、Claude Code Prompt 工程：如何让 AI 写出“懂规矩”的样式代码

前面提到 S2P2 协议时，我给出了一个 Prompt 模板。但仅靠模板不够，Prompt 的设计也需要根据 AI 的理解特点进行调整。

我通过反复试验，总结出给 Claude Code 写样式相关 Prompt 的 5 条原则：

原则 1：先说限制，再说需求

Claude Code 倾向于把“需求”放在优先级第一位。如果你先说“生成一个带搜索的下拉选择器”，它会优先保证功能完整，样式部分可能就写得比较随意。

如果你先说“这个组件必须使用 CSS Modules，所有类名以 cld- 开头，不要修改任何全局样式”，它会在生成代码时主动遵守这些限制。

我在 30 组对比测试中验证了这个顺序效果：先说限制的 Prompt，AI 生成代码的样式合规率是 84%；先说需求的，合规率是 61%。

原则 2：给出“反例”，而不只是“规则”

只说“不要覆盖 Ant Design 的样式”不够具体。加上一个反例：“例如，不要写 .ant-btn { background: red; }，如果你想定制按钮颜色，应该通过 Ant Design 的 Button 组件的 color prop 或者 styles API 来实现。”

反例的作用是：把抽象的规则，转化为 AI 可以模式匹配的具体代码模式。

原则 3：使用“层级化”描述样式优先级

不要在 Prompt 里写一堆平铺的样式要求。用层级结构组织：

样式优先级（从高到低）：

组件内部状态样式（hover、active、disabled 等）
通过 props 传入的样式定制
组件默认样式
继承自全局 / UI 框架的样式

这种格式帮助 AI 理解样式之间的关系，而不是把它们当作孤立的属性列表。

原则 4：要求 AI 在输出代码前先“说出”它的样式策略

这是一个我自己发现的、效果显著但很少人用的技巧。

在 Prompt 结尾加上一句：“在生成代码之前，请先用 2-3 句话说明你打算如何处理该组件的样式隔离，以及你做了哪些假设。”

这个要求让 AI 在生成代码前先进行一次“自我审查”，显式地推理样式问题。在 20 次实验中，要求 AI 先“说出样式策略”后，样式冲突的出现率降低了约 28%。

原则 5：为样式代码提供独立审查点

如果你的组件比较复杂，可以在 Prompt 中要求 AI 把样式代码放在一个独立的代码块中，并标注：“以下为样式代码，请特别注意。”

这样做不是为了让代码更美观，而是因为：当 AI 把样式单独标注时，它对这个代码块的注意力会更高，写出来的样式质量也会更好。 这个观察来自我的主观判断，没有量化数据支撑，但在多次使用中感觉确实有效。

九、常见误区：开发者在 AI 样式问题上犯的 6 个错误

在前面的章节里，我主要讲“应该怎么做”。这一章专门讲“不应该怎么做”，以及为什么。

误区 1：看到样式被覆盖就加 !important

这是我见过最多的错误。开发者发现 AI 生成的组件样式被项目的全局样式覆盖了，第一反应是给 AI 的样式加 !important。

这个做法短期内解决了当前问题，但制造了一个更大的问题：!important 破坏了正常的 CSS 优先级体系。 后续如果有其他组件需要覆盖这个样式，只能再加一个 !important，形成恶性循环。

在我的项目里，后处理脚本会自动检测所有的 !important 声明，如果发现是 AI 生成的代码引入了 !important，脚本会阻止提交并给出警告。

正确的做法是：找到样式被覆盖的根因（可能是加载顺序、选择器特异性、或者层叠上下文问题），然后从源头解决。

误区 2：让 AI 从头写所有的 CSS

有些开发者认为“既然 AI 写样式容易冲突，那就让它别写样式了，只写逻辑，样式我手写”。

这个策略的问题是：你放弃了 AI 在样式生成上的效率优势。 Claude Code 生成一个中等复杂度组件的 CSS 大约需要 10 秒，如果你手写，可能需要 10-30 分钟。

更好的做法是：让 AI 生成基础的、符合规范约束的样式代码，然后人工审查和微调。审查的时间通常只有手写时间的 1/5 到 1/3。

误区 3：不清理被替换掉的 AI 组件样式

前面我提过 Coverage 面板的数据：AI 生成的旧组件样式如果不清理，会变成“沉睡污染”。但很多团队在迭代组件时，只关注替换 JS 逻辑，忘记清理旧 CSS。

我在 CI/CD 中加了一个步骤：每次构建前，运行一个脚本比较 AI 组件目录和对应的样式文件，如果发现有样式文件找不到对应的组件文件，就发出警告。

误区 4：假设所有项目都需要相同的样式隔离强度

不同的项目对样式隔离的需求不同：

• 基础组件库项目：需要最高级别的样式隔离（因为不知道用户会在什么环境下使用你的组件）
• 内部管理系统：中等隔离（因为你了解内部项目的技术栈和规范）
• 快速原型/Demo：低级别隔离（可以用最简单的方式，因为代码可能不会长期维护）

根据项目类型选择合适的隔离强度，而不是一刀切地用 CSS Modules 或 scoped。

误区 5：把 AI 组件的样式问题归咎于 AI

当你发现一个样式冲突时，容易产生“这个 AI 写的代码质量不行”的判断。

但在大多数情况下，问题不是 AI 写错了什么，而是你没有告诉它不应该写什么、或者项目的样式环境有什么特殊之处。

改变这个心态很重要，因为它影响你的调试策略。 如果你认为“AI 代码质量不行”，你会倾向于重写整个样式。如果你认为“AI 缺少项目的上下文信息”，你会去找到缺失的上下文并补充给它，后者通常解决问题的速度更快。

误区 6：没有建立团队级的 AI 样式规范

如果团队中有 3 个人用 Claude Code，每个人各自的 Prompt 里定义了自己的样式规范，那么三个人的 AI 组件放到一起时，仍然会产生冲突。

我强烈建议：团队级 AI 样式规范应该是和 .eslintrc、.prettierrc 平级的项目配置文件。 可以是一个 ai-style-guide.md 文件，存放在项目根目录，所有人使用 Claude Code 时都引用它。

十、建立可持续的 AI 样式质量管理闭环

前面九章讲的是“如何发现问题、如何解决问题”。这一章讲的是“如何让这套方案持续运转”。

度量先行：定义“样式冲突率”

如果你不能度量问题，你就不能管理问题。

在我的团队里，我定义了一个简单的指标：样式冲突率 = 被标记为“存在样式问题”的 AI 组件数 / AI 生成的总组件数（以 Sprint 为单位统计）。

统计方法：

1. 所有 AI 生成的组件在 PR Review 时，增加一个“样式检查”标签。
2. Review 者如果发现样式冲突（包括全局污染、命名冲突、框架不一致等），将该 PR 标记为“样式问题”。
3. Sprint 结束时，计算标记 PR 数量 / AI 组件总数。

有了这个指标后，你可以：

• 判断你的 S2P2 协议和后处理脚本是否在持续生效
• 识别哪些类型的组件样式冲突率更高，针对性地优化 Prompt
• 在团队 Retro 中，用数据而不是感觉来讨论 AI 代码质量

审查清单制度化

任何人都可能会在 Code Review 时遗忘样式检查的重点。我在团队里推行了一个简单的 AI 组件样式审查清单：

• [ ] 是否存在全局选择器（*、body、html）的直接样式？
• [ ] 所有类名是否使用了团队约定的前缀？
• [ ] 是否有硬编码的颜色、字体、间距值？能否替换为 CSS 变量？
• [ ] z-index 是否在可控范围内？是否与项目的层级表一致？
• [ ] 是否使用了 !important？如是，是否有充分的理由？
• [ ] 如果是 Vue 项目，:deep() 使用是否正确？
• [ ] 如果是 React 项目，CSS Modules 的类名引用是否正确？
• [ ] 是否有可能影响 UI 框架现有组件的样式覆盖？

这个清单开始推行时，很多开发者觉得繁琐。但执行了三个 Sprint 后，样式冲突率从 15% 降到了 4%。现在团队已经把这张清单当成了 Review 时的肌肉记忆。

AI 样式的版本管理与回退

即使有再多规范、再多脚本，偶尔还是会出现 AI 生成的样式代码在测试环境正常、但在生产环境出现意外冲突的情况。

因此，所有 AI 生成的样式代码必须有清晰的版本标记。 我的做法是：

• 在每个 AI 生成的样式文件头部添加注释：/* AI-Generated by Claude Code | Date: 2024-06-15 | Component: SearchSelect v1.2 */
• 如果该样式文件经过人工修改，修改者在注释后面添加 /* Modified by [name] | Date: 2024-06-16 | Changes: z-index adjustment */

这样做的好处是：当生产环境出现样式问题时，你可以快速追溯到是 AI 的生成本身有问题，还是人工修改引入了新问题。

持续优化 Prompt 模板

你的 S2P2 协议不应该是静态的。每发现一个新的、之前没有被覆盖的样式冲突模式，就应该更新协议，把新的约束加进去。

我的协议从最初的 5 条规则（项目初始），发展到现在的 12 条（经过 8 个月迭代）。每次更新后，我都会对比更新前后的“样式冲突率”变化，确保添加的规则确实有效、而不是在给 AI 增加不必要的限制。

十一、总结：AI 代码的质量标准应该由你来定义

回到文章开头我的那次“三小时排查”，如果当时我已经有了这篇文章里总结的这套体系，那天的场景会完全不同：

1. 生成前：我会在 Prompt 里声明项目的 Ant Design 版本、CSS Modules 方案、cld- 前缀规范、以及禁止全局选择器。
2. 生成时：AI 会在写样式代码之前先说出它的样式策略，我可以在它写代码之前就发现潜在问题。
3. 生成后：后处理脚本会自动扫描生成的样式文件，拦截任何全局选择器、检查命名前缀、验证 z-index 范围。
4. 审查时：Review 清单确保我不会遗漏关键检查项。
5. 长期：冲突率指标帮助我持续判断这套策略是否有效。

这篇文章最核心的观点，我愿意再重复一遍：解决 AI 生成组件的样式冲突，关键不是提升 AI 的能力，而是提升你管理 AI 输出的能力。

AI 是你的代码生成器，但样式规范、命名约定、审查标准，这些是“规则”，规则应该由你定义、由你维护、由你持续优化。

当你的规则体系足够完善时，AI 会发生一个有趣的变化。它不再是一个你需要时刻盯着的“问题制造者”，而是一个你能够放心放权的“可靠执行者”。

我开始使用这套体系后的感受是：我不再害怕让 AI 写样式代码了。 因为我有了一个稳定的“接收框架”，我知道它的输出会被自动检查、自动修正，而我需要做的事情只是审查和微调。

建立这个框架确实需要投入时间。我把我的后处理脚本从第一版到第三版大概花了三个周末，完善 Prompt 模板用了两周的碎片时间，推行团队审查清单又花了一个月。但长期来看，这个投入已经收回了数十倍的成本。

如果你只从这篇文章里带走一件事，我希望是这一件：在“让 AI 写代码”之前，先花一点时间定义“AI 应该怎么写代码”。 这比事后的任何修复都更有效。

你的下一步行动，可以是：

1. 打开你最近一个让 Claude Code 参与的项目，检查 AI 生成的样式文件里有没有全局选择器、有没有命名冲突。
2. 花 20 分钟写一份你自己的 S2P2 第一层协议（项目基础信息声明），下次用 Claude Code 时先粘贴这段协议。
3. 如果你在团队里，把这篇发给同事，讨论要不要建立团队级的 AI 样式规范。

如果你已经有类似的经验，或者有其他不同的策略，也欢迎在评论区分享。我还在持续优化这套体系，每个人的实践经验都可能带来新的启发。