AI编码Agent实战：用Claude Code写测试、改代码、做批量审查

AI 写代码这件事，推了两年多，已经从自动补全阶段走到“自主执行任务链”阶段。这篇文章围绕 Use AI to make code better 这个主题展开，主线选 Claude Code 这类终端里的 AI 编码 Agent，原因是它的工作方式比较有代表性：不是一句一句补全，而是先读一遍仓库，自己规划改动，然后改代码、跑测试、根据日志继续修。整个过程都发生在终端里，适合配合 VS Code 使用，也适合接进自动化脚本。

真正值得关注的不是它能补全多少行，而是它能把“改代码—执行—看结果—再改”这个循环跑起来。对普通项目来说，这意味着写单元测试、批量替换旧接口、分析报错日志这类重复劳动，可以交给 Agent 处理，开发人员只做验收和兜底。Claude Code 只是其中一个代表，顺着同样的思路，OpenCode 等开源工具和各大模型厂商的 CLI 产品也在做类似的事，选型时可以横向对比。

这篇文章会按一套完整的本地实践顺序来组织：先看核心能力与硬件、环境门槛，再讲安装部署和 VS Code 接入，然后给一组可复现的功能测试，接着是 API 调用和批量任务脚本，最后是资源占用、常见问题和工程化建议。如果你正在选型 AI 编程助手，或者已经装上了但用不顺手，这篇可以直接存下来对照操作。

1. 核心能力速览

因为标题不绑定某个具体仓库，这里把 Use AI to make code better 当作一个能力集合来评估。当前最典型的载体是 Claude Code 这类终端 AI Agent，它们的能力边界可以先用一张表收敛。这里只写通用能力，不写具体版本号，因为这类工具更新非常快，版本差异会造成能力项变化。

有一点需要提前说清楚：这类工具不会每一条输出都正确。它的价值在于把机械化工作压缩到很短时间，但最终合并代码之前，人工 review 仍然不能省。后面第 10 章会展开说工程化边界。

2. 适用场景与使用边界

2.1 适合谁用

从实际使用场景看，最适合的是三类人。第一类是业务开发量大的工程师，日常要写大量 CRUD 接口、改表单页面、补单元测试，这类重复度高的任务非常适合 Agent 批量处理。第二类是维护老项目的开发者，面对一个历史包袱重的代码库，可以用 Agent 快速梳理模块间调用关系、找 TODO 和已废弃接口、批量替换过时写法。第三类是刚接手新项目的初学者，让 AI 解释代码要比在代码库里翻半天更高效。

它解决的问题也可以量化描述：写测试用例、跑 lint、根据报错修复、生成 Markdown 文档、做 Code Review 初筛。实际使用中最有感知的是“报错分析”，把异常堆栈贴给 Agent，省去大量搜索引擎来回跳转。一次好的报错排查，能把“找问题”的时间从半小时压缩到几分钟，剩下的是人工确认修改方案。

2.2 不适合什么场景

不适合的场景同样要讲清楚。第一，没有测试保护的核心模块，不要让 Agent 直接改，比如支付、鉴权、数据迁移。第二，架构层面的决策不要依赖单次对话，Agent 能给出重构方向，但最终取舍需要人对全局负责。第三，如果你的代码库包含用户隐私数据、密钥、内部业务数据，不要随便把整份文件塞进提示词。AI 编码工具不是所有问题的答案，它在边界清晰的机械任务里表现最好，在需要长期技术债判断的任务里只能当辅助。

2.3 版权、隐私与安全边界

AI 编程工具的安全边界要反复强调。首先，不要把 API Key、数据库连接串、客户敏感信息写在提示词里。其次，对于来源不明的命令要保持警惕，网上经常能看到类似“不要把自己不理解的代码粘贴到 DevTools 控制台”的警告，这个原则同样适用于终端里的 AI Agent，在让它执行 shell 命令之前，先看它准备跑什么。最后，AI 生成代码可能参考了开源项目，商用前要确认许可证兼容性。如果你用 AI 处理的是素材生成类代码，同样要确认内容授权链是否完整。

3. 环境准备与前置条件

部署一个终端 AI 编码 Agent，前置条件比图像生成类工具简单得多，不需要独显，不需要 CUDA，重点在 Node.js 环境、账号权限和网络连通性。下面是一套通用检查清单。

操作系统：macOS 或 Linux 可以直接在终端安装；Windows 用户建议先准备好 WSL 或确认原生终端支持。Node.js：建议使用官方 LTS 版本，安装后用命令确认。网络：需要能访问对应 API 服务，如果公司网络有访问限制，先确认终端环境能正常连通目标服务。账号：使用 Claude Code 需要 Anthropic 账号或对应的 API Key；如果是第三方转发服务，则按服务方文档准备。磁盘空间：CLI 工具本身占用不大，但 node_modules、构建缓存和日志会占空间，建议预留几 GB 空间。

# 检查 Node.js 和 npm 是否可用 node -v npm -v

如果 node 命令不存在，先安装 Node.js LTS。这里不推荐把版本锁定死，因为不同版本的 Claude Code 对 Node.js 的最低要求不同，以官方文档为准。检查完之后，最好在一个空目录里做一次平台测试，确认终端可以正常执行 npm 全局安装命令。

3.1 准备 API Key

API Key 是第一个容易卡住的地方。安装完成后，工具需要认证才能调用模型。官方支持登录授权和 API Key 两种方式。如果你走 API Key 方式，通常需要把它配置到环境变量里。

# 这里以常见变量名为例，具体名称以官方文档为准 export ANTHROPIC_API_KEY="your-api-key"

注意，不要把 Key 写进会被提交到 Git 的文件里，更不要写进仓库配置文件后推到远端。建议保存在 shell 配置文件或密钥管理工具中，并在 shell 配置里给它加上export，这样每次打开终端都会生效。如果你用 VS Code 的终端，还要确认 VS Code 是否继承了当前 shell 的环境变量，否则会出现“终端里明明设置了，但启动工具时依然报 401”的情况。

4. 安装部署与启动方式

4.1 安装 Claude Code

Claude Code 的安装方式以 npm 包为主，命令比较简单。以下命令是官方常见的安装方式，实际需要以当前版本文档为准。

npm install -g @anthropic-ai/claude-code

安装完成后，在项目根目录执行启动命令：

claude

第一次启动会进入授权流程，根据终端提示完成认证。如果环境变量里已经配置好 ANTHROPIC_API_KEY，认证通常会更顺畅。启动后你会看到一个交互式对话窗口，它可以读取当前目录下的文件，所以建议第一次先在测试项目里运行，不要直接把生产仓库当成试验场。

4.2 启动方式的三种形态

实际使用中，启动方式可以分为三种。第一种是交互式 REPL，直接在终端里对话，适合临时改代码、解释逻辑、排查问题。第二种是单次问答模式，通过命令行参数传入一个 prompt，输出结束后直接退出，适合写脚本场景。第三种是 API 调用，把请求打到模型服务端点，不依赖 CLI 界面，适合批量任务和业务系统接入。三种形态各有用途，交互式用来探索，单次命令用来自动化，API 用来集成。

下面给一个非交互式的通用示例，实际参数需要按工具文档调整：

claude -p "review the code changes under src/ and output a markdown list of issues"

如果你的场景只需要一次代码审查，这种单次模式比进入交互界面更高效。它还能被集成进 Git 钩子或 CI 脚本里，比如在 push 前自动跑一轮静态问题检查。

4.3 在 VS Code 终端里集成

VS Code 是 Claude Code 最常见的宿主环境。你不需要额外安装复杂的图形插件，直接打开 VS Code 内置终端，进入项目目录后启动 claude 即可。这样做的好处是：Agent 可以读取工作区内容，修改文件后你能立即在编辑器里看到 diff。编写代码时，你可以在对话里指定文件路径，让 Agent 只改某个模块，避免它越界碰到其它文件。

5. VS Code 集成与日常开发流

这一节把 VS Code 里的实际工作流拆开讲。先建立一个基础流程：编辑器里打开项目，内置终端启动 claude，然后用自然语言描述任务。任务描述越具体，Agent 的行为越可控。比如“把 src/utils.ts 里的 fetchUser 函数改成返回 getUserProfile，并同步更新调用方”就比“优化一下这个项目的代码”更容易得到可执行结果。

常见日常操作有三类。第一类是上下文解释：让 Agent 读某个文件并总结职责。第二类是代码生成：给它一段接口定义，让它生成 TypeScript 类型和 mock 数据。第三类是质量改进：让它把某个函数拆小、补上注释、补充单元测试。每一类操作完成后，都要先看 diff，再决定是否保留。实际体验中，最容易出问题的不是生成能力，而是 Agent 对项目结构的理解，所以提示词里带文件路径和目录范围会明显提高准确率。

在 VS Code 终端里，还可以结合 Git 一起用。比如先让 Agent 查看未提交的改动，再让它生成 commit message。这个流程很实用，因为 Agent 能读取git diff的内容，生成的提交说明比手写更完整。以下是一个通用提示词示例：

请先运行 git diff --stat，再看 src/ 目录的改动，然后为我生成一条简洁的 commit message，并列出改动可能影响到的模块。

这种“让 Agent 自己先看再回答”的方式，是终端 AI Agent 区别于普通聊天助手的关键点。它不只是回答你的问题，而是先收集现场信息，再基于真实代码状态输出结果。

6. 功能测试与效果验证

不管装好之后看起来多强，都要先跑一轮最小功能验证。下面的测试用例不绑定具体工具，任何终端 AI 编码 Agent 都可以参考。测试前准备一个小项目，包含一个纯函数文件和一个没有清理过的旧文件，足够观察 Agent 的理解和修改能力。

6.1 代码理解测试

目的：验证 Agent 能否准确读取文件并解释逻辑。写一段带有一点边界判断的纯函数，比如金额计算的函数，让 Agent 解释它的逻辑。输入示例：

请阅读 src/utils/money.ts，解释 formatMoney 函数的作用、输入参数、边界条件和潜在问题。

成功标准：回复里能准确说出函数的功能，能指出金额舍入、负数、空值等边界问题。如果回复只是泛泛而谈，说明上下文文件的加载可能有问题，检查是不是在正确的项目目录下启动了 Agent。

6.2 单测生成测试

目的：验证代码生成能力。选一个输入输出明确的纯函数，让 Agent 生成测试用例。输入示例：

请为 src/utils/calc.ts 中的 calculateTotal 函数生成 Jest 测试用例，覆盖正常值、空数组、负数和小数场景。

成功标准：生成的测试文件能直接运行或只做少量调整后运行；测试用例覆盖正常、边界、异常三类情况。如果生成代码里引入了不存在的 API，说明提示词里缺少约束，可以补充“只使用项目已有依赖”。

6.3 报错修复测试

目的：验证 Agent 的排错能力。故意引入一个编译错误或把 API 返回结构写错，然后让 Agent 看报错日志并修复。输入示例：

运行 npm run build 后出现以下错误：...（粘贴真实报错） 请分析可能原因，检查相关文件，给出最小改动修复方案。

成功标准：Agent 能定位到出错文件，提出的修复方案经过人工确认后可行。这一步重点观察它是否会直接改写不该动的文件，如果它准备修改范围过大，要立刻中断。排错能力是 AI 编码工具中最值得信任的能力之一，因为报错信息本身就是高信号输入。

6.4 批量替换效果测试

目的：验证批量任务处理能力。准备一个包含多个类似调用的旧文件，让 Agent 批量替换。

请把 src/pages 目录下所有文件里的 fetchUser 改为 getUserProfile，调用参数保持不变，先输出改动文件清单，不要直接改。

成功标准：Agent 先给清单而不是直接动手；确认后在指定范围内修改；执行后项目能通过编译。如果它没有先确认就改，说明对话缺少安全约束，下一章会给出批量任务的工程化建议。

7. 接口 API 调用与批量任务

终端 Agent 适合交互式使用，但如果要处理批量任务，比如一批文件的代码审查、一批历史接口的替换、一批单元测试的生成，建议直接走 API 调用。CLI 的非交互模式也可以做，但 API 更容易控制并发、记录日志、处理失败重试。

7.1 通用 API 调用示例

不同模型服务的 API 格式不一样，下面给的是 Anthropic Messages API 的通用模板，端点、模型名、请求头都以官方文档为准。模型名只是示例，不要直接照搬到生产环境。

import os import requests API_KEY = os.getenv("ANTHROPIC_API_KEY") endpoint = "https://api.anthropic.com/v1/messages" payload = { "model": "claude-3-5-sonnet-latest", "max_tokens": 1024, "messages": [ { "role": "user", "content": "请用一句话解释下面这段代码的作用：\n\ndef add(a, b):\n return a + b\n" } ] } headers = { "x-api-key": API_KEY, "anthropic-version": "2023-06-01", "content-type": "application/json" } response = requests.post(endpoint, headers=headers, json=payload, timeout=60) response.raise_for_status() print(response.json())

这个示例的运行前提是环境变量ANTHROPIC_API_KEY已经设置。第一次接入时，先打印一次完整返回 JSON，确认content字段的结构，再写后续的解析逻辑。很多接入问题都出在“照着旧文档解析字段”，而实际响应结构已经变了。

7.2 批量审查脚本

批量任务的核心是控制节奏和可观测性。下面这个脚本会遍历 target_files 目录下的所有 Python 文件，逐个调用 API 生成审查意见，写入 review_results 目录。每次请求之间加 1 秒延迟，避免瞬间触发限流。

import os import pathlib import time import requests API_KEY = os.getenv("ANTHROPIC_API_KEY") endpoint = "https://api.anthropic.com/v1/messages" def review_file(file_path: pathlib.Path) -> str: code = file_path.read_text(encoding="utf-8", errors="ignore")[:4000] payload = { "model": "claude-3-5-sonnet-latest", "max_tokens": 2048, "messages": [ { "role": "user", "content": f"请审查下面的代码，列出潜在问题和改进建议，输出 Markdown：\n{code}" } ] } headers = { "x-api-key": API_KEY, "anthropic-version": "2023-06-01", "content-type": "application/json" } resp = requests.post(endpoint, headers=headers, json=payload, timeout=120) resp.raise_for_status() return resp.json()["content"][0]["text"] input_dir = pathlib.Path("./target_files") output_dir = pathlib.Path("./review_results") output_dir.mkdir(exist_ok=True) for idx, f in enumerate(input_dir.glob("*.py")): try: result = review_file(f) (output_dir / f"{f.stem}_review.md").write_text(result, encoding="utf-8") print(f"[ok] {f.name} -> {output_dir / (f.stem + '_review.md')}") except Exception as e: print(f"[fail] {f.name}: {e}") if idx > 20: break time.sleep(1)

这个脚本里的模型名和响应解析路径同样是示例，接入时先打印一次完整返回 JSON，再写解析逻辑。批量任务最容易踩的坑是：单个文件内容过长导致超时、部分请求被限流、返回结构变化导致解析异常。所以脚本里要保留原始响应日志，方便失败后重放。

7.3 失败重试与并发控制

批量任务建议遵循三个原则。第一，限制并发，文件小的可以并发 2 到 3 个，文件大的最好串行。第二，做失败重试，对 429、5xx、超时等错误采用递增退避，比如第一次等 2 秒，第二次等 5 秒。第三，保存中间结果，每个文件成功后就立即写盘，避免整个任务重跑。如果你要把 AI 生成的意见直接写回仓库，务必先生成 diff，让人工确认后再落地。批量不是目的，可控才是目的。

8. 资源占用与性能观察

终端 AI 编码 Agent 的资源占用和图像模型完全不一样，没有显存焦虑，但有自己的观察重点。

首先是本地资源。Agent 本体运行在 Node.js 进程中，内存占用不会像大模型推理那样动辄十几 GB，但在扫描大型仓库、读取大量文件时会消耗 CPU 和