导读
本文介绍一套 AI 辅助开发工作流 — 一种人与 AI 结构化协作的开发模式.
核心思路: 把开发过程拆分为多个阶段, 每个阶段遵循 "AI 输出 → 人工审查" 的闭环, 确保过程可控, 结果可验收.
读完本文, 你将了解:
- 直接让 AI 写代码存在哪些问题
- 如何通过四个阶段实现高质量的人机协作
- 每个阶段中, 人应该关注什么
- 如何用 Claude Code Skills 将工作流落地为可执行命令
本文以 Claude Code 为例演示落地实现. 工作流思路本身不依赖特定工具 — Cursor, Copilot 等 AI 编码工具均有类似能力, 可参考思路自行适配.
问题: 直接让 AI 写代码为什么效果不好
直接把需求丢给 AI, 让它一步到位输出代码, 看似高效, 实际存在三个典型问题:
- 缺乏项目上下文 — AI 不了解你的项目规范, 技术栈偏好和业务术语, 生成的代码风格与项目格格不入
- 需求理解偏差 — AI 对需求的理解可能与你的预期不同, 等代码写完才发现方向错了, 返工成本高
- 输出难以验收 — 没有测试和审查机制, AI 输出的代码可能包含隐蔽的 Bug, 安全漏洞或性能问题
根源在于: AI 虽然能力强, 但它需要结构化的引导和验证.
解决思路: 分阶段协作 + 人工卡点
工作流的核心是 "分而治之" — 把 "需求 → 代码" 拆分为多个阶段, 每个阶段解决一个具体问题:
| 问题 | 解决方案 | 对应阶段 |
|---|---|---|
| 缺乏项目上下文 | 生成并维护项目上下文文档 | Phase 0 + Phase 3 |
| 需求理解偏差 | 先输出设计规格对齐需求理解 | Phase 1 (Spec) |
| 输出难以验收 | 先写测试建立验收标准 + 独立 AI 审查 | Phase 1 (Test) + Phase 2 |
整体流程:
Phase 0: 生成项目上下文, 让 AI "了解项目" (项目启动时执行一次)
Phase 1~3: (每个需求重复执行)
├── Phase 1: 规格驱动 + 测试先行
├── Phase 2: 代码审查
└── Phase 3: 更新项目上下文
核心原则: 每个阶段都遵循 "AI 输出 → 人工审查" 的模式. AI 负责生成, 人负责把关. 人的审查重心不是逐行检查细节, 而是判断 AI 的理解和决策是否正确.
Phase 0 — 生成项目上下文
项目上下文 (Context) 是写给 AI 看的项目文档, 包含技术栈, 目录结构, 编码规范, 业务术语等信息. 它的作用是让 AI "了解你的项目", 从而生成更符合项目风格的代码.
为什么需要这一步: 没有 Context, AI 只能基于通用知识生成代码, 无法适配项目特有的规范和约定.
Claude Code 内置了 /init 命令, 可以扫描代码仓库自动生成 Context, 输出为 CLAUDE.md 文件.
流程: AI 基于项目输出 Context → 人工审查
人工审查要点:
AI 对技术栈, 目录结构, 工程命令等事实性信息通常提取较准确, 确认无误即可. 重点审查:
- 项目认知 — 项目做什么, 服务于谁, 核心领域概念. 这些信息隐含在代码中, AI 可能理解不到位
- 编码规范 — 命名约定, 代码风格, 设计模式偏好. 这些通常是团队共识, AI 难以完全推断
Phase 1 — 规格驱动 + 测试先行
直接让 AI 写代码存在两个风险: 需求理解偏差导致方向错误, 输出难以验收导致质量失控.
本阶段结合两种工程实践来解决这两个问题:
- SDD (Specification-Driven Development) — 规格驱动开发. 先输出设计规格对齐需求理解, 解决 "方向错误" 问题
- TDD (Test-Driven Development) — 测试驱动开发. 先写测试建立验收标准, 解决 "难以验收" 问题
核心思路: 不急着写代码, 先让 AI 输出 Spec 对齐需求理解, 再基于 Spec 生成 Test Case 建立验收标准, 最后才写代码.
流程: Spec (对齐需求) → Test Case (建立验收标准) → Code (实现 + 验证)
Spec (设计规格)
SDD 的第一步: 让 AI 基于需求输出 Spec (设计规格).
为什么先写 Spec: 如果 AI 对需求的理解有偏差, 在 Spec 阶段就能发现并纠正, 成本远低于写完代码再返工.
Spec 通常包含:
- 改动范围 — 涉及哪些模块和文件
- 实现步骤 — 按什么顺序做, 每一步做什么
- 测试要点 — 需要验证哪些场景
流程: AI 基于需求输出 Spec → 人工审查
人工审查要点:
- 改动范围是否合理, 是否遗漏关键模块
- 实现步骤是否有逻辑问题
- 是否符合项目现有的架构和规范
Test Case (测试用例)
TDD 的关键: 在写代码之前先有测试.
Spec 中的 "改动范围, 实现步骤, 测试要点" 恰好就是生成 Test Case 所需的输入 — SDD 自然衔接 TDD.
流程: AI 基于 Spec 生成 Test Case → 人工审查
人工审查要点:
- 正常 / 边界 / 异常三类场景是否覆盖
- 是否遗漏业务特有的边界条件
Code (编码实现)
Spec 和 Test Case 确认后, 让 AI 基于两者输出代码.
完成标准: 测试通过 (test) + 静态检查通过 (lint, type check, format, build 等).
流程: AI 基于 Spec & Test Case 输出 Code → 运行测试和静态检查 → 未通过则修复重试 → 全部通过
AI 自行迭代直到测试和静态检查通过, 人只需确认通过结果, 无需逐行审查代码. 如果 AI 多次修复仍无法通过, 再由人工排查.
Phase 2 — 代码审查
代码通过测试和静态检查后, 由另一个独立的 AI 执行 Code Review.
为什么要换一个 AI: 实现代码的 AI 对自身的盲区缺乏感知. 换一个独立的 AI 审查, 能以旁观者视角发现问题.
流程: 独立 AI 基于代码变更输出 Review Report → 人工终审
人工审查要点:
- Bug 与安全漏洞 — 逻辑错误, 注入风险, 敏感信息泄露
- 性能问题 — 不必要的重复计算, 内存泄漏, N+1 查询
- 可维护性 — 命名规范, 模块职责划分, 耦合度
- 需求一致性 — 实现是否完整覆盖 Spec
Phase 3 — 更新项目上下文
项目上下文不是一次性产物, 需要随项目演进保持更新. 每个需求交付后, 由 AI 基于代码变更更新 Context.
为什么不能跳过这一步: 如果 Context 过时, 后续需求中 AI 的输出质量会逐渐下降 — 它会基于错误的项目信息生成代码.
流程: 需求交付 → AI 基于代码变更更新 Context → 人工审查
人工审查要点:
- 技术变更 — 新增的技术栈, 依赖, 工程命令是否被记录
- 业务变更 — 新增的业务概念, 模块, 架构决策是否被反映
- 废弃清理 — 已废弃的内容是否被移除
落地实现: 用 Skill 编排工作流
前面介绍了工作流的理念和各阶段职责, 本章介绍如何将其落地为可执行的命令.
Skill 是 Claude Code 的自定义命令机制 — 用 Markdown 文件定义一条指令 (包含角色, 任务, 约束等), 注册为 /命令名, 在对话中直接调用. 详见 官方文档.
思路: 用一个 Skill 编排整个流程 — 将工作流的所有阶段写进一个 Skill 的 prompt, 每步插入人工审查卡点. 只有 Code Review 阶段指示 AI 派生独立子 agent 执行, 以获得旁观者视角.
.claude/skills/
└── dev/SKILL.md # /dev <需求描述>
Skill 目录下的
SKILL.md是入口文件, 文件内容即 Skill 的 prompt.
使用流程
# 项目初始化 (一次性)
/init → 输出 CLAUDE.md → 人工审查
# 每个需求
/dev <需求描述>
├── Step 1 Spec → 人工审查
├── Step 2 Test Case → 人工审查
├── Step 3 Code → 测试 & 静态检查
├── Step 4 Review (子 agent) → 人工审查
└── Step 5 Context Update → 人工审查
Skill 示例
以下是一个参考模板, 展示如何将工作流编码为 Skill prompt. 具体的角色定义, 输出格式, 约束条件等, 可按项目实际需求自行调整.
---
argument-hint: <需求描述>
---
你是开发工作流的编排者. 请严格按照以下步骤执行, 每一步完成后暂停等待用户确认再继续.
## Step 1 — Spec (设计规格)
基于用户的需求描述, 输出 Spec. 内容包括:
- 改动范围 (涉及哪些模块和文件)
- 实现步骤 (按什么顺序做, 每一步做什么)
- 测试要点 (需要验证哪些场景)
完成后暂停, 等待用户审查 Spec 并确认.
## Step 2 — Test Case (测试用例)
基于 Spec, 生成 Test Case. 确保覆盖正常, 边界以及异常场景.
完成后暂停, 等待用户审查 Test Case 并确认.
## Step 3 — Code (编码实现)
基于 Spec 和 Test Case, 实现代码. 完成后运行测试和静态检查, 未通过则修复重试, 直到全部通过.
完成后暂停, 等待用户确认.
## Step 4 — Code Review (代码审查)
使用 Task 工具派生一个独立的子 agent 执行 Code Review, 输出 Review Report.
> 必须使用独立子 agent, 避免实现者的认知偏见影响审查质量.
完成后暂停, 等待用户审查 Review Report 并确认.
## Step 5 — Context Update (更新项目上下文)
基于本次需求的代码变更, 更新 CLAUDE.md. 确保新增的技术栈, 业务概念, 架构决策被记录, 已废弃的内容被移除.
完成后暂停, 等待用户审查 Context 变更并确认.
