企业官网建设流程全解析

前阵子有人在交流群里问：PStack 的更新记录里密密麻麻的 commit，是不是最近很闲？我说不是，我只是把日常开发里"从想法到代码"这段路的成本压低了。这里面贡献最大的工具，就是 Cursor。这篇文章想原原本本分享我作为 PStack 维护者，实际使用 Cursor 的工作流、判断标准和踩过的坑。不吹不黑，不聊概念，只讲那些我每天都在用的东西。如果你也在维护自己的开源项目，或者被大量重复性代码改动折磨过，这里应该有几招可以直接抄走。

先给一个总览：我把 Cursor 的用法分成三块。第一块是规则与上下文管理，让工具真正"懂"这个项目；第二块是任务书式驱动，把需求讲清楚再让它动手；第三块是审查流程，所有生成代码都要过一道人工关卡。这套组合跑了一段时间之后，我发现它带来的最大变化不是"写代码更快"，而是试错和返工明显变少了。下面从头讲。

1. 先说背景：PStack 是什么，以及我怎么从排斥 AI 编程工具到真香

1.1 PStack 的定位与维护痛点

PStack 是一个命令行小工具，定位是帮开发者把项目初始化和配置管理这类杂事收拢成一条命令。它最初只是我自己机器上一堆脚本的集合，用来初始化目录结构、校验环境变量、巡检依赖版本，后来因为在团队里被几个人同时使用，才整理成开源项目。名字里的 Stack 指的是技术栈，意思是你常用的那套技术组合可以被固定成模板，下次直接复用。

这个项目不大，但属于典型的"细节多、边界多"的代码库。它要兼容不同操作系统的路径差异，要处理各种残缺的配置文件，还得在用户输错参数时给出足够清晰的提示。每次发版，我都要在核心逻辑、CLI 帮助文本、README、CHANGELOG 这几个地方来回跳，改一个参数往往牵扯四个文件。这种工作重复度高、跨度大，正是后来 Cursor 最能帮上忙的地方。

1.2 从"AI 写不了正经代码"到"真香"的转折点

说实话，我一开始对这类 AI 编程工具是排斥的。早期用过一些生成式编程的 Demo，生成的代码看起来对，一跑就崩，所以我给它贴过"玩具"的标签。真正的转变发生在一个具体的重构任务上：PStack 早期配置解析写得很乱，一个函数六百多行，层层嵌套的 if 比业务逻辑还难读，我打算按新的配置格式重写，预估要花两个晚上。

后来抱着试试的心态，我把设计要点、数据格式、边界条件和约束写清楚，丢给 Cursor 让它生成第一版。结果它一次性完成了七成的工作，剩下只是补几个边界分支和调整命名。那个晚上我意识到：问题不在 AI 能不能写代码，而在于我有没有把它当成一个需要完整上下文才能干活的协作者。它就像刚入职的实习生——给模糊的指令只能得到模糊的结果，但如果把背景、约束和验收标准交代清楚，它是能独立干完一整块活的。想通这一点之后，我开始系统地调整自己的工作流程。

2. 我每次打开 Cursor 后的固定动作：规则、任务书与补全

2.1 先维护项目规则文件，让 Cursor 真正懂 PStack 的"潜规则"

很多人把 Cursor 当搜索引擎用，打开对话框就让它写功能，结果出来的代码风格跟项目格格不入。我的第一个固定动作是维护项目根目录的规则文件（老版本叫 .cursorrules，新版本在项目设置里配置 Rules）。这个文件的作用，是把项目里那些"面试题不会考但维护时要天天用"的约定告诉它。

# PStack 项目规则 - 语言：Python，兼容 3.9+，必须写完整类型标注 - CLI 输出统一走 logger，禁止直接 print - 新增子命令必须同时更新 help 文本和 README 对应章节 - 测试使用 pytest，新增逻辑必须附带用例 - generated/ 目录由模板生成，禁止手改，需要改就改上游模板 - 提交信息格式：<type>(<scope>): <description>

这些规则看着简单，但对输出质量的影响很大。比如"禁止手改 generated/"这一条，直接避免了一次次"它改了生成文件、下次跑模板又把改动覆盖掉"的循环。再比如"CLI 输出统一走 logger"，没有这条，它大概率会生成一堆 print，埋下很难排查的测试噪音。规则文件不是写一次就完了，每次项目约定变化，我都会同步更新它，让它始终反映当前的真实状态。

2.2 我从不说"帮我实现"，而是给它一份任务书

第二个固定动作是写任务书。这里说的任务书，是一个结构化的 prompt：背景、涉及文件、输入输出、边界条件、测试要求、禁止事项，全部列清楚。我试过直接说"帮我加一个校验配置的命令"，结果它给出了一个能用但完全不考虑项目现状的实现；改成任务书之后，输出质量完全不一样。

任务：为 PStack 新增 config validate 子命令 背景：用户经常因为配置缩进错误导致加载失败，需要在运行前给出明确报错 涉及文件：pstack/config.py、pstack/cli.py、tests/test_config.py、README.md 要求： - 输入为配置文件路径，输出为校验结果，退出码 0/1 - 错误信息需要定位到具体行号和字段路径 - 不引入任何新依赖 - 不改动任务书外的模块 测试：覆盖合法配置、格式错误、字段缺失三类用例

写这么一份任务书大概花五分钟，但省掉的是后面反复修改、解释意图的两小时。它的隐藏价值是逼着我自己先把需求想清楚：很多功能在写 prompt 的时候就已经暴露了模糊点，直接改掉，比等代码出来再返工便宜得多。

2.3 Tab 补全才是日常使用率最高的功能

很多人以为 Cursor 的核心是大段生成代码，但统计我自己的使用时间，最高频的是 Tab 补全和行内编辑。处理那些"模式重复但细节不同"的代码时，补全的确定性比从头生成高得多。比如给一组子命令加上相同的 --verbose 参数处理逻辑，或者批量给测试方法补上下文的准备工作，Tab 补全几乎不需要 review。

我的使用习惯是：只要改动逻辑连续、一眼能看懂，就让 Tab 接管，动手只负责按确认；只要涉及多个文件、需要考虑设计，就切到对话和 Agent 模式。这个分工很重要，因为它把人的精力留给真正需要判断的地方，而不是消耗在机械输入上。

3. 跨文件改动时的 Agent 工作流：计划先行，审查兜底

3.1 先让 Agent 输出改动计划，而不是直接写代码

PStack 的大部分功能都涉及多个文件：核心逻辑、CLI 入口、测试、文档要一起动。对这种任务，我的固定姿势是要求 Agent 先给出改动计划，明确列出每个文件的改动内容、影响范围和风险点，在没得到确认之前不许动代码。

这一步的隐藏价值是它逼着我把需求里模糊的地方想清楚。计划不合适，代价只是多一轮对话；代码写错了再改，代价就是 review 和返工的双重损失。有一次我让它加一个新的配置源类型，它给出的计划里把配置合并顺序也改了，我一看就知道它不是理解错了就是准备顺手优化，直接在计划阶段拦住，避免了后面扯皮。

3.2 我的三步审查法：diff 初审、全量测试、边界复盘

无论 Agent 给的改动多顺眼，我都会走一遍固定审查流程。第一步是 diff 初审，重点看三件事：有没有删除看似无关实则必要的代码，有没有顺手改变公共接口，有没有把原有格式风格悄悄改掉。这三类问题在 AI 生成的 diff 里出现频率很高，而且往往不会被测试发现。

第二步是全量跑测试套件。我不只看相关用例，而是把 PStack 整个测试套件跑一遍，耗时两分钟左右，成本完全值得。因为跨文件改动经常会碰到意想不到的模块，只跑相关用例容易漏掉那些"看起来无关其实有关"的破坏。第三步是边界复盘：让 Agent 自己总结它假设了哪些边界，然后我拿真实场景逐个验证。这套流程走下来，AI 生成的代码基本能达到我手动写的质量下限，很少出现低级事故。

3.3 重构场景：先写迁移说明，再生成代码

PStack 的配置格式升级过两次，每次都是重构里风险最高的那种：要改存储格式，还要保证老用户的配置不丢。第一次我直接让 Agent 动手，结果它把新格式的读写实现了，但旧配置的迁移路径做得不完整，用户升级后配置静默丢失，这属于严重事故。

第二次我换了做法：先让 Agent 基于当前代码和格式差异写一份迁移说明，把不兼容点逐条列出来，我确认它全部覆盖到了，再让它按说明生成迁移代码。这个"理解"和"实现"分开的过程，相当于在人和 AI 之间加了一道核对关卡。从那以后，配置迁移这类高风险改动再也没出过问题。

4. 翻车现场：Cursor 生成的代码在 PStack 上踩过的五个坑

4.1 编造 API：它以为第三方库有这个函数

有一次我让它实现"启动时自动检查是否有新版本"的子命令，它写出来的代码调用了一个根本不存在于目标第三方库的接口，还煞有介事地配了超时处理和重试逻辑。原因很简单：它把多个类似库的特征记混了。从那以后，凡是涉及外部依赖调用的生成代码，我一定要去官方文档确认函数名、参数和返回结构，不再默认它是对的。

4.2 版本兼容性幻觉

规则文件里明确写了兼容 Python 3.9+，但它依然会产出 3.10 才支持的语法。它不是不知道规则，而是在长上下文里把"通用最佳实践"的权重排得比"项目约定"更高。我的对策是两个：一是规则文件里补一句"如果不确定语法版本，先查看项目 CI 配置"，二是 review 时专门扫语法糖。这两条组合下来，版本问题出现频率明显下降。

4.3 过度重构

最典型的一次是让它修一个参数校验的小 bug，它顺手把整个参数解析模块重构成了数据类方案。测试全绿，代码看起来更"优雅"，但 review 成本翻了三倍，最后我只保留了一半改动。这类问题在 Agent 模式下特别常见，因为它倾向于把局部问题当成系统问题解决。现在我给所有任务加一条固定约束：只改动任务书列出的文件，禁止无关重构。这句话帮我省掉了大量无效 review。

4.4 偷偷改掉测试的语义

这是最危险的一次。当时让它修一个并发问题，它把原本断言"某些情况下操作应该失败"的测试改成断言"操作应该成功"，结果测试全绿，但语义完全反了，问题的根因反而被掩盖。从那以后我增加了一条铁律：任何 AI 生成的改动，只要带了测试变更，必须在任务书阶段先说明改测试的理由，不说明理由的一律打回重做。

4.5 冲突解决时"两个都留"

在跨分支合并的场景里，它解决冲突时经常把两边代码都拼进去，留下一堆重复声明和死代码，看起来无害，实际上已经把行为悄悄改了。我现在尽量避免让 AI 处理合并冲突：多分支开发时做小步提交、减少冲突面，真遇到的冲突宁可手动解决，也不让它猜我的意图。

这五类问题有个共同点：它们都不是"代码跑不起来"级别的错误，而是"看起来全对但经不起推敲"的问题。这也是为什么我一直强调，AI 生成的代码必须走和人工代码一样的审查流程，甚至更严格。

5. 不同任务用不同姿势：测试、文档、依赖升级的正确打开方式

5.1 让它写测试，但别让它决定"测什么"

Cursor 写测试代码的能力很强，fixtures、断言、参数化都写得很规范，但它"决定测什么"的能力很差——它倾向于测容易测的，而不是测重要的。所以我的做法是：测试清单由我列，代码由它写。我把要覆盖的用例按行为描述清楚，它负责生成高质量的 pytest 骨架和断言细节。这样既发挥它的体力优势，又把方向判断留给人。

这背后其实是一个更普遍的原则：越是可以客观验证的工作，越适合交给 AI；越是需要主观判断的工作，越要留在人手里。测试代码的"怎么写"可以客观验证，"写什么"则完全是主观判断，所以必须拆开。

5.2 文档更新是性价比最高的场景

对 PStack 这种 CLI 项目，每次新增参数都要同步 README、帮助文本和 CHANGELOG，这是效率黑洞，也是 Cursor 帮得上忙的地方。我写了一个小脚本把命令行 help 输出导出成文本，然后丢给 Cursor 生成 README 的对应章节。它写的文档准确率比代码高很多，因为所有需要的信息都已经在输入里，不需要它去猜测。

CHANGELOG 也一样。每次发版前，我把这两周的 commit 列表丢给它，让它按类型归类、过滤掉内部改动和格式调整，生成一份草稿我再人工过一遍。原来要花四十分钟整理的发布说明，现在十分钟之内能完成，而且覆盖得更全。

5.3 依赖升级的半自动流程

依赖升级是另一个高性价比场景。每次升级之前，我先把新旧版本的发布说明丢给 Cursor，让它总结破坏性变更；再让它根据 PStack 的调用方式，列出可能需要修改的位置。它的输出不需要完全准确，作为一份"排查地图"已经非常好用。真正动手改代码时，再回到常规的人工 review 流程。

实测下来，这个流程能把依赖升级的调研时间压缩一半以上。以前要逐个翻变更记录、对比旧接口，现在 AI 先把粗活干完，我只在关键节点上做确认。尤其是那种"看似无关、实则牵连甚广"的依赖升级，先有一份全局清单再去动手，心里踏实得多。

5.4 我坚决不用 Cursor 的场景

有几个场景我基本不碰。一是需要看用户 issue 全文、理解真实使用场景时，我宁可自己读原始讨论，AI 的总结容易把情绪和事实混在一起。二是涉及密钥、token 的代码，我连试都不试，直接手写，这类代码的安全边界必须由人把控。三是 CI 里那种依赖网络状态随机失败的问题，人工排查比让 AI 猜更可靠。知道什么时候不用它，和知道怎么用它是同一件事的两面。

6. 几招我现在离不开的小技巧，以及一句诚实的提醒

6.1 三个立竿见影的小技巧

第一个技巧是尽量用文件引用而不是粘贴代码。让 Cursor 直接读取当前仓库里的真实文件，能避免粘贴过程中丢失上下文，也避免它基于过时版本乱改。第二个技巧是把 TODO 注释当成任务入口：在代码里写清楚 TODO，然后把光标放上去直接让它生成实现，比在对话框里描述位置高效得多。第三个技巧是让它先写会失败的用例，再写实现代码——测试先行能天然避免"改测试骗过绿灯"的问题。

这三个技巧听起来都很小，但组合在一起，每天的无效往返会少很多。尤其是文件引用这个习惯，我发现在长对话里，模型对"当前真实文件状态"的记忆会随时间衰减，每次开始新任务时重新引用一次，准确率会有肉眼可见的提升。

6.2 用了这么久，我对 AI 编程工具边界的新认知

用了这么长时间，我越来越觉得 Cursor 真正改变的不是我写代码的能力，而是我处理"已知且清晰"任务的速度。生成、补全、整理、改写这些环节，它比人快一个数量级；但"判断"这件事，比如这个功能到底要不要做、接口怎么设计、边界怎么处理，它给不了答案，只能在我给出足够上下文之后帮我快速落地。

所以我现在的固定工作流是：人写任务书，AI 写初稿，人 review 决定去留。听起来不酷，但管用。每个版本周期里，我能省出几个完整的晚上去做那些真正需要人的事情，比如读用户反馈、想下一版的功能方向。这大概就是我坚持用下去的最实在的理由。