拒绝“抽卡式”编程：如何写出让AI秒懂的高质量技术Spec实战指南

• 痛点+解决方案： “抽卡式编程”精准击中开发者面对AI生成代码随机性的痛点。

• 方法/指南： 明确这是一份“实战指南”，承诺提供可落地的操作方法。

✍️ 引言 (Hook)

🎯 核心要点

• 重新定义 Spec： Spec 不是给老板看的文档，而是给 AI 看的“伪代码级”指令。

• C.C.A. 模型： 掌握 Context（上下文）、Constraints（约束）、Acceptance Criteria（验收标准）三大要素。

• Markdown 驱动： 将 Spec 文件化，作为 AI 理解项目的“唯一真理源”。

• 实战模板： 提供一份直接可用的 .md 提示词模板。

📖 文章正文

一、 为什么 Prompt 总是失败？（模糊性 vs 精确性）

• 是别墅还是茅草屋？

• 用木头还是砖块？

• 有几个窗户？

二、 高质量 Spec 的解剖学：C.C.A. 模型

1. Context (上下文)：你在哪，你要去哪

• 当前架构： "我们使用的是 React + Next.js 14 (App Router) + Tailwind CSS。"

• 业务目标： "我们要实现一个用户登录功能，但必须兼容现有的 OAuth 2.0 服务。"

• 角色设定： "你是一位资深的前端架构师，注重无障碍访问 (a11y) 和性能优化。"

2. Constraints (约束)：边界在哪里

• 技术栈约束： "禁止使用 useEffect 处理数据获取，必须使用 React Query。"

• 风格约束： "所有组件必须是函数式组件，使用 TypeScript 强类型，禁止使用 any。"

• 库的限制： "使用 shadcn/ui 组件库，不要引入额外的 CSS 文件。"

3. Acceptance Criteria (验收标准)：做成什么样算完工

• "输入错误的密码时，必须显示红色的 Toast 错误提示。"

• "登录成功后，必须重定向到 /dashboard 页面。"

• "代码必须通过现有的 ESLint 规则。"

三、 实战：从“烂 Prompt”到“神 Spec”

"帮我写一个 Python 脚本，扫描目录下的文件，把图片都压缩一下。"

四、 迭代流程：Spec-First Workflow

1. Draft (草拟)：用自然语言写出粗糙的想法。

2. Refine with AI (AI 辅助完善)：把草稿发给 AI，问它：“为了实现这个功能，你还需要我补充哪些细节？有没有我没考虑到的边缘情况？”
• 这一步至关重要！利用 AI 来查漏补缺，完善 Spec。

3. Generate (生成代码)：确认 Spec 无误后，下令生成代码。

4. Review (审查)：对照 Spec 中的“验收标准”检查代码，而不是凭感觉看。

🔗 类比与图解建议 (Analogy & Visualization)

• 类比建议： 使用**“点菜”**的类比。
• 烂 Prompt： 对厨师说“我饿了，随便做点好吃的”。（厨师可能给你做份你不吃的榴莲披萨）
• 好 Spec： 对厨师说“我要一份五分熟的西冷牛排，黑胡椒汁单独放，配菜要烤芦笋，不要放蒜，我有大蒜过敏”。

• 图解建议： 建议绘制一张**“Spec 驱动开发流程图”**。
• User (模糊意图) -> AI (提问/反问) -> User (确认 Spec) -> Spec.md (清晰蓝图) -> AI (生成代码) -> User (基于 Spec 验收)。
• 重点突出中间的“AI 提问/反问”环节，这是消除歧义的关键。

💡 关键洞察

1. 慢即是快： 写 Spec 看起来浪费了 5 分钟，但它节省了你之后 1 小时 debug 和重构的时间。

2. 文档即代码： 在 AI 时代，Markdown 文档实际上就是“高阶代码”。你维护的是 Spec，AI 维护的是 Implementation。

3. 消除歧义是人类的责任： AI 无法替你做决定。如果 Spec 里没写“处理异常”，AI 写的代码崩了，那是你的责任，不是 AI 的责任。

🚀 行动建议

1. 创建模板： 在你的项目根目录创建一个 .cursorrules (如果是 Cursor) 或 prompt_template.md，把本文的 C.C.A. 模型固定下来。

2. 强制反问： 每次发给 AI 任务时，在末尾加上一句：“在开始写代码之前，请先总结你对任务的理解，并列出你需要澄清的问题。”

3. 从重构开始： 找一个你现在的“烂代码”文件，尝试不直接改代码，而是写一份 Spec 让 AI 重构它。