AI 编程 Agent 实战:如何让智能开发工具理解项目、修改代码与自动测试

举报
yd_228838069 发表于 2026/11/16 09:30:43 2026/11/16
【摘要】 一、什么是 AI 编程 Agent?随着 AI 技术的发展,编程工具已经不再局限于代码补全和语法提示。一类能够理解项目结构、分析代码、修改文件、执行命令和运行测试的智能开发工具,逐渐成为软件开发中的辅助方式。这类工具通常被称为 AI 编程 Agent。与传统的代码补全不同,AI 编程 Agent 可以围绕一个开发任务执行多个步骤:阅读项目文件,了解项目结构。分析现有代码,理解模块之间的关系。...

一、什么是 AI 编程 Agent?

随着 AI 技术的发展,编程工具已经不再局限于代码补全和语法提示。一类能够理解项目结构、分析代码、修改文件、执行命令和运行测试的智能开发工具,逐渐成为软件开发中的辅助方式。

这类工具通常被称为 AI 编程 Agent。

与传统的代码补全不同,AI 编程 Agent 可以围绕一个开发任务执行多个步骤:

  1. 阅读项目文件,了解项目结构。

  2. 分析现有代码,理解模块之间的关系。

  3. 根据需求制定修改计划。

  4. 创建、修改或删除相关文件。

  5. 执行安装、构建和测试命令。

  6. 根据错误信息继续修复。

  7. 汇总修改内容和测试结果。

例如,我们希望给一个现有的 FastAPI 项目增加文章管理功能。传统方式需要开发者手动查找路由、数据库模型、业务逻辑和接口结构,而 Agent 可以先分析项目,再根据现有代码风格完成修改。

但需要注意:AI Agent 并不意味着可以完全代替开发者。它可能误解需求、修改不相关文件,甚至生成看似正确但实际无法运行的代码。

因此,合理的工作流程应该是:

先理解项目,再制定计划,然后修改代码,最后执行测试并人工检查。

本文通过一个实际开发场景,介绍如何让 AI 编程 Agent 参与现有项目的开发。


二、让 Agent 理解现有项目

1. 为什么不能直接让 Agent 写代码?

假设一个项目已经开发了一段时间,目录结构如下:

my-project/
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── database.py
│   │   ├── models/
│   │   ├── schemas/
│   │   ├── routers/
│   │   └── services/
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── api/
│   │   ├── components/
│   │   ├── views/
│   │   └── router/
│   └── package.json
└── README.md

如果直接告诉 Agent:

帮我开发一个文章管理系统。

它可能会重新设计目录结构、创建重复的数据库模型,或者使用与现有项目不同的技术方案。

这会增加后续维护成本。

正确的做法是先让 Agent 阅读项目,了解当前系统。

2. 第一步:要求 Agent 分析项目

可以使用下面的提示词:

请先完整分析当前项目,不要修改任何文件。

重点检查:

1. 项目的整体目录结构。
2. 使用的编程语言和技术框架。
3. 前后端分别采用什么架构。
4. 数据库连接方式和数据模型。
5. API 路由组织方式。
6. 用户认证和权限控制方式。
7. 前端路由、组件和接口调用方式。
8. 当前已有的主要功能。
9. 项目中是否存在明显的结构问题。

请输出:

- 项目架构说明
- 主要目录和文件的作用
- 核心业务流程
- 前后端数据交互方式
- 重要技术约束
- 可能存在的问题

只进行分析,不要创建、修改或删除文件。

这一步的目的不是立即开发,而是让 Agent 建立对项目的整体认识。

3. 第二步:检查关键文件

项目结构分析完成后,还需要进一步检查核心文件。

例如:

请继续分析以下内容:

1. 数据库模型之间的关系。
2. 用户登录和身份验证流程。
3. API 的统一响应格式。
4. 全局异常处理方式。
5. 前端请求拦截器。
6. 前端登录状态管理。
7. 现有代码的命名规范。

请结合实际代码说明,不要仅根据文件名推测功能。

如果某个功能无法确认,请明确标记为未知。

这一步可以减少 Agent 对项目的错误判断。

4. 建立项目说明文档

对于持续开发的项目,建议维护一份项目说明文档,例如:

PROJECT_GUIDE.md

内容可以包括:

# 项目开发说明

## 技术栈

- 后端:Python + FastAPI
- 前端:Vue 3 + TypeScript
- UI:Element Plus
- 数据库:MySQL
- 缓存:Redis

## 后端约定

- API 路由统一放在 routers 目录
- 数据模型统一放在 models 目录
- 请求和响应结构统一放在 schemas 目录
- 业务逻辑放在 services 目录
- 数据库连接统一使用 database.py

## 前端约定

- 页面放在 views 目录
- 公共组件放在 components 目录
- API 请求放在 api 目录
- 路由配置放在 router 目录

## 开发要求

- 优先复用现有代码
- 不随意更换技术栈
- 不重复创建已有功能
- 修改前先分析影响范围
- 完成后运行相关测试

项目说明文档可以帮助 Agent 快速了解项目的技术约定。

不过,文档需要与实际代码保持一致。如果项目发生了较大变化,应及时更新。


三、让 Agent 按照计划修改代码

理解项目之后,才进入实际开发阶段。

这里以给 FastAPI 项目增加文章管理功能为例。

1. 不要一次性提出过大的需求

不建议这样描述:

帮我把整个后台管理系统完善一下,
包括文章管理、用户管理、权限管理、
分类管理、标签管理和数据统计。

这类需求涉及多个业务模块,容易出现:

  • 修改范围过大。

  • 不同模块之间产生冲突。

  • 数据库模型设计不一致。

  • 接口和前端页面无法对应。

  • 出错后难以定位问题。

更好的方法是将任务拆分为多个独立阶段。

例如:

阶段 开发任务
第一阶段 文章数据库模型
第二阶段 文章 CRUD 接口
第三阶段 文章列表和分页
第四阶段 文章搜索和筛选
第五阶段 前端文章管理页面
第六阶段 接口测试和功能验证

每完成一个阶段,就检查一次结果。

2. 先让 Agent 制定修改计划

例如:

现在需要在现有项目中增加文章管理功能。

功能需求:

1. 管理员可以创建文章。
2. 管理员可以编辑文章。
3. 管理员可以删除文章。
4. 管理员可以查看文章列表。
5. 支持分页查询。
6. 支持根据文章标题搜索。
7. 支持根据发布状态筛选。

开发要求:

- 使用现有数据库连接方式。
- 复用现有用户认证机制。
- 遵循项目当前目录结构。
- 不重复创建已有的功能。
- 不修改无关业务模块。

请先检查现有代码,并输出:

1. 需要修改的文件。
2. 需要新增的文件。
3. 数据库结构设计。
4. API 接口设计。
5. 前端页面设计。
6. 可能产生的兼容性问题。

暂时不要修改代码,等待我确认计划。

这样可以提前发现设计问题。

3. 确认计划后再执行

当开发计划没有问题时,可以让 Agent 开始实施:

按照刚才确认的开发计划执行。

要求:

1. 先完成后端数据库模型和 API。
2. 再完成前端页面。
3. 不要一次性重构整个项目。
4. 尽可能复用已有组件和工具函数。
5. 保持现有 API 的兼容性。
6. 不要擅自修改数据库中的已有数据。
7. 完成每个阶段后检查修改结果。

如果发现原计划与实际代码不一致,
请先说明原因,再决定是否调整。

这种方式可以让开发过程更加可控。


四、让 Agent 修改代码时保持边界

AI 编程 Agent 最容易出现的问题之一,就是修改范围超出预期。

例如,你只是想修改文章列表的分页功能,但 Agent 顺便重写了数据库连接、统一响应结构和前端请求拦截器。

这可能引入新的 Bug。

因此,在提示词中应该明确修改边界。

1. 明确允许修改的文件

例如:

本次任务只允许修改:

backend/app/routers/articles.py
backend/app/services/articles.py
backend/app/schemas/articles.py
frontend/src/views/articles/index.vue

如果确实需要修改其他文件,
请先说明原因并等待确认。

2. 明确禁止事项

本次开发必须遵守:

1. 不更换现有技术框架。
2. 不修改数据库连接配置。
3. 不删除已有 API。
4. 不重构无关模块。
5. 不修改生产环境配置。
6. 不清理或删除现有数据。
7. 不覆盖已有用户上传文件。

3. 要求 Agent 说明修改内容

完成任务后,可以要求它输出:

请总结本次修改:

1. 修改了哪些文件?
2. 新增了哪些文件?
3. 每个文件具体修改了什么?
4. 是否修改了数据库结构?
5. 是否新增了依赖?
6. 是否影响已有接口?
7. 执行了哪些测试?
8. 哪些功能尚未验证?

不要只说已经完成,
请根据实际修改结果进行总结。

这样能够提高代码审查的效率。


五、让 Agent 自动执行测试

代码生成完成,并不代表功能已经正确。

一个接口可能没有语法错误,但数据库连接失败;一个前端页面可能可以正常显示,但提交数据时接口返回 500。

因此,测试是整个开发流程中非常重要的一环。

1. 检查 Python 语法

对于 FastAPI 项目,可以先执行:

python -m compileall backend/app

该命令会检查 Python 文件的语法,并生成字节码缓存文件。

注意:语法检查通过不代表接口逻辑正确,也不代表所有依赖都能正常导入。

2. 检查后端依赖

进入后端目录:

cd backend

安装项目依赖:

pip install -r requirements.txt

检查关键依赖:

pip show fastapi
pip show sqlalchemy
pip show pymysql

如果项目使用虚拟环境,应在项目对应的虚拟环境中执行。

3. 启动 FastAPI

例如:

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

启动成功后,可以访问:

http://127.0.0.1:8000/docs

通过 Swagger UI 查看和测试接口。

4. 使用 Pytest 编写接口测试

安装测试依赖:

pip install pytest httpx

创建测试文件:

backend/
├── app/
└── tests/
    └── test_articles.py

示例代码:

from fastapi.testclient import TestClient

from app.main import app

client = TestClient(app)


def test_root():
    response = client.get("/")

    assert response.status_code == 200


def test_article_list():
    response = client.get("/api/articles")

    assert response.status_code == 200

    data = response.json()

    assert isinstance(data, dict)

这里假设项目已经实现 / 和 /api/articles 接口,并且文章列表接口返回 JSON 对象。

实际项目中,还应根据真实响应结构检查分页字段、文章数据和权限行为。

运行测试:

pytest -v

如果需要查看更详细的错误信息:

pytest -v -s

5. 让 Agent 自动编写测试

可以使用下面的提示词:

请为刚刚开发的文章管理功能编写自动化测试。

测试范围:

1. 文章创建接口。
2. 文章列表接口。
3. 文章详情接口。
4. 文章编辑接口。
5. 文章删除接口。
6. 分页查询。
7. 标题搜索。
8. 发布状态筛选。
9. 未登录用户访问限制。
10. 普通用户权限限制。

要求:

- 使用 Pytest。
- 使用 FastAPI TestClient。
- 测试数据与正式数据隔离。
- 不要连接生产数据库。
- 每个测试尽量独立。
- 覆盖正常情况和异常情况。

完成后运行测试,
根据实际错误修改代码,并重新执行测试。

需要特别注意:测试环境必须与生产环境隔离。不能为了方便测试而直接清空或修改生产数据库。


六、让 Agent 自动检查前端代码

如果项目使用 Vue 3 + TypeScript,可以让 Agent 检查前端代码。

进入前端目录:

cd frontend

安装依赖:

npm install

执行类型检查:

npx vue-tsc --noEmit

执行生产构建:

npm run build

如果项目已经配置 ESLint,可以执行:

npm run lint

具体命令取决于 package.json 中的脚本配置。

可以让 Agent 使用以下提示词:

请检查刚刚开发的文章管理页面。

重点检查:

1. Vue 组件是否存在语法错误。
2. TypeScript 类型是否正确。
3. API 请求地址是否正确。
4. 请求参数是否与后端接口一致。
5. 分页功能是否正常。
6. 搜索和筛选功能是否正常。
7. 表单验证是否完整。
8. 加载状态和错误提示是否合理。
9. 删除操作是否有二次确认。
10. 是否存在明显的内存泄漏或重复请求问题。

请运行项目已有的类型检查、
代码检查和生产构建命令。

发现问题后先说明原因,再进行修复。

前端构建成功只能说明构建流程通过,不能代替浏览器中的实际交互测试。


七、使用 Git 控制修改风险

在让 Agent 修改项目之前,建议先建立 Git 提交记录。

Git 可以帮助开发者查看文件变化、恢复错误修改,并保留不同开发阶段的代码版本。

1. 检查当前 Git 状态

git status

查看当前分支:

git branch

查看最近提交:

git log --oneline -5

如果项目已经使用 Git,不要随意重新初始化仓库,也不要覆盖原有提交历史。

2. 创建开发分支

例如:

git switch -c feature/article-management

这样可以将新功能与主分支隔离。

3. 修改前创建提交

检查文件变化:

git status

添加需要提交的文件:

git add backend/ frontend/

提交:

git commit -m "chore: save state before article management"

注意:提交前应检查暂存区,避免把 .env、密钥、数据库备份和其他敏感文件提交进去。

4. 检查 Agent 修改了什么

查看工作区差异:

git diff

查看已暂存的差异:

git diff --cached

查看文件变化列表:

git status --short

如果发现 Agent 修改了不应该修改的文件,不要直接覆盖整个项目,可以先检查具体差异,再选择性恢复。

例如:

git restore frontend/src/views/articles/index.vue

注意: git restore 会丢弃指定文件未提交的工作区修改。执行前一定要确认这些修改不需要保留。


八、一个完整的 AI Agent 开发工作流程

将前面的步骤组合起来,可以形成一套相对稳定的开发流程。

<escape>```text
开始开发
│
▼
检查 Git 状态
│
▼
分析项目结构
│
▼
阅读核心代码
│
▼
整理项目约定
│
▼
描述具体开发需求
│
▼
生成开发计划
│
▼
人工检查并确认计划
│
▼
分阶段修改代码
│
▼
执行后端测试
│
▼
执行前端检查与构建
│
▼
检查 Git 差异
│
▼
人工验收
│
▼
提交代码
│
▼
完成开发


这套流程适合已有项目的功能开发、Bug 修复和代码优化。

对于大型项目,还可以进一步将任务拆分为数据库层、业务层、API 层和前端层,避免一次性修改太多内容。

---

## 九、常见问题与注意事项

### 1. Agent 为什么会反复修改同一个问题?

常见原因包括:

- 没有完整理解原有代码。
- 错误信息没有提供完整上下文。
- 修复方案没有明确验收标准。
- 修改一个文件后影响了其他模块。
- 没有执行测试就继续开发。

建议提供完整错误信息,并要求 Agent 先分析原因,再提出修复方案。

不要只说:

```text
这里报错了,修复一下。

更好的描述是:

文章列表页面加载时出现 HTTP 500。

请检查:

1. 浏览器控制台错误。
2. 后端运行日志。
3. 对应 API 路由。
4. 数据库查询语句。
5. 实际返回的数据结构。

先定位根本原因,再进行最小范围修复。
不要修改无关模块。

2. Agent 能否直接操作服务器?

部分开发环境支持通过终端执行命令、访问文件和运行测试。

但对于生产服务器,应设置明确的操作边界。

不建议直接授权 Agent 执行以下操作:

  • 删除数据库或数据表。

  • 执行未经审核的数据库迁移。

  • 修改 SSH 和防火墙配置。

  • 删除网站目录。

  • 重启关键生产服务。

  • 修改系统用户和文件权限。

  • 覆盖生产环境配置。

更合理的方式是在本地或测试服务器完成开发、测试和验证,再通过人工审核部署到生产环境。

3. Agent 修改后项目无法启动怎么办?

建议按照以下顺序排查:

  1. 查看终端中的完整错误信息。

  2. 检查最近修改的文件。

  3. 检查依赖是否发生变化。

  4. 检查环境变量是否缺失。

  5. 检查数据库连接和配置。

  6. 使用 Git 差异定位问题。

  7. 必要时恢复到上一个稳定版本。

不要让 Agent 在没有定位原因的情况下反复重写大量代码。

4. 一个 Agent 是否适合同时开发整个项目?

对于规模较小的项目,可以由一个 Agent 负责整体开发。

但项目规模增大后,建议按模块划分任务,例如:

  • 数据库与数据模型。

  • 后端业务接口。

  • 前端页面。

  • 自动化测试。

  • 部署与运维。

不同模块之间需要统一接口约定和数据结构。不能简单地把任务分给多个 Agent,就认为它们能够自动协调。

5. 如何避免 Agent 泄露项目敏感信息?

在使用自动化开发能力时,需要注意文件和命令的访问权限。

建议:

  • 不向无关环境提供生产密钥。

  • 将 .env 等敏感配置排除在代码提交之外。

  • 测试使用独立数据库账号。

  • 限制 Agent 对生产目录的访问。

  • 审核它准备执行的终端命令。

  • 不随意开放数据库和服务器管理权限。

尤其是具有文件修改和终端执行能力的 Agent,应遵循最小权限原则。


十、总结

AI 编程 Agent 能够帮助开发者完成项目分析、代码修改、测试执行和问题排查,但它的实际效果很大程度上取决于需求是否明确、项目上下文是否完整,以及开发过程是否受到合理控制。

在实际开发中,建议牢记以下原则:

  1. 先理解项目: 不要跳过项目结构和核心代码分析。

  2. 先制定计划: 复杂需求拆分为可以独立验收的小任务。

  3. 限制修改范围: 不允许随意重构无关模块。

  4. 重视自动测试: 代码生成后必须执行测试和构建。

  5. 使用 Git: 保留修改记录,降低开发风险。

  6. 人工验收: 测试通过不代表业务逻辑一定正确。

  7. 保护生产环境: 开发、测试和生产环境应尽量隔离。

真正高效的 AI 辅助开发,并不是让 Agent 一次性写出大量代码,而是让它在明确的目标和约束下,持续完成可以检查、可以测试、可以追踪的开发任务。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。