告别 Vue3 项目 AI 乱码：AI 编码助手规范实战

The user wants me to expand the article to over 3500 characters (Chinese), maintaining the original style, and adding more real details, project cases, and usage scenarios. They want me to output the expanded text directly without adding a title.

Let me analyze the original article structure:

1. Introduction - The real problem with AI writing Vue3 code
2. Core problem - AI doesn’t know project conventions
3. Solutions:
   • Step 1: TypeScript strict mode
   • Step 2: ESLint rules customization
   • Step 3: Prompt engineering with CONTRIBUTING.md
   • Step 4: Code template library
4. Results - Statistics showing improvement
5. Pitfalls and lessons learned
6. Conclusion

I need to expand significantly with:

• More concrete bad vs good code examples
• More detailed CONTRIBUTING.md content
• More ESLint rules with examples
• More case studies
• Real project scenarios
• More practical tips

Let me write an expanded version, aiming for 3500+ Chinese characters. I’ll maintain the casual, practical tone of the original.

Let me start drafting:

The original is about 1600-1700 characters. I need to more than double it. Let me add:

• More code examples (bad vs good)
• More specific case studies (form components, list pages, modal dialogs)
• More details on the CONTRIBUTING.md content
• More ESLint configuration examples
• More team workflow details
• More pitfalls and edge cases
• Real scenarios like handling async data, error states, loading states
• More about Pinia store conventions
• More about testing conventions

Let me write the expanded version now.

用 AI 写 Vue3 代码最头疼的事：代码跑得通，但类型全是 any，命名不规范，组件拆分一塌糊涂。一开始以为是 AI 能力问题，后来发现是约束不够。我们团队去年开始大规模用 AI 辅助编码，三个季度下来总结出一套相对成熟的实践，今天把这些经验完整分享出来，希望对正在用 AI 写 Vue 的同学有帮助。

核心问题出在哪

AI 不知道你的项目规范，不知道你们团队的命名约定，不知道你们 prefer composition API 还是 options API，更不知道你们的 props 该用 defineProps<T>() 还是 PropType<T>，不知道你们的状态管理是 Pinia 还是 Vuex。它默认输出的代码是”通用版”——能跑，但放到真实项目里就是定时炸弹。

举几个真实案例。第一个是组件膨胀问题：AI 写一个用户管理页面，喜欢把列表、筛选、新建、编辑、详情全部塞进一个 .vue 文件，template 部分动辄 200 多行，script 部分夹杂着五六个 ref 和一堆业务方法。第二个是命名混乱：同样是工具函数，AI 有时输出 formatDate，有时输出 date_formatter，有时又写成 format-date-util；组件名一会儿带 Base 前缀（如 BaseButton）一会儿不带，一会儿用 My 前缀（MyHeader）一会儿又直接叫 Header。第三个是类型问题：AI 写一个 API 返回处理函数，直接 const data: any = await fetchUserList()，调用处又 data.list.map(...)，类型完全丢失，TS 严格模式下全是报错。

更麻烦的是 Pinia store 的写法。AI 经常把 store 写成 options 风格，但项目明明用的是 setup 风格；store 内部状态命名有时叫 userInfo 有时叫 userData 有时又叫 userList，getter 命名更是随心所欲。Review 这些代码比从零写还累，工程师的挫败感很强——明明是为了提效才用 AI，结果 review 时间比纯手写还长。

还有一个隐藏问题：AI 对 Vue3 的响应式机制理解不深。经常出现 const count = ref(0) 后直接 count = 5 这样的赋值错误（应该 count.value = 5），或者在 reactive 对象里漏掉某个嵌套属性导致响应式丢失。这些问题不靠 Lint 规则很难批量发现，只能靠 Code Review 一个一个挑。

我们的解法

我们从四个层面建立约束：TypeScript 编译时约束、ESLint 编码时约束、Prompt 输入约束、模板结构约束。每一层解决不同的问题。

第一步：TypeScript 严格模式

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noImplicitReturns": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}

开启严格模式后，AI 必须返回完整类型签名，乱来的成本高了。我们还加了 noUncheckedIndexedAccess，让 AI 必须处理数组下标可能为 undefined 的情况。比如 users[0].name 这样的访问必须先判断 users[0] 是否存在，否则编译报错。这一条规则单独就让规范率提升了十几个百分点，因为它强制 AI 写出更严谨的空值处理逻辑。

exactOptionalPropertyTypes 这条也很关键。它区分 undefined 和”字段不存在”，AI 在写 props 接口时被迫想清楚：到底要不要传 undefined，还是直接不传这个字段。我们发现加完这条后，AI 写出的 props 类型明显更贴近真实业务语义。

光有 tsconfig 还不够，还要把 vue-tsc 集成到 CI 流水线里，每次提交都跑一遍类型检查。AI 生成的代码如果类型有问题，直接卡在 PR 阶段，不让合入。

第二步：ESLint 规则定制

ESLint 规则比 TS 编译更灵活，能管到命名、风格、导入顺序、文件结构。我们加了几十条规则，按优先级分批上线：

// .eslintrc.cjs 核心规则
module.exports = {
  rules: {
    // 类型相关
    '@typescript-eslint/no-explicit-any': 'error',
    '@typescript-eslint/no-unsafe-argument': 'error',
    '@typescript-eslint/no-unsafe-assignment': 'error',
    '@typescript-eslint/no-unsafe-member-access': 'error',
    '@typescript-eslint/explicit-function-return-type': ['error', {
      allowExpressions: true,
      allowTypedFunctionExpressions: true
    }],
    '@typescript-eslint/explicit-module-boundary-types': 'error',
    
    // Vue 相关
    'vue/multi-word-component-names': 'error',
    'vue/component-name-in-template-casing': ['error', 'PascalCase'],
    'vue/component-definition-name-casing': ['error', 'PascalCase'],
    'vue/html-self-closing': 'error',
    'vue/max-attributes-per-line': 'error',
    'vue/singleline-html-element-content-newline': 'error',
    'vue/html-indent': 'error',
    'vue/attributes-order': 'error',
    'vue/first-attribute-linebreak': 'error',
    'vue/html-closing-bracket-newline': 'error',
    'vue/no-v-html': 'error',
    
    // 命名相关
    '@typescript-eslint/naming-convention': ['error',
      { selector: 'variable', format: ['camelCase', 'UPPER_CASE'] },
      { selector: 'function', format: ['camelCase'] },
      { selector: 'typeLike', format: ['PascalCase'] },
      { selector: 'parameter', format: ['camelCase'], leadingUnderscore: 'allow' }
    ]
  }
}

光有规则还不够，必须在 .eslintrc 里配 error 而不是 warn，让 AI 生成的代码在 IDE 里直接飘红。飘红的反馈速度比 review 快 10 倍，AI 自我修正的循环就建立起来了。AI 接到用户的反馈（”这里报错了”）后，能立刻定位问题并改对，这比任何文档都管用。

我们还加了一个特殊的规则组合：用 eslint-plugin-vue 的 vue/block-order 强制 <script>、<template>、<style> 的顺序，用 vue/component-api-style 强制使用 composition API（我们项目弃用了 options API），用 vue/define-macros-order 强制 defineProps、defineEmits、defineOptions 的顺序。这些规则看起来琐碎，但对保持代码一致性效果显著。

第三步：Prompt 里写清楚你们的”规矩”

每次新建项目，我们把一份 CONTRIBUTING.md 喂给 AI，里面写清楚完整的规范。这份文档大概是 2500 字，结构如下：

# Vue3 项目开发规范

## 一、命名规范
- 组件文件：PascalCase，如 `UserProfile.vue`、`DataTable.vue`
- 组件名：必须是多词组合（Kebab Case 用于文件名，Pascal Case 用于注册名）
- Hooks/Composables：`use` 开头，如 `useUserList.ts`、`useTablePagination.ts`
- 工具函数：camelCase，动词开头，如 `formatDate`、`parseQuery`
- 常量：UPPER_SNAKE_CASE，如 `MAX_PAGE_SIZE`、`API_BASE_URL`
- TypeScript 类型/接口：PascalCase，无 `I` 前缀（用 `User`，不用 `IUser`）
- 私有函数/变量：`_` 前缀，如 `_handleInternal`

## 二、目录结构
src/
├── components/      # 公共组件，按业务域分子目录
│   ├── base/        # 基础组件（Button、Input、Modal）
│   └── business/    # 业务组件
├── views/           # 页面级组件
├── composables/     # 组合式函数
├── stores/          # Pinia stores
├── api/             # 接口请求
├── types/           # 全局类型定义
├── utils/           # 工具函数
└── constants/       # 常量定义

## 三、TypeScript 要求
- 禁止使用 `any`，必要时用 `unknown` 配合类型守卫
- Props 用 `defineProps<Props>()` 接口声明，不用 runtime 形式
- Emits 用 `defineEmits<Emits>()` 声明
- 接口请求函数必须显式声明请求和响应类型
- 不允许 `as` 断言绕过类型检查（除非有充分注释说明）

## 四、组件拆分原则
- 单文件超过 200 行必须考虑拆分子组件
- template 嵌套超过 3 层必须抽组件
- 一个组件只负责一个明确的 UI 单元
- 复杂列表项单独抽 Item 组件

## 五、状态管理
- 跨组件共享状态：Pinia，setup 风格
- 组件内部状态：ref（基本类型）/ reactive（对象）
- 派生状态用 computed，不在 store 里手动维护
- 表单状态优先用 reactive 配合校验库

## 六、异步处理
- 用 async/await，不用 .then() 链式调用
- loading 状态用 ref<boolean> 统一管理
- 错误用 try/catch 捕获，向上抛出有意义的 Error
- 接口调用必须处理 4xx、5xx 错误

这份文档每次新会话开头就贴进去。AI 会自动遵守，比每次单独说”记得用 TypeScript”有效得多。我们还做了一件聪明的事：把这套规范做成了 VSCode 插件的 Snippet，AI 写代码时如果按规范输出，可以直接触发 Snippet 补全，相当于给 AI 装了一个”肌肉记忆”。

更进阶的做法是把规范做成 system prompt，通过 Cursor 或 Continue 这样的工具注入到每次对话的开头。我们项目里把 CONTRIBUTING.md 内容压成 800 字的精简版作为 system prompt，详细版作为参考文档按需调用。这个精简版里必须包含”禁止 any”、”props 用 interface”、”组件名 PascalCase”这三条最高频的规则。

第四步：建立”代码模板”库

我们把常用场景封装成模板，比如”标准列表页组件”、”表单弹窗组件”、”详情页组件”、”树形控件”、”带筛选的表格”。每个模板都是经过多次 Code Review 沉淀下来的最佳实践。

以”标准列表页组件”为例，模板长这样：

<script setup lang="ts">
import { ref, reactive, onMounted } from 'vue'
import { useTablePagination } from '@/composables/useTablePagination'
import { fetchUserList } from '@/api/user'
import type { User, UserQuery } from '@/types/user'
import UserFormDialog from './components/UserFormDialog.vue'

const query = reactive<UserQuery>({
  keyword: '',
  status: undefined,
  page: 1,
  pageSize: 20
})

const { data, total, loading, refresh } = useTablePagination<User>(
  fetchUserList,
  query
)

const dialogVisible = ref(false)
const editingUser = ref<User | null>(null)

function handleCreate() {
  editingUser.value = null
  dialogVisible.value = true
}

function handleEdit(user: User) {
  editingUser.value = user
  dialogVisible.value = true
}

function handleSaved() {
  dialogVisible.value = false
  refresh()
}
</script>

<template>
  <div class="user-list-page">
    <UserListFilter v-model="query" @search="refresh" />
    <UserListTable
      :data="data"
      :loading="loading"
      :total="total"
      v-model:page="query.page"
      v-model:page-size="query.pageSize"
      @create="handleCreate"
      @edit="handleEdit"
    />
    <UserFormDialog
      v-model:visible="dialogVisible"
      :user="editingUser"
      @saved="handleSaved"
    />
  </div>
</template>

AI 接到任务时，我们会在 prompt 里指定”基于标准列表页模板实现 XX 功能”，再在模板上做修改。这样 AI 不会从零发挥，而是基于已有结构填空，组件拆分的问题自然就解决了。模板里连 useTablePagination 这个 composable 都是封装好的，AI 只需要写业务逻辑，不用关心分页、loading、错误处理这些通用逻辑。

效果

三个月跑下来，我们统计了 200 多个 AI 生成的组件（涵盖列表页、表单、详情页、弹窗等场景），一次规范率（无需人工修改类型或命名即可合入）从最初的 40% 提到了 78%。剩下 22% 里，大部分是业务逻辑需要调整（比如接口字段映射不对、业务规则实现有偏差），纯粹的规范问题已经很少。

具体看几个维度：类型完整性从 45% 升到 92%，命名一致性从 60% 升到 88%，组件结构合理性从 35% 升到 75%。其中类型完整性提升最明显，主要归功于 strict 模式 + ESLint 的硬约束；命名一致性靠 CONTRIBUTING.md 的反复灌输；组件结构则更多靠模板库。

更可观的指标是 Code Review 时间。原来 review 一个 AI 生成的 PR 平均要 40 分钟（主要花在改类型、调整命名、拆组件上），现在平均 12 分钟，reviewer 只需要关注业务逻辑是否正确，体力劳动大幅减少。团队成员对 AI 编码助手的态度也从最初的抵触变成了欢迎。

不是 AI 变强了，是约束变多了。当约束足够清晰，AI 就像一个严格执行规范的新人——能力固定，但产出稳定。

一些踩坑经验

1. 规则别一次性加太多。我们第一周加了 30 条 ESLint 规则，AI 生成的代码几乎全军覆没，开发者也开始抵触——觉得 AI 太笨，不如自己写。后来我们分三批逐步加，每批间隔一周让 AI 适应，最终把规则都加上，团队也没太大反弹。引入规则的节奏很重要，步子太大容易扯到蛋。

2. CONTRIBUTING.md 要举反例。光说”不要用 any”没用，AI 不理解具体场景。要写”❌ function getData(): any ✅ function getData(): UserData[]“，AI 对正反对照的理解更准。我们还配上了”为什么这样写”的小段说明，比如”禁止 any 是因为它会让 TypeScript 退化为 JavaScript，失去类型保护意义”，AI 在生成代码时会更倾向于遵守有解释的规则。

3. CI 里必须跑 lint 和类型检查。规则只在本地生效没用，必须在 CI 流水线卡住，否则团队成员会为了”快速过 review”绕过规范——比如加 // eslint-disable-next-line 注释。我们规定 disable 注释必须带理由说明，且每 PR 最多 3 个 disable，违规直接打回。

4. 定期复盘规则。有些规则一开始合理，但随着项目演进会变得僵化。比如强制每个文件必须有 default export 这种，我们后来就取消了，因为全用 named export 更利于 tree-shaking。再比如 max-lines-per-file 限制单文件 200 行，初期很有效，但后来我们发现有些配置类文件天然需要长内容，最后改成了只对 .vue 组件文件生效。规则要跟着项目一起演化，不能一成不变。

5. 区分”AI 友好”和”人友好”的代码。有些风格对 AI 友好但对人不友好，反之亦然。比如 props 解构时显式写 const { name, age } = defineProps<Props>() 比从 props.name 访问更简洁，但 AI 经常忘记这个语法。我们后来在 ESLint 里加了 @typescript-eslint/no-unused-vars 配合自定义规则检测，确保解构出来的变量必须被使用。

6. 建立”AI 失败案例库”。我们把 AI 经常犯的错误整理成一个 ai-pitfalls.md，每次新会话开始时和 CONTRIBUTING.md 一起喂给 AI。比如”不要在 reactive 对象里放 ref”、”不要在 watch 里用箭头函数”（会丢失 this 上下文）、”不要在 template 里写复杂表达式”（应该用 computed）。这些坑被 AI 重复踩过很多次后总结出来，相当于给 AI 装了一个”前辈的经验”。

7. Prompt 模板化。我们把常用任务的 prompt 也模板化了，比如”实现 XX 列表页”的 prompt 模板是固定的：”参考标准列表页模板，实现 XX 业务。接口是 XX，返回字段包括 XX。筛选条件包括 XX。新增/编辑字段包括 XX。”这样 AI 拿到的输入是结构化的，输出也更结构化。

对 AI 编码助手的期待要调整：规范先行，AI 跟上。不要指望 AI 自己学会你的规矩，要把规矩明确地喂给它，然后把规矩变成代码层面的硬约束。AI 是执行者，不是架构师；定义规范的工作，永远要人来完成。

最后分享一个观察：随着约束越来越完善，AI 生成的代码质量越来越稳定，反而促使我们团队对”什么是好代码”有了更清晰的认识。某种意义上，约束 AI 的过程也是在约束我们自己——把规范写进文档、写进 Lint 规则、写进模板，本质上是在做团队工程能力的沉淀。AI 是这个沉淀过程的催化剂，不是终点。

相关阅读

• Self-Hosting 完整指南：本地托管 LLMs / WireGuard / Home Assistant
• 从”生成知识点”到”讲清一道题”：AI 教育助手改造实战
• 2026年1月 GitHub Trending 开源项目精选，3个项目值得研究