用 Claude Code 做前端开发：我踩过的坑和摸出的门道

写在前面

我大概是从2025年底开始用 Claude Code 的。之前一直用 通义灵码，觉得 AI 辅助编程就是那个味儿——直到试了 Claude Code。

但说实话，刚开始用的那两周，我是崩溃的。

我说"帮我做个登录页面"，它给我一个丑得不能看的 form；我说"样式不对，改好看点"，它把字体改成了 Comic Sans；我说"不是这个意思"，它开始跟我道歉然后继续理解错。

后来我花时间琢磨了一下，发现不是 Claude Code 不好用，是我不会用。这篇文档就是记录我怎么从"来回改10遍"到"一次命中80%"的。

如果你也在用 AI 辅助编程，希望我踩的坑能帮你省点时间。

第一部分：为什么 AI 生成的代码总是跟你想的不一样

坑1：我以为 AI 能读懂我的想法

现实：它不能。

刚开始用的时候，我最常见的对话是这样的：

1. 我："帮我做个登录页面"
2. ClaudeCode：[生成了一个极简的 form，两个 input 一个 button]
3. 我："不是，要好看一点"
4. ClaudeCode：[加了点 margin 和 padding]
5. 我："……"

问题在哪？我以为"登录页面"是个明确的需求，但实际上这个词在每个人脑子里长的都不一样：

• 有人想要左图右表的时尚布局
• 有人想要居中的卡片式设计
• 有人想要全屏背景 + 玻璃态效果

Claude Code 不知道你要哪种，所以它选了一个"最不出错"的方案——也就是最难看的那个。

我是怎么解决的

后来我再提需求，会先花5分钟写一段"图片描述"，就像在跟一个没见过登录页面的人解释一样：

1. "我要做一个登录页面，具体是这样的：
2. - 整体布局：左边占40%宽度放品牌展示（可以是个大图或者 Slogan），右边放表单
3. - 表单样式：白色卡片，有点阴影，圆角大概8-12px
4. - 颜色：主色调用蓝色系，具体色值我没定，你先选一个常见的蓝色
5. - 交互：输入错的邮箱格式时，输入框变红，下面出一行红色提示文字
6. - 响应式：手机上左右布局改成上下，品牌展示区缩小到顶部
7. - 技术栈：React + Tailwind CSS"

第一次写完这么长一段，我自己都觉得麻烦。但效果是真的好——它第一次生成的版本，已经能用，只需要微调。

小结：如果你脑子里有画面，就把它描述出来。别省那5分钟，省下来的是后面1小时的改代码时间。

坑2：AI 总是"过度发挥"

现实：你说要一个按钮，它可能给你整一套组件库。

这件事特别烦。有一次我说"帮我做个下拉菜单"，结果它给了我一个支持多级、支持搜索、支持异步加载的"完整解决方案"。而我只是想要一个最简单的 <select> 替代品。

后来我观察了一下，发现 Claude Code 有个特点：它倾向于给你"最佳实践"级别的答案。你说要 A，它会把 A+B+C+D 都做了，因为"在生产环境中你迟早会需要 B/C/D"。

我是怎么解决的

现在我在提需求的时候，会明确说"边界"：

1. "我要一个下拉菜单，具体功能：
2. - 点击展开，选择后收起
3. - 就这么简单
5. 先不要做：
6. - 多级菜单（以后再说）
7. - 搜索过滤（暂时不需要）
8. - 异步加载（数据量很小，不需要）
10. 先用最简单的方式实现，能跑就行"

关键词是"先不要做"和"暂时不需要"。明确告诉它哪些东西这次不做，它就不会自作主张帮你"提前规划"。

坑3：聊着聊着，它就"忘"了

现实：上下文窗口是有限的。

这是我踩过的最隐蔽的坑。前5轮对话还好好的，我提到"用 Tailwind 就行，别用 CSS Modules"，它也答应得好好的。结果到第8轮，它突然开始给我写 CSS Modules 的代码。

我一开始以为是 Claude Code 的问题，后来才明白：对话太长了，早期的信息被"压缩"了。它不是忘了，是它的上下文窗口装不下所有东西了。

我是怎么解决的

两个办法：

办法1：定期总结

每聊个3-5轮，我会说一句："帮我总结一下现在我们的技术决策和已完成的功能"。它会给我一个清单，然后我把这个清单复制到新的对话里继续。虽然麻烦，但比它"失忆"强。

办法2：写进项目文件

后来我发现更简单的办法是把关键信息写进项目里的 CLAUDE.md 文件（Claude Code 会自动读这个文件）。内容大概是这样：

1. # 项目约定
3. -技术栈：React+TypeScript+Tailwind CSS
4. -禁止使用：CSS Modules、Styled-components（保持统一）
5. -状态管理：优先用 useState，复杂场景才用 useReducer
6. -代码风格：严格TypeScript，不允许 any 类型

这样每次新开对话，它都会先读这个文件，不会乱来。

第二部分：怎么让 AI 真正理解你要什么

这部分是我花时间最多的。我发现"会提问"是跟 AI 协作的核心技能。

方法1：用"五维描述法"（这名字是我自己起的）

我不知道别人是怎么做的，但我发现如果需要描述一个 UI 组件，从以下五个角度去说，Claude Code 的理解准确率会高很多：

1. 视觉（长得什么样）

别只说"好看的按钮"，具体点：

• 尺寸：高度 40px，水平左右各 16px padding
• 颜色：背景 #3B82F6，hover 时加深一点
• 字体：14px，白色，中等字重

2. 结构（代码怎么组织）

如果你对代码组织有要求，就说出来：

• "这个组件要拆成三个子组件"
• "状态放在父组件，通过 props 传下去"
• "用自定义 Hook 封装逻辑"

3. 行为（用户怎么操作）

这一步很多人会漏。你脑子里知道点击按钮后会有一个 loading 动画，但你不说出来，AI 就不知道：

1. "按钮的交互流程：
2. 1. 用户点击 → 按钮禁用 + 显示 loading spinner
3. 2. 请求成功 → 跳转到首页
4. 3. 请求失败 → 按钮恢复 + 上方显示红色错误提示
5. 4. 错误提示 5 秒后自动消失"

4. 数据（传什么、收什么）

如果你有现成的数据结构，直接贴代码。比描述管用10倍：

1. // 这是我期望的表单数据结构
2. interfaceLoginForm{
3. email:string;
4. password:string;
5. rememberMe:boolean;
6. }

5. 约束（什么不能用）

这个特别重要，尤其是团队项目：

1. "注意：
2. - 不要用 antd 的 Button 组件（项目里没引入 antd）
3. - 不要写内联样式（统一用 Tailwind）
4. - 不要使用 any 类型"

方法2：给参照物 + 说差异

如果你想做一个跟现有东西类似但有点不同的功能，别从零描述，给参照物：

1. "参考项目里现有的 src/components/UserForm.tsx
2. 照着那个结构再写一个 ProductForm
4. 区别是：
5. - 字段不一样（具体字段我列在下面）
6. - 布局从垂直改成两列
7. - 多一个图片上传的功能
9. 其他的（验证逻辑、错误提示样式、loading 状态）都跟 UserForm 一样"

这个方法我特别喜欢，因为 Claude Code 很擅长"模仿"。给它一个参照，它能很好地保持代码风格一致。

方法3：说不清楚就画

有一次我要做一个比较复杂的布局，文字描述了三遍它都没理解。后来我直接画了个 ASCII 图：

1. "页面布局大概是这样：
3. +------------------------------+
4. | Header（固定顶部） |
5. +----------+-------------------+
6. | | |
7. | Sidebar | Main Content |
8. | (200px) | (剩余空间) |
9. | | |
10. +----------+-------------------+
12. 移动端时 Sidebar 隐藏，通过汉堡菜单唤出"

然后它就理解了。

所以现在如果遇到布局类的需求，我会直接画个草图（不需要精美，能看就行），或者用 Figma 做个简单的线框图截图给它看。

第三部分：实战中的工作流程

这部分是我实际开发中总结出的"比较顺手"的流程。不一定对，但对我有用。

场景1：从零开始做个新功能

我以前的习惯是一上来就让 AI "帮我做个 XXX"，然后看着它生成的代码发呆——能用，但不是我想要的。

现在我改成"先设计，后编码"：

第1步：先聊方案，不写代码

1. "我要做一个用户管理的页面，先帮我理一下思路：
2. - 需要哪些组件？
3. - 数据怎么流动？
4. - 用什么状态管理？
6. 你先给我文字方案，我确认后再写代码"

这一步很关键。让它在"设计模式"层面跟你对齐，比直接生成代码然后改要高效。

第2步：定义数据结构

1. "好，那就按你说的方案来。
2. 先帮我定义 TypeScript 接口：
3. - User 数据类型
4. - 组件 Props 类型
5. - API 响应的类型
7. 定义完给我看看，确认后再写逻辑"

第3步：写核心逻辑（不管样式）

1. "现在写组件逻辑，但先不管样式。
2. 我要的是：
3. - 能正确渲染数据
4. - 能处理用户操作
5. - 有基本的错误处理
7. 样式后面再调"

这一步的目标是"让功能跑通"。代码丑没关系，先让它 work。

第4步：打磨 UI

功能 OK 了，再来调整样式。这时候你的需求描述会更准确，因为你知道代码长什么样了。

第5步：补测试

最后再写测试。我以前会先写测试，但后来发现用 AI 辅助开发时，先让功能稳定再补测试会更顺——因为需求可能在开发过程中变化，先写测试容易反复改。

场景2：改现有代码

这部分我踩的坑最多。有一次我让 Claude Code "帮我优化一下这个组件"，它直接给我重写了一遍。功能是对的，但把我原来的一些"坑"给填了——问题是那些"坑"是有原因的，结果线上出了 bug。

我现在的安全流程：

第1步：先让它读懂代码

1. "在改代码之前，你先帮我理解一下这个组件：
2. 1. 它主要做什么？
3. 2. 状态是怎么管的？
4. 3. 有哪些副作用（useEffect 里的东西）？
5. 4. 有没有什么奇怪的写法（我可能当时有原因）？
7. 只做分析，不要改代码"

让它先输出一段"代码解读"，你确认它真的理解了，再进入下一步。

第2步：明确改动范围

1. "好，我要改的是 handleSubmit 这个函数，具体改动：
2. - 加表单验证
3. - 验证不通过时不提交
5. 不改的是：
6. - 验证通过后的提交逻辑（保持不变）
7. - 错误处理（保持不变）"

第3步：小步修改，频繁确认

1. "我们分步来：
2. 1. 先写 validateForm 函数
3. 2. 我确认后，你再改 handleSubmit 调用它
4. 3. 每改完一步，我测试一下
6. 不要一次全改完"

这个方法虽然慢，但安全。尤其是改别人代码（或者自己很久以前写的代码）的时候。

场景3：调试 Bug

这部分 Claude Code 其实挺好用的，但前提是你得会问。

我的调试流程：

第1步：说清楚 Bug 的现象

别只说"有 Bug"。说清楚：

• 什么操作触发的？
• 期望的结果是什么？
• 实际发生了什么？
• 有什么错误信息？

1. "有个 Bug：在用户管理页面，删除了一个用户后，列表没有刷新
3. 重现步骤：
4. 1. 打开 /users 页面
5. 2. 点击某个用户行的"删除"按钮
6. 3. 确认删除
7. 4. 弹窗提示"删除成功"，但列表还在
9. 我看了一下代码，删除接口是调成功了的，就是没重新获取列表"

第2步：让它提假设，你来判断

1. "我怀疑是这几个原因：
2. 1. 删除成功后没有重新调 fetchUsers
3. 2. 或者重新调了，但组件没重新渲染
5. 你帮我看看代码，是哪个问题？"

第3步：改完验证

修完之后，别急着走，测一下相关的功能有没有被搞坏。

1. "改完了，你帮我列一下需要测的场景：
2. - 正常删除 ✅
3. - 删除后列表刷新 ✅
4. - 删除失败时的提示 ✅
5. - ...还有啥？"

第四部分：我常犯的错（希望你别犯）

错误1：一次性提太多要求

1. 我："帮我做个表单，要验证，要动画，要响应式，要支持暗黑模式，还要有单元测试"
3. ClaudeCode：[试图一次性做完，结果每个都做了但每个都做的不好]

正确做法：分优先级。这次只做核心功能，下次再加动画，再下次改响应式。

AI 跟我一样，一次做太多事情容易做不好。

错误2：不会就说"不对"

有时候 Claude Code 生成的东西不对，但我说不清楚哪里不对，就一直说"不对，再改改"。

这样效率极低。

现在我会：

• 截图，圈出来哪里有问题
• 或者给参考："我希望的效果类似这个网站的 XXX"
• 或者干脆说："我描述不清楚，你给我三个方案，我选一个"

错误3：忘了 AI 会"撒谎"

有一次 Claude Code 很自信地告诉我："你可以用 react-hook-form 的 v8 版本的新 API"。

我信了，结果跑不起来。查了一下，那个 API 根本不存在，是它编的。

现在的习惯：如果它提到了具体的 API 或库，我会：

1. 去官方文档查一下是不是真的
2. 或者直接运行代码，看能不能编译通过

AI 的"自信"和"正确"是两回事。

错误4：没有备份就大改

这个坑我不小心踩过一次。让 Claude Code 重构了一段代码，结果越改越乱，想回退发现...

1. git status
2. # 一片红色，没提交

现在的铁律：

• 改代码之前，先 git commit
• 大改动开新分支
• 每改完一个功能点，提交一次

AI 辅助开发不代表你可以偷懒不写提交信息。

第五部分：一些好用的 Prompt 模板

这部分是我自己常用的，你可以直接复制去用，但根据你的场景改改。

模板1：创建新组件

1. 创建一个[组件名]组件
3. 功能：[用大白话描述这个组件是干嘛的]
5. 技术：
6. -React+TypeScript
7. -样式用[Tailwind CSS / CSS Modules/其他]
8. -状态用[useState / useReducer /其他]
10. 长这样：
11. [描述布局、颜色、交互，能多详细就多详细]
13. Props：
14. [列出你想要的Props，包括类型]
16. 注意：
17. -先实现功能，样式可以后面再调
18. -TypeScript要严格，不要用 any

模板2：改现有代码

1. 重构[文件路径]
3. 为什么要改：
4. [说明原因，是性能问题？还是代码太乱？]
6. 保留：
7. -[列出不能动的部分]
9. 改动：
10. -[列出要改的部分]
12. 方案：
13. 我考虑过两个方案：
14. -方案A：[描述]，好处是XXX，坏处是XXX
15. -方案B：[描述]，好处是XXX，坏处是XXX
17. 你帮我选一个，或者给我更好的建议

模板3：调试 Bug

1. 有个Bug修不掉，帮我看看
3. 现象：
4. [描述Bug现象]
6. 重现步骤：
7. 1.[步骤1]
8. 2.[步骤2]
9. 3.[步骤3]
11. 错误信息：
12. [粘贴错误栈]
14. 我已经试过：
15. -[排查1]
16. -[排查2]
18. 你帮我分析一下可能的原因，按可能性排序

第六部分：资深用户才知道的门道

这部分是我用了半年多之后，才慢慢摸索出来的。前面的内容能让你"用起来"，这部分能让你"用得爽"。

门道1：CLAUDE.md 怎么写一个"好用"的版本

前面提到要把规范写进 CLAUDE.md，但没说怎么写才真的有用。我踩过坑——写了跟没写一样。

我现在的写法：

1. # 项目规范（Claude Code 用）
3. ## 技术栈（必须遵守）
4. -框架：React18+TypeScript5.x
5. -样式：Tailwind CSS 3.x（禁止 CSS Modules、Styled-components）
6. -状态：useState 优先，复杂场景用Zustand（不用Redux）
7. -请求：Axios封装在 src/utils/request.ts
9. ## 代码风格
10. -严格TypeScript：禁止 any，实在不行用 unknown
11. -组件命名：PascalCase，文件名用小写+横杠（user-form.tsx）
12. -导入顺序：第三方库→内部模块→样式→类型
13. -每个函数必须有JSDoc注释（哪怕很简单）
15. ## 禁止事项（重要！）
16. -不要用 antd / MUI 等 UI 库（项目统一不用）
17. -不要写 console.log（用项目封装的 logger）
18. -不要使用Math.random()做 key（用 crypto.randomUUID()）
19. -不要在生产环境用 alert（用 antd 的 message 或项目 toast）
21. ## 项目结构约定
22. src/
23. components/# 通用组件（可被多个页面复用）
24. pages/# 页面级组件（每个页面一个文件夹）
25. hooks/# 自定义 Hooks
26. utils/# 工具函数
27. types/# TypeScript 类型定义
29. ## 常用命令
30. -启动：npm run dev
31. -构建：npm run build
32. -测试：npm run test
33. -Lint：npm run lint
35. ## 已知坑（Claude Code 容易踩的）
36. - src/utils/request.ts 里有个自定义的超时逻辑，别改
37. -登录态存在 localStorage 的 token 字段，不是 localStorage
38. -路由用 react-router-dom v6，但 navigate 的用法有封装，看 src/hooks/useNavigation.ts

为什么这样写？

• 把"禁止事项"单独列出来，Claude Code 会特别注意
• "已知坑"是给 AI 看的，不是给人看的，非常有用
• 常用命令写进去，它帮你跑测试的时候不会跑错

门道2：用 @ 引用文件，别复制粘贴

Claude Code CLI 支持用 @文件名 引用文件内容，但这个功能很多人不知道。

用法示例：

1. "帮我改一下 @src/components/UserForm.tsx 的验证逻辑
2. 参考 @src/utils/validators.ts 里的工具函数"

为什么要这样用？

• 比复制粘贴代码干净
• Claude Code 会自动读取文件内容，不会"看错版本"
• 支持多个 @ 同时引用

进阶用法：

1. "看完 @src 整个目录，帮我找出所有用了 any 类型的地方"

（这会让 Claude Code 递归读取 src 下的文件，适合代码审查场景）

注意：引用大文件时要小心，Claude Code 读大文件会消耗很多 token。如果文件超过 500 行，建议只引用需要改的部分：

1. "看 @src/components/UserForm.tsx 的第 45-80 行，帮我改一下验证逻辑"

门道3：多文件同时编辑，要明确告诉它范围

Claude Code 可以同时改多个文件，但你需要明确告诉它。否则它可能只改了一半。

错误示范：

1. "帮我加一个退出登录的功能"

（它可能只改了 Header 组件，忘了改路由守卫）

正确示范：

1. "加一个退出登录的功能，需要改这些地方：
2. 1. src/components/Header.tsx（加退出按钮）
3. 2. src/hooks/useAuth.ts（加 logout 函数）
4. 3. src/App.tsx（退出后跳转到登录页）
5. 4. src/types/auth.ts（如果需要新类型的话）
7. 你帮我列一下改动计划，我确认后你再改"

关键技巧：

• 先让它列"改动计划"，你确认范围后再执行
• 改完后让它列"改动清单"，你对照检查

门道4：Token 成本和对话长度管理

资深用户会在意这个——长对话很贵，而且效果会下降。

我的策略：

1. 每完成一个大功能，开新对话

• 别在一个对话里聊超过 50 轮
• 把重要决策写进 CLAUDE.md，新对话会自动读

2. 用 /compact 压缩上下文（Claude Code CLI 特有命令）

• 它会把前面的对话压缩成摘要，节省 token
• 但压缩后"细节"可能丢失，重要信息要提前写进文件

3. 大文件不要一次性给 AI 读

• 一个 2000 行的文件，它读起来慢且贵
• 先让它"只读需要改的部分"

经验值：

• 一个小功能（单个组件）：大概 5000-10000 tokens
• 一个中等功能（3-5 个文件）：大概 20000-30000 tokens
• 如果对话超过 50000 tokens，考虑开新会话

门道5：什么时候不该用 Claude Code

有些场景，手写比 AI 快。

不该用的场景：

• 很简单的代码：写一个 onClick 处理函数，自己写 30 秒，描述给 AI 要 2 分钟
• 性能关键的代码：AI 生成的代码往往"能跑但不够快"，需要你懂底层去优化
• 你需要学习的东西：让 AI 帮你写，你自己还是不会（比如你想学 React Query，就别让它帮你写）
• 调试诡异 Bug 的前 10 分钟：先用传统方法（看错误栈、打 log、用 DevTools），确定方向后再让 AI 帮你改

该用的场景：

• 样板代码（组件骨架、类型定义、测试模板）
• 重构（"帮我把这个类组件改成函数组件"）
• 写测试（AI 很擅长写边界情况测试）
• 代码解释（"这段代码在干嘛？"）

门道6：Claude Code 会"伪造"看起来合理的代码

比"撒谎"更危险的是，它生成的代码看起来完全合理，但实际上是编的。

典型案例：

1. // Claude Code 生成（假的 API）
2. import{ useForm }from'react-hook-form/v7'// 这个路径不存在
3. import{ validateEmail }from'~/utils/validators'// 这个文件我没告诉它有
5. // 真实的用法应该是
6. import{ useForm }from'react-hook-form'

防范措施：

1. 让它列"依赖清单"
   1. "你用了哪些第三方库和内部模块？列出来我确认一下"
2. 新引入的库，让它说明用途
   1. "你为什么要用 lodash 的 debounce？原生 setTimeout 不行吗？"
3. 运行代码前先 Review

• 别直接 npm run dev，先肉眼看一下它改了啥
• 重点关注 import 语句，那是它最容易"造假"的地方

门道7：让 Claude Code 解释它生成的代码

很多使用者只看"结果对不对"，不要求解释。这导致后面维护困难——代码是 AI 写的，你不懂，改不动。

我的习惯：

1. "代码写完了，你给我解释一下：
2. 1. handleSubmit 里的 async/await 是怎么处理的？
3. 2. 为什么要用 useCallback 包一层？
4. 3. 如果以后要加新字段，我该改哪里？"

好处：

• 你真正理解了代码，后面改起来不慌
• 它能解释清楚 = 代码逻辑清晰；它解释不清 = 代码可能有坑

门道8：团队协同时的 CLAUDE.md 管理

如果你们团队多人用 Claude Code，需要统一规范。

我的建议：

1. 把 CLAUDE.md 提交到仓库

• 每个人新 clone 项目，Claude Code 自动读取规范
• 有变更时，像改文档一样走 PR 流程

2. 分模块写多个规范文件

• CLAUDE.md（全局规范）
• src/components/CLAUDE.md（组件规范）
• src/utils/CLAUDE.md（工具函数规范）

3. 定期复查 AI 生成的代码

• 每周挑 2-3 个 AI 写的文件，人工 review
• 发现共性问题，更新到 CLAUDE.md

第七部分：Vue 项目专项补充

我用 Vue 的时间比 React 短，但足够发现一些Vue 特有的坑。如果你用 Vue 3 + Claude Code，这部分可能帮你省点时间。

Vue 与 React 在 Claude Code 使用上的核心差异

差异1：Options API vs Composition API

Claude Code 默认倾向于生成 Composition API（因为"现代"），但你的项目可能在用 Options API。

解决方法：在 CLAUDE.md 里明确写出来：

1. ## Vue 版本规范
2. -使用Vue3+Composition API（<script setup>）
3. -禁止使用Options API（除非维护旧代码）
4. -状态管理用Pinia，不用Vuex
5. -组件样式用<style scoped>，不用 CSS Modules

差异2：响应式系统的"陷阱"

Vue 的响应式系统比 React 的 state 更容易让 AI "理解偏"。

典型案例：

1. <!-- Claude Code 生成（有坑） -->
2. <scriptsetup>
3. import{ ref } from 'vue'
5. const user = ref({ name:'张三', age:25})
7. // 坑：直接修改 ref 的内部值，响应式可能失效
8. const updateName =()=>{
9. user.value.name ='李四'// 有时能触发响应式，有时不能
10. }
11. </script>

正确写法（AI 需要明确指导）：

1. <!-- 你应该告诉 AI 这样写 -->
2. const updateName = () => {
3. user.value = { ...user.value, name: '李四' } // 新对象，确保响应式
4. }

所以，在 Vue 项目里，我会在 CLAUDE.md 加这条：

1. ## Vue 响应式规范
2. -ref的.value 修改要生成新对象（确保响应式）
3. - reactive()只用在对象类型，基本类型用ref()
4. -计算属性用 computed()，不要用 watch()模拟计算属性
5. -组件 emit 的事件名用 kebab-case（update:user-name）

差异3：Template 里的指令，AI 容易写错

Vue 的 template 语法（v-if、v-for、@click）跟 JSX 不一样，Claude Code 有时会"混着写"。

常见错误：

1. <!-- 错误：在 Vue 里用了 JSX 语法 -->
2. <template>
3. <divonClick={handleClick}><!-- 这是 React 写法 -->
4. </div>
5. </template>
7. <!-- 正确：Vue 模板语法 -->
8. <template>
9. <div @click="handleClick">
10. </div>
11. </template>

解决方法：给 AI 明确的"禁止事项"：

1. ## Vue 模板规范
2. -事件绑定用@click，禁止用 onClick={}
3. -条件渲染用 v-if，禁止用&&短路运算
4. -列表渲染用 v-for，禁止用.map()
5. -双向绑定用 v-model，禁止用 value + onChange 手动绑定

Vue 项目 CLAUDE.md 完整示例

1. # Vue 项目规范（Claude Code 用）
3. ## 技术栈（必须遵守）
4. -Vue3.4+（<script setup>+Composition API）
5. -TypeScript（严格模式，禁止 any）
6. -样式：Tailwind CSS +<style scoped>
7. -状态管理：Pinia（不用Vuex）
8. -路由：VueRouter4.x
9. -请求：Axios封装在 src/utils/request.ts
11. ## 禁止事项（重要！）
12. -不要用Options API（除非维护旧代码）
13. -不要写 onClick={}（这是React写法，Vue用@click）
14. -不要写 v-if和 v-for在同一个元素上（Vue会警告）
15. -不要用 index 做 key（用 id 或 crypto.randomUUID()）
16. -不要在生产环境用 console.log（用封装的 logger）
18. ## 组件规范
19. -组件命名：PascalCase（如UserProfile.vue）
20. -文件名：kebab-case（如 user-profile.vue）
21. -Props定义：必须用 defineProps<{...}>()的TypeScript写法
22. -Emit定义：必须用 defineEmits<{...}>()的TypeScript写法
23. -事件名：kebab-case（如@update:user-name）
25. ## 响应式规范
26. -基本类型用ref()，对象类型用 reactive()
27. -修改ref的值要生成新对象（确保响应式）
28. -计算属性用 computed()，不要用 watch()模拟
29. - watch()要显式声明深度监听：watch(()=> state, handler,{ deep:true})
31. ## 项目结构
32. src/
33. components/# 通用组件
34. views/# 页面级组件（路由对应的组件）
35. router/# Vue Router 配置
36. stores/# Pinia stores
37. utils/# 工具函数
38. types/# TypeScript 类型
39. assets/# 静态资源
41. ## 常用命令
42. -启动：npm run dev
43. -构建：npm run build
44. -测试：npm run test
45. -Lint：npm run lint
47. ## 已知坑（Claude Code 容易踩的）
48. -<style scoped>里用子组件选择器要加:deep()（不能直接写子组件类名）
49. - v-for必须要有:key，且不要用 index（除非列表是静态的）
50. -Pinia store 要在 main.ts 里 app.use(pinia)，不能只import
51. -路由守卫用 beforeEach()，不要用 watch(route)模拟

Vue 特有坑点（Claude Code 容易写错）

坑1：在

1. ## 交互流程
3. 1.用户告诉你组件名称和功能
4. 2.你先列出Props和Emits的设计，让用户确认
5. 3.用户确认后，再生成完整代码
7. 不要一次生成太多代码，先让用户确认设计。

怎么用？

在 Claude Code 里说：

1."用 vue-component skill，帮我生成一个 UserCard 组件， 
2.功能是显示用户头像、名字和邮箱， 
3.点击卡片时 emit 一个 'select' 事件"  

它会按你的规范生成，不用每次重复说"用 defineProps"...

实用 Skill 案例2：代码审查助手

适用场景：提交 PR 前，让 Claude Code 帮你做一遍代码审查。

Skill 内容（保存在 ~/.claude/skills/code-review.md）：

1. ---
2. name: code-review
3. description:代码审查：检查规范、性能、安全隐患
4. ---
6. 你是一个资深前端工程师，负责代码审查。
8. 用户会给你一个文件路径（用@文件路径引用），你要从以下维度审查代码：
10. ## 审查清单
12. ### 1. 代码规范
13. -[]TypeScript类型是否严格（有没有 any）
14. -[]组件命名是否符合规范
15. -[]有没有 console.log（生产代码不应该有）
16. -[]导入顺序是否正确（第三方→内部→样式→类型）
18. ### 2. 性能
19. -[]有没有不必要的重渲染（React：缺少 memo/useMemo/useCallback）
20. -[]有没有大数组/大对象直接写在 render 里（应该提取成常量）
21. -[]图片有没有懒加载
22. -[]有没有使用 index 做 key
24. ### 3. 安全
25. -[]有没有直接把用户输入插到 DOM 里（XSS 风险）
26. -[]有没有把敏感信息（token、密钥）写在前端代码里
27. -[] API 请求有没有做参数校验
29. ### 4. 边界情况
30. -[]空数据有没有处理（列表为空、接口返回null）
31. -[]加载状态有没有处理（loading、skeleton）
32. -[]错误状态有没有处理（接口失败、超时）
34. ## 输出格式
36. 对于每个问题，按这个格式输出：

问题1：[问题标题]

• 文件：src/components/UserForm.vue
• 行号：第 45-48 行
• 问题：用了 any 类型
• 建议：改成具体类型 UserFormData
• 严重度：🔴 必须改 / 🟡 建议改 / 🟢 可选

1.审查完所有问题后，给一个总结： 
2.-必须改的几条 
3.-建议改的几条 
4.-可选改的几条  

怎么用？

1."用 code-review skill，审查 @src/components/UserForm.vue" 

它会按你的清单，一条条检查，比你人工 review 快很多。

实用 Skill 案例3：Bug 排查助手

适用场景：遇到诡异 Bug，不知道从哪下手。

Skill 内容（保存在 ~/.claude/skills/bug-debug.md）：

1.--- 
2.name: bug-debug 
3.description:系统化排查前端Bug 
4.--- 
5. 
6.你是一个前端调试专家。 
7. 
8.用户会给你一个Bug描述（现象、重现步骤、错误信息），你要按系统化流程帮你排查。 
9. 
10.## 排查流程 
11. 
12.### 第1步：理解 Bug 
13.-让用户确认：现象、期望行为、实际行为 
14.-让用户提供：错误信息、截图、录屏（如果有的话） 
15. 
16.### 第2步：提出假设（按可能性排序） 
17.对每个假设，说明： 
18.-为什么会有这个假设 
19.-怎么验证这个假设 
20.-如果假设成立，怎么修 
21. 
22.假设的例子： 
23..状态更新了，但组件没重新渲染（可能忘了响应式） 
24.接口调了，但数据格式不对（可能后端改了字段名） 
25.事件绑定的函数名写错了（可能拼写错误） 
26. 
27.### 第3步：指导验证 
28.告诉用户具体怎么验证每个假设： 
29.-"在浏览器的 DevTools 里，看 Network 面板，第3个请求的 Response 是什么" 
30.-"在代码里加一行 console.log，看这个值是不是 undefined" 
31.-"用 Vue DevTools 看这个组件的 state 是不是正确的" 
32. 
33.### 第4步：给出修复方案 
34.找到根因后，给出修复代码，并说明： 
35.-为什么这样修 
36.-有没有副作用 
37.-要不要写回归测试 
 
## 注意事项 
40.-不要一上来就让用户"重装 node_modules"（这是偷懒） 
41.-不要一上来就让用户"升级到最新版"（先排查别的原因） 
42.-给出假设时，按"最常见 → 最不常见"排序 

怎么用？

1."用 bug-debug skill，帮我排查这个 Bug： 
2. 
3.现象：用户管理页面，删了用户后列表没刷新 
4.重现步骤： 
5. 打开 /users 
6. 点删除 
7. 确认 
8. 弹窗说'删除成功'，但列表没变" 

它会系统地帮你分析，而不是瞎猜。

怎么创建自己的 Skill

方法1：用 Skill 命令（推荐）

在 Claude Code 里说：

1."帮我创建一个 Skill，名字叫 xxx，功能是 xxx"

它会帮你生成 SKILL.md 文件，并保存到 ~/.claude/skills/。

方法2：手动创建

1. 在 ~/.claude/skills/ 下新建一个 .md 文件
2. 文件开头写 YAML frontmatter（name、description）
3. 后面写 Skill 的具体指令（就是给 Claude Code 的 Prompt）

Skill 写好后怎么用？

在对话里说：

1."用 xxx skill，帮我做 xxx" 

Claude Code 会自动加载这个 Skill 的指令，并按它执行。

写在最后

我用了几个月 Claude Code，最大的感受是：它像个能力很强但没经验的新同事。

你需要：

• 把任务说清楚（它不会读心）
• 定期检查它的工作（它会犯错）
• 给它正确的方向（它会过度发挥）
• 耐心地迭代（完美是改出来的）

但一旦磨合好了，效率提升是很明显的。我现在做一个功能，以前可能要2天，现在大半天就够了——当然，前提是我没在跟它"吵架"。

几个最后的建议

1. 别迷信 AI：它生成的代码要你理解，否则后面改不动
2. 别排斥 AI：它真的很擅长样板代码、测试和重构
3. 写好 CLAUDE.md：这是你跟 AI "签的合同"，写得越清楚，它越听话
4. 多用 Skill：把重复的工作流保存下来，别每次都重新教它
5. 保持学习：AI 是工具，你自己懂底层，才能判断它做得对不对

最后说一句：别指望一篇文档能让你"精通 AI 辅助编程"。我这些经验，是我踩了几百个坑换来的。你也会踩坑，这很正常——踩完了，你就真的会用了。

欢迎交流。如果你有更好的使用方法，或者发现我哪里写错了，告诉我。这篇文档是活着的，我会持续更新。

最后更新：2026-05-09