AI 生成代码最容易被高估的一点，是“跑起来了”就被当成完成。
但在真实项目里，更昂贵的成本往往发生在两周后：
- 变量命名模糊
- 函数做太多事
- 错误处理不一致
- Reviewer 说不清哪里不舒服，却知道这段以后难维护
所以如果你要让 Cursor 真正服务项目，而不是只服务演示，就必须把“可读性”写进提示词。建议配合阅读 Cursor 任务单模板、Cursor 项目级提示词规范、代码质量门禁与 CI 集成 和 Cursor + 单元测试工作流。
先给结论：可读性不是审美，它是长期效率
一段代码是否可读，决定了：
- 下次谁敢改
- 改动会不会引发新错误
- 评审时间会不会持续上升
因此“可读性”不是风格争论，而是维护成本问题。
一、命名：先说清对象和动作，再谈简洁
AI 很容易给出“语法正确但语义模糊”的命名，例如：
dataresulthandleSubmitData
这类名字的问题不是太短或太长，而是读者看不出它到底承载什么角色。
更好的提示词写法应该明确要求：
- 名称反映业务对象
- 动词和名词职责清楚
- 避免无语义泛词
二、函数边界：别让 AI 一次生成“万能函数”
很多 AI 生成代码的问题都不是逻辑错，而是一个函数把校验、转换、请求、错误处理全做了。
这类代码短期能跑，长期很难读。
在提示词里，你可以直接要求：
- 每个函数只负责一个主要动作
- 数据转换和副作用分离
- 错误处理集中在边界层
三、错误处理：可读代码不等于只看 happy path
如果一段代码只写成功路径，失败路径全靠默认异常往外冒，它通常很难读也很难维护。
可读的错误处理至少满足：
- 错误来源清楚
- 错误信息可理解
- 调用方知道如何处理
这也是为什么“让 AI 顺手加 try/catch”并不够，关键是错误语义和边界要清晰。
四、可读性的提示词最好是结构化要求，不是抽象口号
“写得清晰一点”这种要求几乎没有约束力。更有效的写法是：
- 变量命名必须体现业务含义
- 函数不得同时处理校验和请求
- 错误信息要区分用户提示与日志信息
- 优先复用现有工具函数，不新造近似抽象
这种要求更容易转化成可检查产物。
五、把可读性写进验收，而不是只写进愿望
如果你只在提示词里说“请保持代码可读”，但验收里没有任何对应项，最后 review 时很难判断是否达标。
建议在验收里加入：
- 命名是否能自解释
- 函数是否职责单一
- 关键错误路径是否显式处理
- 新增代码是否符合现有项目结构
一个可直接复用的提示词片段
请优先生成可读代码：
- 变量与函数名体现业务语义，避免 data/result/temp 等泛词
- 每个函数只负责一个主要动作
- 数据转换、请求调用、错误处理尽量分层
- 用户可见错误提示与内部日志信息分开
- 若现有项目已有同类工具或模式，优先复用，不新增近似抽象
这类片段和 质量门禁 结合时尤其有效，因为它把“代码好不好读”从主观评价，拉回到可检查条件。
一个失败案例：功能实现了，但 reviewer 还是要求重写
常见原因并不是业务逻辑有 bug，而是：
- 命名全是抽象词
- 一个函数做了太多事
- 错误处理埋在分支里到处都是
- 代码看起来像拼装，不像有边界的实现
这类代码短期也许能 merge，但后续维护一定会把成本补回来。
可读代码提示词检查清单
- 是否要求命名体现业务语义
- 是否要求函数职责单一
- 是否区分用户错误提示与内部日志
- 是否要求复用现有项目模式和抽象
- 是否把可读性写入验收标准
- 是否配合最小测试或质量门禁一起使用
