AI Agent 测试先行开发：用 TDD 驯服大模型代码生成

最近 HN 上一个帖子引发了广泛讨论：rsync 项目引入 Claude 参与代码编写后，bug 率反而上升了。这不是个案——GitHub 的研究数据显示，AI 辅助编码工具生成的代码中，约 30% 存在逻辑错误或安全隐患。问题不在于 AI 不够聪明，而在于我们使用它的方式有根本性缺陷：先写代码再补测试的流程，对 AI 来说是一场灾难。本文将用实战案例证明，测试先行开发（TDD）是约束 AI Agent 输出质量最有效的工程方法。

🔍 一、为什么 AI 生成的代码 bug 多？

1.1 AI 编码的本质缺陷

大语言模型（LLM）生成代码的机制是「基于概率的下一个 token 预测」，它并不真正理解代码的语义。这意味着：

• ✅ 擅长：语法正确的代码、常见模式的实现、标准 API 的调用
• ❌ 不擅长：边界条件处理、并发安全、资源泄漏检测、业务逻辑的隐含约束

⚠️ **警告：**永远不要盲目信任 AI 生成的代码。LLM 没有编译器的类型检查能力，也没有运行时的上下文感知，它只是在「模仿」它见过的代码模式。

一个典型的例子——让 AI 实现一个简单的分页函数：

// ❌ AI 生成的常见写法（存在 bug）
function paginate(items, page, pageSize) {
  const start = page * pageSize;
  return items.slice(start, start + pageSize);
}
// bug：page 从 1 开始时，第一页会跳过前 pageSize 个元素

// ✅ 经过测试约束后的正确实现
function paginate(items, page, pageSize) {
  if (page < 1) page = 1;
  if (pageSize < 1) pageSize = 10;
  const start = (page - 1) * pageSize;
  return items.slice(start, start + pageSize);
}

1.2 「先代码后测试」的流程对 AI 不友好

传统开发中，开发者先写代码再补测试，依赖的是自身的隐式知识——你知道边界在哪里，因为你理解业务。但 AI 没有这种隐式知识。

当你对 AI 说「写一个用户注册接口」，它会给你一个看起来正确但细节上漏洞百出的实现。如果你先写好测试用例再让 AI 去实现，情况就完全不同了——测试用例就是显式的、可执行的需求文档。

🚀 二、AI + TDD 实战工作流

2.1 核心流程：Red → Green → Agent Refactor

经典 TDD 的「红-绿-重构」循环，在 AI 辅助开发中进化为：

1. Red：你（人类）编写失败的测试用例，定义期望行为
2. Green：AI Agent 分析测试用例，生成通过测试的代码
3. Refactor：AI Agent 优化代码结构，确保测试仍然通过

💡 **提示：**关键区别在于，测试用例必须由人类编写或严格审查。测试是「需求的精确表达」，把这个任务交给 AI 等于让 AI 自己出题自己答——它会倾向于写最容易通过的实现。

2.2 完整实战：用 AI 构建 JSON 数据脱敏工具

以 jsjson.com 的场景为例，我们用 TDD + AI Agent 构建一个 JSON 数据脱敏函数。

第一步：编写测试用例（人类完成）

// json-masker.test.js
import { describe, it, expect } from 'vitest';
import { maskJson } from './json-masker';

describe('maskJson - JSON 数据脱敏', () => {
  it('应该对手机号中间四位脱敏', () => {
    const input = { phone: '13812345678' };
    const result = maskJson(input, { phone: 'phone' });
    expect(result.phone).toBe('138****5678');
  });

  it('应该对邮箱用户名部分脱敏', () => {
    const input = { email: 'zhangsan@example.com' };
    const result = maskJson(input, { email: 'email' });
    expect(result.email).toBe('zha****@example.com');
  });

  it('应该支持嵌套对象的脱敏', () => {
    const input = {
      user: {
        name: '张三',
        idCard: '110101199001011234',
        address: { city: '北京', street: '朝阳路' }
      }
    };
    const result = maskJson(input, { 'user.idCard': 'idCard' });
    expect(result.user.idCard).toBe('110101********1234');
    expect(result.user.name).toBe('张三'); // 不脱敏的字段保持不变
  });

  it('应该支持数组中每个元素的脱敏', () => {
    const input = {
      users: [
        { name: '张三', phone: '13800001111' },
        { name: '李四', phone: '13900002222' }
      ]
    };
    const result = maskJson(input, { 'users[].phone': 'phone' });
    expect(result.users[0].phone).toBe('138****1111');
    expect(result.users[1].phone).toBe('139****2222');
  });

  it('应该保留原始对象不被修改（不可变性）', () => {
    const input = { phone: '13812345678' };
    const original = { ...input };
    maskJson(input, { phone: 'phone' });
    expect(input).toEqual(original);
  });

  it('遇到 null 或 undefined 应该原样返回', () => {
    expect(maskJson(null, {})).toBeNull();
    expect(maskJson(undefined, {})).toBeUndefined();
  });
});

第二步：让 AI Agent 实现代码（基于测试用例）

将测试文件和需求一起提供给 AI Agent（如 Claude Code、Cursor），提示词如下：

请根据 json-masker.test.js 中的测试用例，实现 maskJson 函数。
要求：
1. 支持 phone、email、idCard 三种脱敏规则
2. 支持嵌套对象路径（用点号分隔，如 'user.idCard'）
3. 支持数组路径（用 [] 表示，如 'users[].phone'）
4. 保持不可变性，不修改原始对象
5. 使用纯 JavaScript，无外部依赖

AI Agent 生成的实现：

// json-masker.js - AI 生成的实现
const MASK_RULES = {
  phone: (val) => {
    if (!/^1[3-9]\d{9}$/.test(val)) return val;
    return val.slice(0, 3) + '****' + val.slice(7);
  },
  email: (val) => {
    const [user, domain] = val.split('@');
    if (!domain) return val;
    const masked = user.length <= 3 ? user[0] + '***' : user.slice(0, 3) + '****';
    return masked + '@' + domain;
  },
  idCard: (val) => {
    if (val.length < 8) return val;
    return val.slice(0, 6) + '*'.repeat(val.length - 10) + val.slice(-4);
  }
};

export function maskJson(data, rules) {
  if (data === null || data === undefined) return data;
  if (typeof data !== 'object') return data;

  const result = Array.isArray(data) ? [...data] : { ...data };

  for (const [path, ruleType] of Object.entries(rules)) {
    applyMask(result, path, ruleType);
  }

  return result;
}

function applyMask(obj, path, ruleType) {
  const maskFn = MASK_RULES[ruleType];
  if (!maskFn) throw new Error(`Unknown mask rule: ${ruleType}`);

  const segments = path.split('.');
  applyMaskRecursive(obj, segments, 0, maskFn);
}

function applyMaskRecursive(current, segments, index, maskFn) {
  if (current === null || current === undefined) return;

  const segment = segments[index];
  const isLast = index === segments.length - 1;

  // 处理数组标记 users[]
  if (segment.endsWith('[]')) {
    const key = segment.slice(0, -2);
    const arr = current[key];
    if (!Array.isArray(arr)) return;

    for (let i = 0; i < arr.length; i++) {
      if (isLast) {
        arr[i] = maskFn(arr[i]);
      } else {
        applyMaskRecursive(arr[i], segments, index + 1, maskFn);
      }
    }
    return;
  }

  if (isLast) {
    if (segment in current) {
      current[segment] = maskFn(current[segment]);
    }
  } else {
    applyMaskRecursive(current[segment], segments, index + 1, maskFn);
  }
}

第三步：运行测试验证

# 运行测试
npx vitest run json-masker.test.js

# 预期输出：
# ✓ maskJson - JSON 数据脱敏
#   ✓ 应该对手机号中间四位脱敏
#   ✓ 应该对邮箱用户名部分脱敏
#   ✓ 应该支持嵌套对象的脱敏
#   ✓ 应该支持数组中每个元素的脱敏
#   ✓ 应该保留原始对象不被修改
#   ✓ 遇到 null 或 undefined 应该原样返回
# Tests 6 passed (6)

⚡ **关键结论：**这个流程中，测试用例就是你的「需求契约」。AI Agent 无论怎么实现，都必须通过这 6 个测试。这比任何 prompt engineering 都更有效地约束了 AI 的输出质量。

💡 三、进阶模式与避坑指南

3.1 测试用例的编写策略

测试用例的质量直接决定了 AI 生成代码的质量。以下是经过实战验证的编写策略：

覆盖率分层模型：

📌 **记住：**Happy Path 测试对 AI 来说几乎没有约束力——它几乎总能写出通过 happy path 的代码。真正有价值的是 Edge Cases 和 Invariants 测试，这才是暴露 AI 代码缺陷的关键。

必写的 5 类测试用例：

// 1. 🎯 基本功能验证
it('should convert snake_case to camelCase', () => {
  expect(toCamelCase('hello_world')).toBe('helloWorld');
});

// 2. ⚠️ 空值和边界
it('should handle empty string', () => {
  expect(toCamelCase('')).toBe('');
});

// 3. ⚠️ 特殊字符和 Unicode
it('should handle Unicode characters', () => {
  expect(toCamelCase('用户_名称')).toBe('用户名称');
});

// 4. 🔒 不可变性
it('should not mutate input', () => {
  const input = { nested: { key: 'hello_world' } };
  const original = JSON.parse(JSON.stringify(input));
  transformKeys(input, toCamelCase);
  expect(input).toEqual(original);
});

// 5. 🔒 幂等性
it('should be idempotent', () => {
  const input = 'hello_world';
  expect(toCamelCase(toCamelCase(input))).toBe(toCamelCase(input));
});

3.2 与主流 AI 编码工具的集成

不同 AI 工具对 TDD 工作流的支持程度差异明显：

💡 **提示：**Claude Code 和 Aider 是 TDD 工作流的最佳选择，因为它们能自动执行测试命令并根据失败信息迭代修复代码。Cursor 的 Agent 模式也很好，但需要手动触发测试运行。

Claude Code 的最佳 TDD 提示词模板：

# 在 Claude Code 中使用 TDD 工作流

# 1. 先创建测试文件
claude "根据以下需求，只生成测试用例文件，不要实现代码：
- 需求：实现一个 URL 解析器，提取协议、域名、路径、查询参数
- 要求：支持 IPv6 地址、端口号、fragment
- 测试框架：vitest"

# 2. 审查测试用例，确认覆盖了所有边界情况后，让 AI 实现
claude "运行 tests/url-parser.test.js，根据测试失败信息实现 url-parser.js。
约束：不使用 URL 构造函数，纯字符串解析实现。"

# 3. 让 AI 重构但保持测试通过
claude "重构 url-parser.js，提取公共方法，改善代码可读性。
运行测试确认重构后所有用例仍然通过。"

3.3 常见坑点与避坑策略

❌ 坑点 1：让 AI 同时写测试和实现

# ❌ 错误做法
claude "帮我写一个 URL 解析器，包含测试用例"
# AI 会倾向于写简单的测试来匹配它容易实现的代码

# ✅ 正确做法
claude "这是我写的测试文件 [粘贴测试]，请实现通过这些测试的代码"
# 测试作为约束条件，AI 必须满足你的期望

❌ 坑点 2：测试用例过于模糊

// ❌ 模糊的测试 — AI 有很多"正确"的实现方式
it('should parse URL', () => {
  const result = parseUrl('https://example.com/path');
  expect(result).toBeDefined();
});

// ✅ 精确的测试 — 唯一正确的实现
it('should extract protocol, host, path and query params', () => {
  const result = parseUrl('https://api.example.com/v2/users?page=1&size=20#top');
  expect(result).toEqual({
    protocol: 'https',
    host: 'api.example.com',
    port: null,
    path: '/v2/users',
    queryParams: { page: '1', size: '20' },
    fragment: 'top'
  });
});

❌ 坑点 3：忽略 AI 生成代码中的硬编码

AI 有一个常见倾向：为通过特定测试用例而硬编码返回值。

// ❌ AI 可能生成的"作弊"实现
function parseUrl(url) {
  if (url === 'https://api.example.com/v2/users?page=1&size=20#top') {
    return {
      protocol: 'https',
      host: 'api.example.com',
      port: null,
      path: '/v2/users',
      queryParams: { page: '1', size: '20' },
      fragment: 'top'
    };
  }
}

// ✅ 用参数化测试防止硬编码
it.each([
  ['https://example.com/path', { protocol: 'https', host: 'example.com', path: '/path' }],
  ['http://localhost:3000/api', { protocol: 'http', host: 'localhost', port: '3000', path: '/api' }],
  ['ftp://files.org/pub/doc.pdf', { protocol: 'ftp', host: 'files.org', path: '/pub/doc.pdf' }],
])('parseUrl(%s) should return correct structure', (url, expected) => {
  const result = parseUrl(url);
  expect(result).toMatchObject(expected);
});

⚠️ **警告：**参数化测试（it.each）是防止 AI 硬编码返回值的最佳手段。当测试覆盖 5 个以上不同的输入时，AI 几乎不可能通过硬编码来「作弊」。

3.4 回归测试的安全网

TDD 工作流的另一个关键优势是构建回归测试安全网。当 AI 重构代码时，现有测试用例就是你的安全网：

# 工作流示例
# 1. 正常开发：积累测试用例
npx vitest run                    # 120 tests passed

# 2. AI 重构代码
claude "重构 auth 模块，将 JWT 逻辑提取到独立的 token-service.js"

# 3. 重构后立即运行测试
npx vitest run                    # 如果有测试失败，立即发现问题
# ✓ 118 passed
# ✗ 2 failed - token-expiry 相关的测试失败

# 4. 让 AI 修复失败的测试
claude "测试 token-expiry.test.js 失败了，错误信息如下：[粘贴错误]
请修复 token-service.js 中的问题，不要修改测试文件。"

🔧 四、团队级 AI + TDD 实践建议

4.1 建立测试用例审查流程

在团队中推行 AI + TDD 时，最关键的一环是测试用例的审查，而不是代码审查。

# .github/workflows/ai-tdd-review.yml
name: AI TDD Review
on:
  pull_request:
    paths:
      - 'src/**/*.ts'
      - 'tests/**/*.test.ts'

jobs:
  tdd-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 检查测试覆盖率
        run: |
          npx vitest run --coverage
          npx istanbul check-coverage \
            --statements 80 \
            --branches 75 \
            --functions 85

      - name: 检查测试是否存在（防止 AI 删除测试）
        run: |
          # 确保测试文件没有被删除或大量减少
          TEST_COUNT=$(find tests -name "*.test.*" | wc -l)
          if [ "$TEST_COUNT" -lt 10 ]; then
            echo "❌ 测试文件数量异常减少！"
            exit 1
          fi

4.2 项目级 AI 配置

在项目根目录创建 AI 工具的配置文件，强制 TDD 行为：

// .cursor/rules/tdd.mdc (Cursor Rules)
{
  "description": "TDD 工作流规则",
  "rules": [
    "修改任何源代码之前，必须先确认存在对应的测试用例",
    "实现新功能时，先生成测试用例文件，等用户确认后再生成实现代码",
    "重构代码后必须运行测试确认全部通过",
    "不允许修改测试文件来让测试通过（除非测试本身有误）",
    "测试覆盖率不低于 80%"
  ]
}

# .claude/CLAUDE.md (Claude Code 项目指令)
## TDD 工作流规则
1. 实现新功能前，先编写或确认测试用例
2. 每次代码修改后运行 `npm test` 确认全部通过
3. 禁止为了通过测试而硬编码返回值
4. 重构时保持测试绿色（所有测试通过）
5. 覆盖率目标：语句 80%、分支 75%、函数 85%

4.3 度量 AI + TDD 的效果

持续追踪以下指标来衡量 TDD 对 AI 代码质量的影响：

⚡ 关键结论：TDD 不仅提升了 AI 代码的质量，更重要的是它让团队敢于重构。当你知道 120 个测试用例守护着核心逻辑时，AI 建议的任何重构都可以安全执行——跑一遍测试就知道有没有问题。

📊 总结

AI 编码工具已经从「可选辅助」变成了「日常必备」，但随之而来的代码质量问题不能靠祈祷来解决。TDD 是唯一经过数十年工程验证的方法论，它天然适配 AI Agent 的工作模式——显式的、可执行的需求约束。

三个核心行动项：

• ✅ 测试用例由人类编写——测试是需求的精确表达，不要把这个责任交给 AI
• ✅ 参数化测试防止硬编码——5 个以上的不同输入让 AI 无法「作弊」
• ✅ 团队审查重点在测试——测试覆盖的质量比代码实现的风格更重要

推荐工具链：

• 🧪 测试框架：Vitest（前端）、pytest（Python）、JUnit 5（Java）
• 🤖 AI Agent：Claude Code（TDD 最佳）、Cursor Agent、Aider
• 📊 覆盖率：V8 Coverage（前端）、Istanbul/nyc
• 🔄 CI 集成：GitHub Actions + 覆盖率门槛检查