核心摘要

AI 辅助编程时代，决定代码质量的不再是模型能力，而是你的工程规范。如果你不给 AI 戴上“紧箍咒”，它会倾向于生成命名随意、逻辑臃肿、缺乏异常处理的“垃圾代码”。本文将教你如何通过命名契约、职责约束、SDD 方法论以及 IDE 规则固化，让 AI 真正成为输出高质量代码的资深专家。

📋 目录

✨ 核心要点

  • 命名即契约：强制要求 AI 使用业务语义清晰的命名，而非通用的 get/process。
  • 职责单一化：通过提示词限制函数行数和复杂度，防止“上帝函数”的产生。
  • Spec 为先：在写代码前，先与 AI 确认结构化 Spec，将返工率降低 70% 以上。
  • 规则固化：利用 .traerules 或 .cursorrules 将团队规范转化为 AI 的原生直觉。

💡 快速工具: JS 格式化工具 — 在 AI 生成后快速统一代码风格，确保符合团队排版标准。

AI 代码的“可维护性危机”

“AI 写的代码，跑得起来，但没人敢改。” 这是许多开发者在引入 GitHub Copilot 或 Cursor 后的共同感慨。AI 生成的代码往往具备以下“垃圾特征”：

  1. 命名诡异：喜欢用 data1, handleInfo, temp_list 这种信息量为零的名字。
  2. 函数臃肿：一个函数包揽了数据获取、格式转换、存储和错误处理，长达上百行。
  3. 依赖混乱：为了方便，随意引入项目中未授权或已过时的第三方库。
  4. 难以测试：强依赖全局变量，逻辑耦合度高，无法进行 Mock 测试。

问题出在 AI 吗？不完全是。AI 是“概率预测引擎”，它会生成最符合训练数据（往往包含大量低质量脚本）的输出。如果你不明确指出“干净代码”的标准，它就会走捷径。

核心哲学：规范即上下文

在 AI 时代，工程规范不再是写在 Wiki 里的死文档，而是必须喂给 AI 的活跃上下文。

AI 就像一个能力极强但没有原则的新同事。你需要告诉它：

  • 在这个项目里，React 组件必须用 PascalCase 命名。
  • 所有的异步操作必须包含 try-catch。
  • 禁止使用 moment.js，统一使用原生 Intl。

📝 术语链接: 提示工程 (Prompt Engineering) — 学习如何通过设计精准的提示词来引导大模型的输出。

实战指南：三步驯服 AI 输出干净代码

1. 明确角色与风格约束

不要直接说“写一个函数”，要赋予它专家人格并定义风格。

markdown 
# 好的提示词示例
你是一名拥有 10 年经验的资深 React 架构师。
请为我实现一个图片上传组件。
要求：
- 使用函数式组件 + Hooks。
- 遵循单一职责原则，将逻辑拆分为小的辅助函数。
- 强制使用 TypeScript，并开启 strict 模式。
- 变量命名使用 camelCase，布尔值必须带 is/has 前缀。

2. 建立命名与结构的“白名单”

通过提供现有的代码示例或具体的规则列表，让 AI 模仿。

javascript 
// ✅ 引导 AI 遵循的命名规范
const fetchUserOrderHistory = async (userId) => { ... }; // 动作 + 对象 + 详情

// ❌ AI 默认可能生成的命名
const getData = () => { ... };

3. 分步引导：先逻辑，后实现

不要让 AI 一次性吐出几百行代码。采用“设计-确认-实现”的流程。

graph TD A[提出需求] --> B["AI 输出实现思路/伪代码"] B --> C{人工确认思路?} C -- 否 --> D[修正思路] D --> B C -- 是 --> E[AI 生成具体实现] E --> F[生成单元测试] style A fill:#e1f5fe,stroke:#01579b style E fill:#e8f5e9,stroke:#2e7d32

进阶范式：规范驱动开发 (SDD)

规范驱动开发 (Spec-Driven Development) 是 2026 年最高效的 AI 协作模式。

它的核心思想是：输入质量决定输出质量。

步骤 动作 目的
Specify 定义功能目标、输入输出、异常场景 消除歧义，建立共识
Plan 让 AI 输出技术选型和架构设计 提前发现设计缺陷
Implement 根据已确认的 Spec 生成代码 实现与需求的高度一致
Validate 使用自动化工具和人工审查进行验证 确保不产生技术债

🔧 立即体验：使用我们的 JSON Schema 生成器 为你的 API 预先定义好 Spec，让 AI 严格按此结构生成代码。

工具化落地：在 IDE 中固化规则

现在流行的 AI IDE（如 Trae, Cursor, Windsurf）都支持“项目规则文件”。这是拒绝垃圾代码的终极利器。

在项目根目录创建 .traerules (或对应 IDE 的规则文件)，将你的[代码风格规范](file:///Users/xuezhangying/WebstormProjects/qubittool/.trae/rules/code-style.md)写进去：

markdown 
# QubitTool 代码风格规范

## 组件规范
- 必须使用函数式组件 + Hooks。
- Props 必须解构。

## 国际化规范
- 所有用户可见文本必须使用 t() 函数。
- 禁止在代码中硬编码中文或英文。

## 导入规范
- 顺序：React -> 第三方库 -> 内部组件 -> Hooks -> 工具函数 -> 样式。

当 AI 拥有了这份“宪法”，它在生成代码时会自动检查是否符合规范，甚至在你写出不规范的代码时主动提醒你重构。

最佳实践 Checklist

  1. [ ] 赋予角色：指定 AI 为资深工程师或架构师。
  2. [ ] 显性约束：明确提及“禁止使用 X”、“必须使用 Y”。
  3. [ ] 小步快跑：一个函数一个函数地生成，不要生成整个文件。
  4. [ ] 强制注释：要求 AI 为复杂逻辑添加 JSDoc 或 Python Docstring。
  5. [ ] 配套测试：要求 AI 同时生成单元测试，通过测试来验证代码逻辑。

⚠️ 常见错误:

  • 过于信任 AI 的初次输出 → 始终进行 AI 代码审查。
  • Prompt 太模糊 → 使用“你是一个...”公式。
  • 忽视上下文管理 → 及时清理不相关的旧对话，防止 AI 产生幻觉。

常见问题 (FAQ)

Q1: AI 总是喜欢引入我不需要的库怎么办？

回答：在你的提示词或 .rules 文件中维护一个“依赖白名单”。明确告诉 AI：“本项目仅允许使用 Ant Design, lodash-es, 和 axios。禁止引入任何其他 UI 库或状态管理库。”

Q2: 既然 AI 能写代码，为什么我还要关注命名规范？

回答：代码不仅是写给 AI 看的，更是写给人看的。良好的命名不仅能减少 AI 的幻觉 (Hallucination)，还能在未来的维护中大幅降低人类理解成本。

Q3: 使用 SDD 会不会让开发速度变慢？

回答：短期内写 Spec 会多花 5-10 分钟，但它能减少 80% 的调试和返工时间。在复杂项目中，SDD 是唯一的提效手段。

总结

拒绝 AI 生成垃圾代码，本质上是重新定义人与 AI 的协作边界。人负责“定义规范”和“确认 Spec”，AI 负责“高速执行”。通过建立一套可被 AI 自动识别的工程标准，你可以将大模型从一个“只会写 Hello World 的实习生”转化为一个“严格执行团队标准的资深专家”。

👉 立即开始使用 QubitTool 的开发辅助工具 — 让你的代码在 AI 时代依然保持极致的干净与专业。

相关资源