AI 编程最佳实践：从 Vibe 模式到 Claude Code 的 Spec 编程

一、AI 编程认知

1.1 AI 是副驾驶，不是自动驾驶

副驾驶坐在你旁边，帮你导航、操作仪表、处理常规事务，但你始终握着方向盘。遇到关键决策时，由你拿主意。自动驾驶则是你设置目的地后就可以睡觉了，它自己开。

2026 年的 AI 编程工具是 Copilot，不是 Autopilot。

AI 可以：

• 大幅加速编码过程（写代码速度快 2-5 倍）
• 帮你处理重复性工作（CRUD、样板代码、格式化）
• 辅助学习新技术（解释概念、生成示例）
• 发现潜在问题（代码审查、安全检查）

但 AI 不能：

• 替你理解业务需求的本质
• 替你做架构决策
• 保证生成的代码没有 Bug 和安全漏洞
• 替你维护和调试复杂的系统

最高效的 AI 编程模式：人负责思考和决策，AI 负责执行和加速。

1.2 AI 编程的三种模式

可以把这三种模式理解成一个从简到繁的坐标轴：项目越简单、越清晰，就越适合快速推进；项目越复杂、越模糊，就越需要在动手之前把结构搭好。

1.3 Spec 编程（规范驱动开发）

Spec Coding（Spec-Driven Development，SDD） 是一种新兴的 AI 辅助开发方法论，它将软件规范（Specification）作为开发的核心和真理之源。

与传统的"Vibe Coding"（即时反应式编码）不同，Spec Coding 强调在编写代码之前先建立清晰、结构化的规范文档，然后让 Coding Agent 基于这些规范生成代码。

核心洞察：我们正在从「代码是真理之源」转向「意图是真理之源」。

在 AI 时代，规范不再是被束之高阁的静态文档，而是变成了可执行的、活的产物（Living Artifacts），能够直接驱动代码的生成和演进。

一个非常简单的需求当然可以直接 Vibe Coding，但当你开始尝试做复杂项目时，随着会话变长，智能体往往会逐渐失去对全局的把握。

Spec 就是为了解决这一问题而存在的——它提供一份可以持续维护的实现计划，让人和 AI Agent 在整个开发过程中始终对齐：现在在做什么、接下来要做什么、什么算完成。如果你曾经见过 AI 在项目进行到一半时突然「跑偏」，那么 Spec 就是帮你预防这种情况的那根「安全绳」。

二、Claude Code 编程工具

Claude Code 内置的规则能够有效保证 AI 按照符合预期的方式运行，也就是 Harness 工程。配置好 Claude Code 能够让编程工具稳定输出。

关于 Claude Code 的详细用法，可参考 官方文档。

2.1 CLAUDE.md

CLAUDE.md 是进入项目时第一个读取的文件，相当于项目欢迎手册。

• 放置在项目根目录，所有团队成员共享
• 包含项目背景、规范、命令
• 每次开工前 Claude 都会先读一遍
• 优先级比对话中说的话更高

如果你在 CLAUDE.md 里写了「用 pnpm 不用 npm」，之后即使口头说「用 npm 装」，Claude 也会优先遵循文件里的规则。

典型内容示例

# My Project

一句话描述项目用途。

## Tech Stack
- Backend: Python / FastAPI
- Frontend: React + TypeScript
- Database: PostgreSQL

## Common Commands
`npm run dev`    # 启动开发服务器
`pytest tests/`  # 运行测试
`npm run build`  # 构建生产版本

## Code Conventions
- 使用 snake_case 命名变量
- 所有 API 需要写单元测试
- PR 合并前必须通过 CI

## Architecture Overview
src/
├── api/        # FastAPI 路由层
├── services/   # 业务逻辑层
└── models/     # 数据模型层

该写什么（Claude 无法自己推断的「项目特殊情况」）

• 常用命令：怎么构建、测试、运行、lint。Claude 会执行这些，所以必须准确
• 架构说明：用三两句话讲清楚主要模块和它们怎么通信
• 硬约束：比如「永远不要从测试写生产数据库」「所有 API 路由必须经过认证中间件」「不要编辑 generated/ 目录」
• 编码约定中 Claude 猜不到的：比如「用 X 不用 Y」的决定、特殊的命名规范、错误处理方式
• 已知的坑：每个新人都会踩的坑，提前告诉 Claude

不该写什么

• 完整的 API 文档：Claude 可以直接读代码，没必要复制一份
• 代码风格细节：缩进、行长这些交给 linter，不用浪费 Claude 的注意力
• 模糊的「最佳实践」：「写出高质量代码」「遵循 SOLID 原则」这类话没有信息量
• 会过期的信息：文件数量、版本号等频繁变动的内容

渐进式扩展

随着项目发展，再逐步引入：

2.2 Rule（规则）

Rule 本质是可复用上下文，约束 AI 行为边界，避免代码风格、架构、技术选型随机跑偏。

什么时候应该沉淀 Rule？ 当反复纠正 AI 同一类错误时，就应当把该要求沉淀为 Rule。

2.3 Skill（技能）

Agent Skills，为 Agent 扩展能力。

Skill 是带 SKILL.md 的目录，包含指令、脚本、资源，为 Agent 赋予额外能力。

• 工作机制：采用渐进式披露——先仅加载技能简介，任务匹配成功才加载完整指令，按需执行脚本，减少上下文占用
• 适用场景：固定重复工作流、沉淀个人与团队经验资产

2.4 Command（命令）

在 Claude Code 中，Command 本质上是「提示词模板」或「快捷指令」。它们是你预先定义好的工作流，通过输入 /命令名 来触发，用来执行重复性的任务，或者为特定场景加载专门的上下文。

你可以把它理解成给 Claude 设定的「一键宏」。它的核心作用有两点：

1. 自动化重复工作流：比如你每次部署前都要跑一遍「测试 → 构建 → 检查健康状态」，就可以写成一个 /deploy-staging 命令。以后只需输入这个命令，Claude 就会按你预设的步骤执行。

2. 按需加载专业上下文：Claude 的上下文窗口有限。Command 允许你只在需要时，才把某个特定领域（如数据库操作、API 设计）的规范、模式或指令注入给 Claude，避免一开始就塞满无关信息，从而让回答更精准。

2.5 Agent（子代理）

Agent（在 Claude Code 中通常指 Subagent） 是一个拥有独立上下文窗口的专职 AI 助手。如果说 Skill 是「技能包」，那 Agent 就是一个「有自己工位的专家员工」——它接到任务后在自己的工位上独立干活，干完只把结果汇报给你，不会把中间过程塞进你的主对话里。

核心价值只有一个：上下文隔离。

主对话的窗口是有限的。如果你让 Claude 去「遍历 50 个文件找性能瓶颈」，那些文件内容、中间推理过程会瞬间填满你的对话窗口，后续再聊别的就「没地方了」。Agent 解决的就是这个问题：它在自己的独立窗口里完成这些「脏活累活」，只把最终结论（比如「发现 3 个瓶颈，分别在 fileA.ts:120、fileB.ts:45」）带回主对话。

三、最佳实践

3.1 功能拆分，逐个实现

不要一次性让 AI 实现整个功能。 将大功能拆分为独立模块，逐个实现和验证：

❌ 错误做法
帮我实现完整的用户注册登录系统

✅ 正确做法
第一步：实现 User 模型和数据库迁移
第二步：实现注册 API 和输入校验
第三步：实现邮箱验证码发送和验证
第四步：实现登录 API 和 JWT 签发

每个模块完成后验证一下，确认没问题再进入下一个。 这样即使 AI 生成了有问题的代码，你也能快速定位问题出在哪个模块。

3.2 提供足够的上下文

AI 编程工具的输出质量，直接取决于你提供的上下文质量：

❌ 低质量 Prompt
写一个 Express 中间件做 JWT 认证

✅ 高质量 Prompt
项目使用 Express 4 + TypeScript，ESM 模式。
写一个 JWT 认证中间件，要求：
- 从 Authorization header 提取 Bearer token
- 使用 jsonwebtoken 库验证
- 支持 token 过期自动刷新
- 将解码后的用户信息挂载到 req.user
- 未认证返回 401，token 过期返回 401 + 特定标识
- 参考项目中已有的 middleware/auth.ts 的代码风格

高质量 Prompt 的核心差异：

• 技术栈和版本明确
• 具体行为要求清晰
• 指定了参考代码风格
• 边缘情况的处理方式明确

3.3 编程专用高效 Prompt 技巧

以下是从大量实践中总结的编程 Prompt 最佳实践：

技巧一：结构化描述需求

用固定的结构描述你的需求，而不是写一长段文字：

## 任务
实现分页查询功能

## 技术栈
- 后端：Express 4 + TypeScript + better-sqlite3
- 前端：Vue 3 + Element Plus

## 要求
- 后端支持 offset/limit 分页 + 总数统计
- 前端使用 el-pagination 组件
- 支持按创建时间排序
- 每页默认 20 条，最大 100 条

## 参考
参考项目中 src/api/posts.ts 的分页实现

技巧二：分步而非一次性

对于复杂任务，明确告诉 AI 分步骤执行：

请分以下步骤操作：
1. 先阅读现有的数据库 schema，了解表结构
2. 设计新表的 schema
3. 写迁移脚本
4. 实现 CRUD API
5. 编写单元测试
6. 运行测试确认通过

每一步完成后等我说"继续"再进行下一步。

技巧三：指定约束和风格

明确告诉 AI 你的项目约束：

项目约束：
- TypeScript strict mode，不允许 any
- 统一使用 ESM import，路径必须带 .js 后缀
- 错误处理用 try-catch，返回 res.status(500).json({ error: '描述' })
- CSS 只用原生 CSS + CSS 变量，不用预处理器

技巧四：用否定告诉 AI 不要做什么

有时候告诉 AI「不要做什么」比「要做什么」更有效：

注意：
- 不要引入新的 npm 依赖
- 不要使用 any 类型
- 不要修改现有 API 的接口签名
- 不要使用 eval 或 Function 构造器
- 不要在组件中直接使用 axios，走 api/index.ts

技巧五：迭代式对话

不要期望一次 Prompt 就得到完美结果。用对话逐步优化：

第一轮：写一个函数实现 X 功能
第二轮：上面的实现有性能问题，N+1 查询，请优化
第三轮：加上错误处理和日志
第四轮：为这个函数写单元测试

每一轮在前一轮的基础上改进，比一次写完所有要求效果好得多。

技巧六：让 AI 主动询问

当 AI 遇到不明白的边界、模糊的定义时会自己猜测，往往结果并不是想要的。可以通过让 AI 询问自己的方式大量避免这种猜测。

只需要在 prompt 的后面加一句：「有不明白的问我，不要猜测」

3.4 禁止不理解就接受

看到 AI 生成的代码能用就直接提交，不理解每行代码的含义。这比手写代码更危险——你至少理解自己写的代码，但不理解 AI 生成的代码意味着出了 Bug 你完全无法调试。

应对方法：

• 对 AI 生成的每一段代码，确保你能解释它的作用
• 遇到不理解的代码，让 AI 解释，直到你理解为止
• 把「不理解」视为红色警报，而非跳过的理由

3.5 基础习惯

• 每次编码前先描述清楚需求再开始
• 使用项目的编码规范文件（如 CLAUDE.md）提供上下文
• 复杂任务拆分为小步骤，逐步让 AI 实现
• AI 生成的代码每段都审查，理解后再接受
• 每完成一个功能就让 AI 生成对应的测试

3.6 团队习惯

• 团队统一 AI 编程工具和模型选择
• 建立团队共享的 Prompt 库和 CLAUDE.md 模板
• 制定 AI 生成代码的审查标准
• 定期分享 AI 编程的高效用法和新发现
• 对 AI 生成的代码标注来源，便于后续追溯

参考资料

• AI 编程工作流
• AI 编程最佳实践
• Claude Code 官方文档
• UI/UX Pro Max Skill