智能体工程朴素工作流

概述

智能体工程的核心理念很简单：

人类定义目标 → AI 生成代码 → 人类审核

朴素工作流更进一步：不需要复杂工具，只需要一个 AI 编码工具 + Markdown 写规范 + 人类审核。

本文介绍最简单、最朴素的方法，适合个人开发者或小团队快速上手。

一、朴素工作流的核心原则

1.1 最少工具原则

必需工具：
1. AI 编码工具（Claude Code / Cursor / Copilot）
2. 任意文本编辑器（写 Markdown 规范）
3. Git（版本控制）

可选工具：
- 测试框架
- 代码审查工具

1.2 核心信念

规范 > 代码 — 先写规范再写代码，规范是源代码，代码是编译结果

人类审核 — AI 生成的代码不是免检品，必须人类审核

简单胜过复杂 — 用最少的工具达成目标

二、工作流步骤

2.1 第一步：写规范（SPEC.md）

在项目根目录创建 SPEC.md：

# 功能名称

## 需求
- 描述要做什么
- 具体功能点

## 验收标准
- [ ] 标准 1
- [ ] 标准 2
- [ ] 标准 3

## 技术约束
- 技术要求（比如用 JWT、bcrypt）

## 边界情况
- 边界 1
- 边界 2

2.2 第二步：AI 生成代码

用 AI 编码工具读取规范，生成代码：

你：按照 SPEC.md 生成代码，实现用户登录功能

AI：生成代码...

你：看起来不错，生成测试代码

AI：生成测试...

2.3 第三步：人类审核

人类检查：

  • ✅ 代码是否符合 SPEC.md？
  • ✅ 有测试覆盖吗？
  • ✅ 有安全漏洞吗？
  • ✅ 变量命名清晰吗？

通过 → 提交代码
未通过 → 让 AI 修复

2.4 第四步：重复

SPEC.md → AI 生成代码 → 人类审核 → SPEC.md（新功能）

三、最简项目结构

my-project/
├── SPEC.md          # 项目规范（必须）
├── CLAUDE.md         # AI 上下文（可选）
├── src/             # 源代码
│   └── index.ts
├── tests/           # 测试
│   └── index.test.ts
└── .env             # 环境变量

最关键的是 SPEC.md，其他都是可选的。

四、实战示例：用户登录功能

4.1 写规范

创建 SPEC.md：

# 用户登录功能

## 需求
- 用户名/密码登录
- 登录失败返回错误信息

## 验收标准
- [ ] 正确密码能登录，返回 JWT token
- [ ] 错误密码显示"用户名或密码错误"
- [ ] 连续 5 次失败锁定 10 分钟

## 技术约束
- 使用 Express.js
- JWT 认证
- 密码 bcrypt 加密
- 存入 PostgreSQL users 表

## 边界情况
- 空用户名 → 返回"用户名不能为空"
- 空密码 → 返回"密码不能为空"
- 不存在的用户 → 返回"用户名或密码错误"（不暴露哪个字段错）

4.2 AI 生成代码

你：根据 SPEC.md，生成完整代码

AI：生成以下文件：
- src/auth/login.ts
- src/auth/password.ts
- src/db/users.ts
- tests/auth/login.test.ts
- package.json
- tsconfig.json

4.3 人类审核

检查：

  • 是否有 src/auth/login.ts？符合规范吗？
  • JWT 是否生成？
  • bcrypt 是否用于密码加密？
  • 5 次失败锁定的逻辑存在吗？
  • 错误消息是否"用户名或密码错误"（不区分）？
  • 有测试吗？测试覆盖登录成功、失败、锁定吗？

发现问题 → 让 AI 修复：

你：login.ts 缺少连续失败锁定逻辑，加上

AI：已修复，添加了 loginAttempts 字段和锁定逻辑

4.4 提交

git add .
git commit -m "feat: 用户登录功能
- JWT 认证
- bcrypt 密码加密
- 5次失败10分钟锁定"
git push

五、CLAUDE.md 示例

创建 CLAUDE.md 让 AI 理解项目上下文：

# 项目上下文

## 技术栈
- Node.js + TypeScript
- Express.js
- PostgreSQL

## 代码规范
- 4空格缩进
- 命名：camelCase（变量），PascalCase（类）
- 错误返回格式：{ error: "消息" }

## 项目结构
- src/ - 源代码
- tests/ - 测试文件
- SPEC.md - 功能规范

六、常见问题

Q: 规范要写多详细？

不要过度设计。

简单规范示例：

# 计算器

## 需求
- 加法
- 减法

## 验收标准
- [ ] 1 + 1 = 2
- [ ] 5 - 3 = 2

详细规范示例：

# 用户登录

## 需求
- 用户名/密码登录

## 输入
- username: string (1-50字符)
- password: string (8-128字符)

## 输出
- 成功: { token: "jwt...", user: { id, name } }
- 失败: { error: "用户名或密码错误" }

## 安全
- 密码 bcrypt 加密，cost 12
- JWT 过期 24 小时
- 5次失败锁定10分钟（基于 IP）

## 边界情况
- 空用户名 → 400 + "用户名不能为空"
- 空密码 → 400 + "密码不能为空"
- 用户不存在 → 401 + "用户名或密码错误"
- 密码错误 → 401 + "用户名或密码错误"
- 5次失败 → 429 + "账户已锁定"

规则：足够让 AI 生成可用代码，但不要过度设计。

Q: 审核要看什么？

检查关键点，不是逐行阅读：

检查项 为什么重要
代码是否符合 SPEC？ 确保满足需求
有测试吗？ 确保可维护
安全漏洞？ SQL注入、XSS等
错误处理？ 边界情况
命名清晰？ 可读性

Q: 发现问题怎么办？

让 AI 修复：

你：login.ts 的错误处理不够，添加：
1. 参数验证（空检查）
2. 数据库连接失败处理
3. 统一错误响应格式

AI：已修复，添加了参数验证和错误处理

Q: 可以跳过测试吗？

看场景：

场景 测试要求
快速原型 可跳过
学习项目 可跳过
生产代码 必须有
团队项目 必须有

简单测试也好过没有：

// 最简测试
test('登录成功', () => {
  const result = login('user', 'pass');
  expect(result.token).toBeDefined();
});

七、朴素工作流检查清单

开始之前：

  • 有 AI 编码工具（Claude Code / Cursor / Copilot）
  • 有文本编辑器
  • 有 Git

写规范时：

  • 需求描述清晰
  • 验收标准具体
  • 技术约束明确

生成代码后：

  • 代码符合 SPEC
  • 有测试覆盖
  • 无明显安全漏洞
  • 错误处理完整

八、朴素 vs 完整工作流

方面 朴素 完整
工具 AI + Markdown AI + 规范工具 + 审查工具 + 测试工具
规范 手动写 SPEC.md 专用规范工具（Spec-Kit等）
审核 人类检查 AI 辅助 + 人类检查
测试 简单断言 完整测试套件
适合 个人、快速原型 团队、生产项目

朴素工作流的目的是让你快速开始，不是替代完整工作流。

九、总结

朴素工作流：

1. 写 SPEC.md（规范）
2. AI 生成代码
3. 人类审核
4. 通过 → 提交
5. 重复

核心原则：

  • 规范 > 代码
  • 人类审核
  • 简单工具
  • 持续迭代

最小工具集：

  • AI 编码工具
  • Markdown 编辑器
  • Git

开始方法：

  1. 创建 SPEC.md
  2. 描述一个功能
  3. 让 AI 生成代码
  4. 人类审核
  5. 通过就提交

就这样。

参考来源