企业官网建设流程全解析

先聊一件让我挺有感触的事。以前我用 Cursor 写代码，最怕的不是 AI 写出多离谱的代码，而是它每次写出来的风格都像开盲盒。有时候给出的方案很惊艳，有时候又犯低级错误，变量命名天马行空，异常处理直接忽略，甚至把团队内部约定的 API 封装都绕过去了。代码评审一次能打回三四轮，AI 越改越乱，我越看越气。后来我把问题想明白了：不是 AI 不行，是我压根没告诉它“在我们项目里，好代码到底长什么样”。于是我花了一个晚上写了一份 40 行左右的.cursorrules，把项目约束、代码风格、输出格式全部塞进去。实测之后，AI 生成代码的“首版通过率”从之前纯靠运气的状态，直接稳定到了 80%。这篇文章我就把这份规则文件的完整内容、设计思路、踩过的坑和量化方法都讲一遍，希望能给同样在跟 AI 协作写代码的朋友一些参考。

1. 先搞清楚一件事：AI 写的代码为什么总得返工

很多人的第一反应是“AI 能力不行”，但我测过 GPT、Claude 还有 Cursor 内置的不同模型，发现问题的核心根本不是模型智力，而是上下文里缺乏项目级约束。你给 AI 一个 Task，它就只盯着这个 Task 的局部上下文，自动补全缩进、命名、边界情况全靠猜。猜对了皆大欢喜，猜错了就是一次次返工。

1.1 首版通过率低，根子在于上下文缺失

我复盘了两次典型的返工现场。第一次是让 AI 写一个用户列表的分页接口。任务描述写得很清楚：分页参数、返回结构、异常处理。结果 AI 交出来的代码里直接return users.slice(0, 10)，把分页参数写死了，排序逻辑也默认按创建时间降序，完全没看我们项目里通用的查询封装。第二次是让 AI 给一个 React 组件加搜索功能，它转头就引入了一个新的 URL 参数管理库，我们的项目里明明一直用的是react-router-dom原生 searchParams。

这两次返工浪费了大概四十分钟。后来我意识到一个残酷的事实：AI 理解“任务”，但不理解“场景”。如果你不把项目的技术栈选型、目录习惯、命名规范、错误处理策略、禁止事项全部暴露给它，它只能按照训练数据里的“最大公约数”来写代码。那个“最大公约数”往往是最通用、最教材化、最不符合真实工程需求的写法。

1.2 为什么同一位 AI，不同人用效果差这么多

同一个模型、同一个项目，有人用着像资深工程师，有人用着像刚毕业的实习生。差距就在你有没有给它建立一套“项目共识”。我见过很多人直接在新对话里粘贴一段需求就开始写，AI 连续问三个问题，他嫌烦，直接说“你先写，后面我再改”。结果自然就是首版通过率惨不忍睹。

.cursorrules本质上就是把“项目共识”提前注入到每一次 AI 请求里。它不是一个魔法开关，更像是一个上岗培训手册。你把它放在项目根目录，Cursor 在每次对话时会自动读取并作为系统级上下文的一部分参与生成。你不需要每次重复强调技术栈和代码规范，AI 自动就能看到。这样一来，首版代码和团队预期的差距会被大幅压缩。

2. .cursorrules 到底是什么，以及它凭什么能起作用

简单说，.cursorrules是放在项目根目录下的一个纯文本文件（建议用 Markdown 格式写），Cursor 编辑器会在你发起对话、生成代码、做内联编辑时，自动把它作为系统提示词的一部分发给模型。它跟你手动在对话框里打的提示词相比，优势在于持久化、无感、项目级共享。

2.1 一句话理解 .cursorrules 的原理

你每次跟 AI 对话，本质上就是在给模型“补上下文”。但对话框里的上下文是一次性的，换一个新对话就没了。团队成员各自开新对话，AI 就各自失忆。.cursorrules把项目规则“焊死”在项目目录里，不管是谁、什么时候、在哪台机器上打开这个项目，AI 的行为基线都是一样的。

我把它理解为“给 AI 立规矩”。规矩不用多，但不能没有。这跟带新人是一个道理：如果团队没有编码规范文档，新人就只能靠猜，或者照着老代码的风格复制。如果有一份靠谱的规范，新人上手速度快，产出也稳定。AI 比新人更需要这份规范，因为它连“问”都不会主动问，你不说，它就自由发挥。

2.2 文件该放在哪、怎么生效、优先级是怎么排的

.cursorrules的位置很讲究。放在项目根目录，Cursor 会在你打开该项目下的任何文件时自动加载它。如果你在子目录里也放一个.cursorrules，子目录的规则会合并进来，但项目根目录的规则优先级更高。如果你在~/.cursorrules放了一份全局规则，那么它会被任何项目的局部规则覆盖。简单记就是：越贴近当前工作区的规则，优先级越高。

我建议团队直接把这个文件提交到 Git 仓库里，跟代码一起管理。新的同事 clone 项目下来，Cursor 就会自动读到这份规则，不需要额外配置。文件命名就是.cursorrules，不需要扩展名，Cursor 原生支持。如果用的是 VS Code 加 Cline、Continue 之类的插件，也有对应的方式引入类似规则，这个后面可以单独聊。

3. 我那份 40 行 .cursorrules 的完整结构与逐段解读

先说明一下，我这份规则是围绕一个 TypeScript 全栈项目写的，技术栈是 React + Node.js + Prisma + PostgreSQL，团队对代码质量要求比较严。你如果不是这个技术栈，把对应部分换成自己的就行，核心骨架和思路是通用的。

3.1 全文展示

我把它压在了 40 行左右，不是越短越好，而是每一条都经过筛选，确保不会因为太长而导致模型忽略关键信息。下面是去掉了敏感信息后的完整版：

# Project Context - 语言: TypeScript - 前端: React 18 + Vite - 后端: Node.js + Express - 数据库: PostgreSQL + Prisma ORM - 包管理: pnpm # Code Style - 使用函数组件和 hooks，禁止 class 组件 - 所有变量、函数使用 camelCase，组件文件使用 PascalCase - 类型定义统一放在 types/ 目录，禁止在组件文件内定义共享类型 - 优先使用 type 而不是 interface，除非是描述对象形状且需要合并 - 禁止 any，未知类型用 unknown，再通过类型守卫收窄 - 使用绝对路径导入，别名 @/ 指向 src/ 根目录 # Engineering Practices - 所有新增业务逻辑必须附带单元测试，测试文件放在 __tests__ 目录 - 错误处理优先使用 try/catch，不要吞异常，必须记录日志 - 禁止编写超过 80 行的函数，拆分为小函数 - API 请求统一走 src/lib/apiClient.ts 封装，禁止直接使用 fetch 散落各处 - 环境变量通过 src/config.ts 统一读取，禁止在业务代码中直接 process.env - 数据库查询必须经过 Prisma Client，禁止写裸 SQL - 组件内禁止直接修改 props 和 state，使用不可变更新 # Output Format - 生成新文件之前，先给出文件路径和职责说明 - 修改现有文件时，只展示 diff 块，并说明修改原因 - 代码必须通过 TypeScript 严格模式检查 - 每次输出末尾附上“自测清单”，列出你如何验证这段代码正确 - 如果不确定项目里的既有约定，先搜索相关代码再实现

这看起来很简单，但每条背后都有故事。

3.2 逐块拆解：技术栈锁定、代码风格、工程约束、输出格式

“Project Context”这一块我称之为“防串味”。AI 在训练数据里见过太多技术栈，你不锁定，它可能给你写一个 Vue 组件混进 React 项目里，或者用 axios 而不是项目统一的 apiClient。锁定技术栈的意义不是限制发挥，而是把 AI 从“通用程序员”变成“你团队里的程序员”。

“Code Style”这一块解决的是“代码像不像人写的”问题。我见过 AI 生成的代码里冒出一个any，在严格模式检查下直接编译失败。也见过它在组件文件里定义了一堆只在别的文件里用到的类型，导致循环依赖。把命名规范、类型策略、导入方式写清楚以后，这类低级问题基本不会出现了。这里要特别说明一下“优先使用 type 而不是 interface”，这是我们团队内部的一个选择，不是为了迎合谁，而是为了避免 interface 的属性合并带来的隐性类型污染。你的团队如果习惯用 interface，改成 interface 也行，重点是“统一”。

“Engineering Practices”这块是首版通过率的灵魂。没有这些约束，AI 生成的代码能跑，但经不起 Code Review。比如说“禁止编写超过 80 行的函数”，AI 看到这条之后，在生成复杂逻辑时会主动拆函数，虽然偶尔拆得不够优雅，但比一大坨几百行的流程代码好改多了。再比如“API 请求统一走 apiClient 封装”，这个约束直接让 AI 放弃了自己造一个 fetch 函数的想法，转而去找项目里已有的封装。我甚至发现，当这条规则存在时，AI 会主动先搜索apiClient的用法，再开始写请求代码，这正是我想要的行为。

“Output Format”这个设计很多人会忽略，但它直接影响你 review 代码的速度。让 AI 先给出文件路径和职责说明，你就能快速判断它的实现思路对不对，而不是先读一堆代码再恍然大悟。让 AI 列出“自测清单”更是神来之笔，它会让模型在生成代码时模拟执行一遍，很多低级的逻辑漏洞在这一步就被模型自己过滤掉了。实测下来，加了这条之后，边界条件漏处理的情况明显减少。

4. 实测记录：从“瞎猜”到 80% 首版通过率的全过程

我不喜欢只讲概念不讲数据。为了验证这份.cursorrules的效果，我专门做了一轮对比测试，也把“首版通过率”这个指标量化了。

4.1 什么叫“首版通过率”以及怎么量化

我定义的首版通过率是：AI 生成的第一版代码，不需要人工修改就能通过以下全部检查的概率：

1. TypeScript 严格模式编译无报错
2. 现有单元测试全部通过（新增代码如果有测试，新测试也能通过）
3. 代码风格符合团队约定（命名、导入路径、目录归属）
4. 无明显的逻辑漏洞（比如漏掉 loading 状态、没有处理错误分支）
5. 没有绕过项目基础设施（比如没用 apiClient、直接操作 DOM、绕过 Prisma）

这五个条件看起来简单，但实际操作中，哪怕 AI 生成的代码能编译，也可能因为没走 apiClient 而被评审打回。所以我的通过标准不是“能跑”，而是“能直接合入”。

测试方法是在同一个项目里抽取 20 个日常开发任务，包括新增接口、修改组件、修复 bug、添加测试等类型。每类任务交替进行，一组使用旧的“无规则自由对话”方式，另一组使用加了.cursorrules的方式。同一个任务不会同时在两组里出现，但任务难度和类型分布保持一致。我记录了每个任务第一版代码的通过情况。因为样本量不算大，这个数字不会特别精确，但趋势很有参考价值。

4.2 基线测试到优化后的真实数据对比

在没有.cursorrules的时候，我随机抽了 10 个任务，结果如下表：

10 个任务里只有 2 个能直接通过，也就是 20%。而且这 20% 还是最简单的任务。换句话说，在复杂一点的业务场景里，几乎全靠人工返工。AI 写的代码看着能用，但离“可合入”差得很远。

加上.cursorrules之后，我对另外 10 个同难度任务重复了上面的测试，通过率是 8 个，也就是 80%。失败的两个任务，一个是因为模型没有处理极端的空数组边界情况，另一个是因为生成的新接口字段和前端组件的类型定义对不上。但这里我要说一句公道话：这两个失败点，放在人类开发者也经常会漏，代码评审时改一下也就几分钟的事。整体节省下来的返工时间非常可观。

4.3 80% 里的水分和口径

为了防止有人抬杠，我得说清楚：这个 80% 不是“AI 写出来的代码完美到一行不用改”，而是“在评审时不需要结构性调整、只做小规模修改即可合入”。我们团队的实际开发流程里，AI 生成代码后我仍然会过一遍 diff，但这个 review 的负担从“逐行检查逻辑”降到了“扫一眼确认没有越界”。这是我感受到的最大变化。

我也测过一份 150 行的.cursorrules，通过率并没有继续提升，反而出现了模型“过度贴合规则”导致输出变啰嗦、忽略任务重点的情况。后来我把规则精简到 40 行，在保持核心约束的前提下，把那些“锦上添花”的建议都删了。结论是：规则文件不是越详细越好，要给模型留出理解任务的空间。40 行对大多数项目来说，是一个甜点区间的下限。当然，如果你的项目里藏着一大堆历史约定，你可以适当增加到 60 到 80 行，但我不建议超过 100 行。

5. 常见问题与排查技巧实录

这份.cursorrules用完以后，我踩过几个很有代表性的坑，也收到过一些朋友的使用反馈。这里整理成问题实录，希望能帮你少走弯路。

5.1 文件没生效？先查这 3 个点

第一个常见问题是“我写了 .cursorrules，但感觉 AI 完全没读”。这种情况先确认文件有没有放在项目根目录，而不是src或者.cursor子目录。Cursor 只会读取当前打开项目的根目录文件。第二个坑是文件编码问题，如果你在 Windows 上用记事本保存的，务必确认编码是 UTF-8，不然中文内容可能变成乱码，导致模型读不懂。第三个坑就是 Cursor 版本和模型选择的问题，有些旧版本对话不会自动加载.cursorrules，需要你在对话里手动 @ 一下这个文件。建议升级到最新版本，并且尽量使用支持超长上下文的模型，比如 Claude 的对应版本或者 GPT-4 以上级别，效果会稳定很多。

在这里给一个自检方法：你在对话框里随便问一句“这个项目的技术栈是什么？请读一下 .cursorrules”，如果 AI 能准确说出 React、TypeScript、Prisma 这些关键词，说明规则已生效。如果答得含糊其辞，那就是没加载上，按上面的顺序排查。

5.2 规则冲突、过宽、过窄的处理方式

规则写多了以后，偶尔会遇到“规则打架”的情况。比如我在 Code Style 里写了“禁止 any”，但在 Engineering Practices 里又写了“处理未知类型时可以用 unknown 再收窄”，这两个本身不冲突，但如果你再写一条“解析接口返回数据时可以使用 any 快速处理”，那模型就懵了。它会纠结到底哪条优先级更高，最后可能输出一个as any再加一行注释，非常难看。所以规则之间一定要保持一致，能用正向描述就尽量不要用否定式加例外条款。

还有一个常见的坑是规则过窄导致 AI 不敢动手。比如“所有函数不得超过 20 行”这种约束，会让模型为了拆函数而拆函数，产生一些毫无意义的中间函数。我实测后把它改成了 80 行，给了模型足够的发挥空间，反而代码质量更高了。规则过宽的后果则是 AI 写出来的代码风格漂移不定，今天用 function 声明，明天用箭头函数，整体观感很差。所以宽严之间要找到平衡点，你需要反复试验并观察 AI 的输出变化。

5.3 后续扩展和小心得

用了一段时间以后，我又在.cursorrules里加了一些针对“新人友好”的内容，比如“新增文件时若引用了不存在的依赖，请在代码注释中标注依赖安装命令”，这能有效减少我在本地装依赖时的猜谜时间。

另外，如果你用的是 Cursor 以外的 AI 编程工具，比如 Continue 插件、Cline、甚至直接通过 API 调用模型做代码生成，这套思路同样适用。你只需要把.cursorrules的内容改造成对应的规则文件格式，或者直接把它作为 System Prompt 的一部分传给模型。核心逻辑是一样的：先给 AI 划定边界，再让它自由发挥。没有边界的 AI 是惊喜和惊吓并存的盲盒，有边界的 AI 才是你团队里那个稳定、高效、知根知底的初级工程师。

最后再分享一个小技巧：如果你改动了.cursorrules，最好新开一个对话再测试，因为旧的对话上下文里可能还残留着旧规则的影响。实际开发中，我每次调整规则后都会用同一个测试任务跑一遍对比，确认改动是正向的再提交到 Git。这样积累下来，你的规则文件就会变成一个数据驱动的团队资产，而不是拍脑袋的产物。