团队里最常见的 Cursor 失控，不是模型不行，而是输入像聊天、不是规格。
如果你给 AI 的只是“帮我改一下这个页面”，结果通常会是：
- 改动范围失控
- 改对了 A，却破坏 B
- 很难 review，更难回滚
这篇文章给你一套项目级 Prompt Spec，让 AI 输出进入可审计工程流程。
如果你属于下面三类人，这篇会特别有用：
- 带 2~10 人研发小团队的负责人
- 正在把 AI 编程接入日常开发流程的前端/全栈
- 经常遇到“AI 改得挺快，但 review 很痛苦”的项目协作者
结论先说：Prompt Spec 至少包含 6 个硬字段
| 字段 | 作用 | 缺失风险 |
|---|---|---|
| Scope（范围） | 限定允许改动的目录/文件 | AI 误改无关模块 |
| Non-goals（非目标） | 防止“顺手优化” | 需求膨胀、交付延期 |
| Constraints（约束） | 技术栈/代码规范/禁改项 | 风格漂移、破坏约定 |
| Acceptance（验收） | 明确“完成”的定义 | 无法判定是否交付 |
| Risk Control（风控） | 分步提交/先读后改 | 一次大改不可回滚 |
| Rollback（回滚） | 失败时恢复路径 | 故障处理时间过长 |
为什么项目里“会提问”仍然不够
在个人场景，Prompt 可以松；在团队场景，Prompt 必须是“合同”。
项目级约束的本质是把自然语言变成可执行协议：
$$ 需求文本 \rightarrow 结构化约束 \rightarrow 可验证输出 $$
没有结构化约束，AI 会默认做“最可能的合理动作”，而不是“你团队的正确动作”。
可复制模板：Cursor Project Prompt Spec（MVP）
# Task Spec
## Goal
实现 xxx 功能，解决 yyy 问题。
## Scope (Allowed)
- 仅可修改：
- app/pages/tools/**
- app/components/tools/**
## Non-goals (Forbidden)
- 不改 package.json
- 不改 nuxt.config.ts
- 不新增第三方依赖
## Constraints
- 使用 TypeScript
- 保持现有命名风格与目录结构
- 新增逻辑优先复用现有 composables
## Acceptance
- 功能路径 A/B 手测通过
- 无 console error
- 关键交互响应时间 < 300ms
## Risk Control
- 先输出改动计划（文件级）
- 每次只改 1~2 个文件
- 每次改动后说明影响面
## Rollback
- 如出现回归，按文件粒度回退新增代码块
实战流程：把“要改啥”变成“能交付”
- 先写 Scope：不先写范围，不要开始改代码。
- 补 Non-goals：把“这次不做”的内容写死。
- 定义验收：至少有功能、质量、性能三个维度。
- 要求分步提交：先计划，再实现，再自检。
- 最后做回滚预案：确认最小回退颗粒度（函数/文件）。
可量化评审：给 Prompt Spec 打分（100 分制）
很多团队写了 Spec，但评审时仍然靠感觉。建议用统一评分表，避免“写了等于没写”。
| 维度 | 分值 | 判定标准 |
|---|---|---|
| 范围清晰度 | 20 | 是否明确到目录/文件级 |
| 非目标约束 | 15 | 是否写清楚禁改项与禁止动作 |
| 验收可测性 | 25 | 是否能被手测/自动化验证 |
| 风险控制 | 20 | 是否有分步执行与影响面说明 |
| 回滚可行性 | 20 | 是否能在 5~10 分钟内回退 |
建议上线门槛：
- 内部协作任务：$\ge 80$ 分
- 生产核心链路任务：$\ge 90$ 分
两类任务的 Spec 写法差异
小改动（1~2 文件）
- Scope 可以精确到文件
- Acceptance 强调“功能正确 + 无副作用”
- Risk Control 可简化为“先读后改 + 单次提交”
中改动（3~10 文件）
- Scope 需要分“允许改动区”与“只读参考区”
- Acceptance 必须包含功能、性能、兼容 3 维
- Rollback 要给出“按文件分组回退”顺序
可直接复用的 Review 话术模板
## Reviewer Notes
- Scope 是否越界：是 / 否（若是，列出文件）
- Non-goals 是否被违反：是 / 否
- Acceptance 是否可复现：是 / 否（附步骤）
- 风险说明是否充分：高 / 中 / 低
- 是否允许合并：通过 / 需修改 / 拒绝
这段模板能把“主观评价”转成“结构化结论”，特别适合多人协作和异步评审。
常见烂 Prompt，对照改写示例
模糊写法
帮我优化一下这个页面，顺便整理代码。
问题：
- 范围不清
- 没有非目标
- 无法判断“整理到什么程度”
可执行写法
仅修改首页 Hero 与 FAQ 区块；不改路由、不改依赖；目标是降低首屏冗余文案并保留现有埋点；验收为移动端首屏不超过两屏、无新增 console error。
这类改写的核心不是“写更长”，而是把风险边界写实。
Spec 最好放在哪
团队里常见的三种放法：
- 直接写在任务单里：适合小改动
- 写在 PR 描述顶部：适合需要 review 对照的任务
- 单独沉淀成模板文档：适合团队长期复用
如果刚开始落地，建议先从“任务单 + PR 描述同步”开始，成本最低。
失败案例：只写目标，没写非目标
原始指令： “优化页面加载速度，并整理一下代码结构。”
结果：
- AI 同时改了路由、状态和样式结构
- 性能有提升，但线上出现样式错位
- 无法快速定位哪一步引入问题
根因： 没有 Non-goals + 没有分步风险闸门。
修复：
- 限定仅改
image加载策略和资源压缩 - 禁止结构性重构
- 先输出改动计划，按文件分批执行
再具体一点，合格的改写应该像这样：
目标：优化首页图片加载，降低 LCP
允许改动：components/Hero.tsx、utils/image.ts
禁止改动：路由、埋点、全局样式、依赖
验收：LCP 下降；页面视觉不变；无新增 console error
读者真正需要的不是“Prompt 要写清楚”，而是“清楚到什么程度才算够”。
Checklist（发布前）
- Prompt 含 Scope/Non-goals/Acceptance
- 禁改项明确（配置/依赖/核心目录）
- 改动按小步提交并可单独回退
- 每步有自检说明（功能/性能/兼容性）
- 最终验收有客观指标
FAQ
Q1：Prompt 写很长会不会降低效率？
不会。项目场景里，清晰约束比重试 3 次更快。
Q2：所有任务都要完整 Spec 吗？
小修不用全量模板，但至少写 Scope + 验收。
Q3：能让 AI 自己补全约束吗？
可以，但要先让它“提问补约束”，你确认后再执行。
Q4：Spec 和 PR 描述会重复吗？
不会。Spec 负责“改之前的边界”，PR 描述负责“改之后的事实”，两者互补。
Q5：Spec 要不要规定“先读文件再改”？
建议要。尤其是中改动任务，这能明显降低 AI 一上来就越界修改的概率。
先做这 3 件事（读完可直接执行）
- 从你最近一次 AI 改动任务里，补写
Scope和Non-goals - 给团队统一一个最小 Spec 模板，不再每次自由发挥
- 在 review 里增加“是否越界”这一项，先把风险拦住
