1
月
在社区成长 1 月
LEVEL 1
1 XP
## 背景：AI 生成代码很快，但工程成本可能被推迟
现在不少 AI 编程 IDE 已经可以读取项目文件、生成多个模块、执行终端命令并根据报错继续修改。实际使用中，最常见的问题并不是“模型不会写代码”，而是它在上下文不完整时仍然快速输出，导致接口约定被破坏、异常分支遗漏、测试只覆盖正常路径，甚至为了让测试通过而修改测试本身。
因此，我更建议把 AI IDE 定位为“受约束的结对开发者”，而不是一次性代码生成器。可靠的工作流应该形成一个小闭环：理解仓库 → 明确变更边界 → 制定计划 → 小步实现 → 静态检查 → 自动测试 → 针对失败调试 → 人工审查差异。
下面以一个 Python 服务项目为例，演示如何建立这套流程。方法同样适用于 TypeScript、Java、Go 等项目，具体命令按技术栈替换即可。
## 一、工作原理：AI IDE 到底依赖哪些上下文
AI IDE 生成结果的质量，通常取决于四类信息：
1. 当前对话中的需求与限制，例如“不得修改公开接口”。
2. 已打开、被引用或被索引的代码文件。
3. 仓库中的规则文件、README、类型定义和测试用例。
4. 终端返回的编译、检查、测试和运行日志。
这里有一个容易忽略的点：代码仓库很大，并不等于模型自动理解了整个仓库。即使 IDE 支持项目索引，也应该主动指定关键文件，并要求它先复述现有调用关系。如果 AI 连入口、数据结构和测试位置都没说清楚，就不适合立即进入编码阶段。
一个更稳定的提示结构是：
- 目标：要增加或修复什么能力。
- 范围：允许修改哪些目录和文件。
- 约束：兼容性、性能、依赖和编码规范。
- 验收：哪些命令必须通过，哪些行为必须保持不变。
- 输出方式：先分析和列计划，确认后再改代码。
## 二、前置条件：先把仓库变成可验证环境
开始使用 AI IDE 前，建议确保项目至少具备以下条件：
- 使用 Git 管理，并且工作区处于可识别状态。
- 有明确的依赖锁定文件，例如 `poetry.lock`、`uv.lock`、`package-lock.json` 或 `pnpm-lock.yaml`。
- 有统一的格式化、静态检查和测试命令。
- 测试可以在本地或容器中重复执行。
- 密钥、令牌、生产数据库地址没有进入仓库和提示上下文。
以 Python 项目为例，可以准备如下基础命令：
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
ruff check .
mypy src
pytest -q
Windows PowerShell 激活虚拟环境时可使用：
.\.venv\Scripts\Activate.ps1
在让 AI 修改代码之前，先执行一次完整检查并记录基线。如果原项目本来就有 3 个失败测试，后续不能简单地把全部失败都归因于本次修改。可以使用：
git status --short
pytest -q | tee test-baseline.txt
对于 Node.js 项目，对应命令通常可以是：
npm ci
npm run lint
npm run typecheck
npm test
实际命令应以仓库现有脚本为准，不要让 AI 自行发明一套与 CI 不一致的命令。
## 三、分步骤实践：实现一个带重试规则的 HTTP 客户端
假设现有项目需要为内部 HTTP 客户端增加有限重试：仅对连接超时和指定的 5xx 状态码重试，不重试参数错误，不改变原有返回类型，而且测试中不得访问真实外部服务。
### 第 1 步：让 AI 先阅读，不要立即改代码
可以在 AI IDE 中给出这样的任务：
“请先阅读 `src/client.py`、`src/config.py`、`tests/test_client.py` 和项目配置文件。说明请求入口、异常类型、返回值约定及当前测试方式。暂时不要修改文件。列出实现重试机制需要确认的问题。”
理想输出应该能回答：
- 哪个函数是真正的网络调用入口。
- 当前使用同步还是异步客户端。
- 调用方依赖什么返回类型。
- 现有异常是否被包装。
- 测试使用 mock、fake transport 还是本地测试服务器。
如果回答含糊，应继续补充上下文，而不是马上点击“应用全部修改”。
### 第 2 步：固定变更边界和验收标准
接着给出明确约束：
“只允许修改 `src/client.py`、`src/config.py` 和对应测试。不要新增第三方依赖。最大尝试次数从配置读取，默认值为 3；仅连接超时以及 502、503、504 可重试；400、401、403、404 不重试；最后一次失败保留原有异常类型。测试必须使用 mock 或本地 fake，不访问互联网。先给出文件级修改计划。”
这种提示比“帮我增加重试功能”更有效，因为它把业务规则直接变成了可测试条件。
### 第 3 步：要求小步生成，而不是一次改十几个文件
建议先让 AI 只生成核心逻辑，再补测试。伪代码可以控制在如下结构：
for attempt in range(max_attempts):
try:
response = send_request()
if response.status_code not in retryable_statuses:
return response
except ConnectTimeout:
if attempt == max_attempts - 1:
raise
if attempt < max_attempts - 1:
sleep(calculate_delay(attempt))
审查时重点看三个边界：
1. `max_attempts` 表示总尝试次数，还是首次调用之后的重试次数。
2. 最后一次失败后是否仍然错误地 sleep。
3. 捕获范围是否过宽，例如 `except Exception` 会把编程错误也当成网络问题吞掉。
如果需要退避，测试中不要真的等待数秒。应将 sleep 函数或时间策略设计为可注入对象，或者在测试中 mock 掉等待函数。
### 第 4 步：让 AI 根据测试矩阵补齐用例
不要只写一个“成功请求”测试。可以先要求生成测试矩阵：
- 第一次请求成功：调用 1 次。
- 第一次 503、第二次成功：调用 2 次。
- 连续超时达到上限：抛出原有超时异常。
- 返回 400：立即返回或抛出原有业务异常，不重试。
- 返回 504 后重试：验证调用次数。
- 配置为 1：只尝试一次，不发生等待。
- 非法配置，例如 0 或负数：启动时拒绝，或按项目约定处理。
运行单个测试文件：
pytest tests/test_client.py -q
查看失败详情：
pytest tests/test_client.py -vv --maxfail=1
如果项目有覆盖率要求，可以执行：
pytest --cov=src --cov-report=term-missing
覆盖率不是唯一质量指标。更重要的是关键分支是否有明确断言，例如请求次数、异常类型、是否调用 sleep，以及不可重试状态是否被错误重试。
### 第 5 步：把终端错误交给 AI，但只提供必要日志
测试失败时，不要只说“还是不行”。应提供：
- 执行的完整命令。
- 首个失败堆栈。
- 相关函数和测试代码。
- Python、Node.js 或 JDK 版本。
- 期望行为与实际行为。
例如：
“执行 `pytest tests/test_client.py::test_timeout_keeps_original_exception -vv` 后，期望抛出 `ConnectTimeout`，实际变成了 `RuntimeError`。请沿异常链分析原因，只提出最小修复，不修改测试断言，除非能证明断言与既有接口冲突。”
这一句“不要为了通过而先改测试”很重要。AI 常会把失败测试视为阻碍，而工程上测试更可能是在表达不可破坏的契约。
### 第 6 步：执行分层验证
建议按照从快到慢的顺序验证：
ruff format --check .
ruff check .
mypy src
pytest tests/test_client.py -q
pytest -q
先检查格式和类型，可以更早发现导入错误、未定义名称和返回类型不一致。最后再运行全量测试，确认局部修改没有破坏其他模块。
如果项目使用 pre-commit，可以运行：
pre-commit run --all-files
然后检查改动：
git diff --stat
git diff -- src/client.py src/config.py tests/test_client.py
不要只阅读 AI IDE 的摘要。摘要可能遗漏细节，最终应以 Git diff 和实际执行结果为准。
## 四、把调试从“猜原因”改成“验证假设”
AI 很适合帮助整理调试思路，但不应让它连续盲改。更高效的调试提示可以要求它输出三项内容：
1. 最可能的三个根因，按概率或证据排序。
2. 每个根因对应的最小验证方法。
3. 验证后分别应该采取什么修复。
例如调用次数比预期多一次，可能来自：循环边界错误、底层库自身启用了重试、测试 mock 的副作用列表配置错误。应先打印或断言调用路径，而不是立刻重写重试模块。
可以临时增加结构化日志，但不要记录令牌、完整请求头、密码、Cookie 和敏感业务数据。调试结束后，还要判断临时日志是否应该删除，避免生产环境持续泄漏信息。
## 五、适合放进仓库的 AI 协作规则
如果团队频繁使用 AI IDE，可以在仓库中维护一份简短规则文件，并根据具体工具支持的规则机制进行配置。内容可包含：
- 修改前必须阅读 README、贡献指南和相邻测试。
- 不允许直接修改生成文件、锁文件或数据库迁移，除非任务明确要求。
- 不新增依赖，除非说明必要性、许可证和替代方案。
- 不得读取或输出 `.env`、私钥、访问令牌和生产配置。
- 修复缺陷时先新增可复现测试，再修改实现。
- 保持公开接口兼容；如必须破坏兼容性，需要明确说明迁移方案。
- 完成后列出实际执行过的命令，不得把“建议运行”表述成“已经通过”。
最后一条尤其重要：AI 可以生成命令，但只有终端真实执行并返回结果，才能证明检查通过。
## 六、风险与注意事项
### 1. 上下文泄漏
不要把生产日志、客户数据、密钥文件和内部凭证直接发送给外部模型服务。必要时使用脱敏日志、最小复现项目，或采用符合组织数据策略的部署方式。日志中的 URL 查询参数也可能携带敏感信息。
### 2. 幻觉式 API
AI 可能生成不存在的库方法、错误的参数名，或者混用不同版本文档。遇到不熟悉的 API，应查看项目已安装版本、类型提示和官方文档，并在本地执行最小示例验证。
### 3. 过度修改
一个小需求如果产生几十个文件的差异，通常意味着任务边界失控。可以要求“禁止无关重构”“每一步最多修改三个文件”“先展示计划再应用”。
### 4. 测试被弱化
需要警惕删除断言、扩大异常捕获、随意增加 skip、把精确比较改成模糊比较等做法。测试通过不代表行为正确，有时只是验收标准被降低了。
### 5. 自动执行命令的权限
不建议让 AI IDE 无确认执行删除文件、覆盖配置、发布包、操作云资源或连接生产数据库的命令。命令自动审批应限定在低风险范围，例如格式检查和本地单元测试。涉及安全测试时，只能在授权靶场、本地实验环境或明确的防御场景中进行。
## 七、常见问题
### Q1：应该让 AI 一次生成完整功能吗？
小型、独立且验收标准明确的函数可以一次生成。涉及公开接口、数据库、并发、权限、支付或跨模块状态时，应该拆成计划、实现、测试和审查多个阶段。
### Q2：AI 写了测试，是否还需要人工补充？
需要。AI 往往优先覆盖主路径，人工应重点检查边界值、异常传播、幂等性、并发行为、资源释放和兼容性。还要确认测试没有复制实现逻辑，否则实现和测试可能同时犯同一个错误。
### Q3：代码补全和聊天式生成应该如何选择？
局部、可预测的重复代码适合代码补全，例如类型定义、序列化字段和测试参数。需要理解多个文件、分析报错或设计接口时，更适合使用聊天或代理模式，但应明确文件范围和验收命令。
### Q4：为什么 AI 修改后单元测试通过，CI 仍失败？
常见原因包括运行时版本不同、依赖锁文件未同步、大小写敏感差异、时区或区域设置不同、遗漏格式检查，以及本地存在未提交文件。应对照 CI 配置，在本地复现相同命令和环境变量。
### Q5：如何判断一次 AI 生成是否值得保留？
至少检查四点：是否符合现有架构、是否缩小而不是扩大风险面、是否有可重复验证的测试、后续维护者能否读懂。生成速度不应成为唯一指标。
## 总结
AI IDE 真正的价值，不只是把代码写得更快，而是缩短“提出假设—实现修改—运行验证—定位失败”的反馈周期。要实现这一点，仓库必须有清晰规则，任务必须有边界，测试必须能重复执行，最终结果必须通过真实命令和 Git diff 验证。
我自己的实践原则可以压缩成一句话：让 AI 多读、多计划、小步改、勤验证；把接口契约、安全边界和最终合并决定留在人手里。这样使用 AI 编程工具，速度提升才不会以技术债和线上风险为代价。
现在不少 AI 编程 IDE 已经可以读取项目文件、生成多个模块、执行终端命令并根据报错继续修改。实际使用中，最常见的问题并不是“模型不会写代码”，而是它在上下文不完整时仍然快速输出，导致接口约定被破坏、异常分支遗漏、测试只覆盖正常路径，甚至为了让测试通过而修改测试本身。
因此，我更建议把 AI IDE 定位为“受约束的结对开发者”，而不是一次性代码生成器。可靠的工作流应该形成一个小闭环：理解仓库 → 明确变更边界 → 制定计划 → 小步实现 → 静态检查 → 自动测试 → 针对失败调试 → 人工审查差异。
下面以一个 Python 服务项目为例，演示如何建立这套流程。方法同样适用于 TypeScript、Java、Go 等项目，具体命令按技术栈替换即可。
## 一、工作原理：AI IDE 到底依赖哪些上下文
AI IDE 生成结果的质量，通常取决于四类信息：
1. 当前对话中的需求与限制，例如“不得修改公开接口”。
2. 已打开、被引用或被索引的代码文件。
3. 仓库中的规则文件、README、类型定义和测试用例。
4. 终端返回的编译、检查、测试和运行日志。
这里有一个容易忽略的点：代码仓库很大，并不等于模型自动理解了整个仓库。即使 IDE 支持项目索引，也应该主动指定关键文件，并要求它先复述现有调用关系。如果 AI 连入口、数据结构和测试位置都没说清楚，就不适合立即进入编码阶段。
一个更稳定的提示结构是：
- 目标：要增加或修复什么能力。
- 范围：允许修改哪些目录和文件。
- 约束：兼容性、性能、依赖和编码规范。
- 验收：哪些命令必须通过，哪些行为必须保持不变。
- 输出方式：先分析和列计划，确认后再改代码。
## 二、前置条件：先把仓库变成可验证环境
开始使用 AI IDE 前，建议确保项目至少具备以下条件：
- 使用 Git 管理，并且工作区处于可识别状态。
- 有明确的依赖锁定文件，例如 `poetry.lock`、`uv.lock`、`package-lock.json` 或 `pnpm-lock.yaml`。
- 有统一的格式化、静态检查和测试命令。
- 测试可以在本地或容器中重复执行。
- 密钥、令牌、生产数据库地址没有进入仓库和提示上下文。
以 Python 项目为例，可以准备如下基础命令：
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
ruff check .
mypy src
pytest -q
Windows PowerShell 激活虚拟环境时可使用：
.\.venv\Scripts\Activate.ps1
在让 AI 修改代码之前，先执行一次完整检查并记录基线。如果原项目本来就有 3 个失败测试，后续不能简单地把全部失败都归因于本次修改。可以使用：
git status --short
pytest -q | tee test-baseline.txt
对于 Node.js 项目，对应命令通常可以是：
npm ci
npm run lint
npm run typecheck
npm test
实际命令应以仓库现有脚本为准，不要让 AI 自行发明一套与 CI 不一致的命令。
## 三、分步骤实践：实现一个带重试规则的 HTTP 客户端
假设现有项目需要为内部 HTTP 客户端增加有限重试：仅对连接超时和指定的 5xx 状态码重试，不重试参数错误，不改变原有返回类型，而且测试中不得访问真实外部服务。
### 第 1 步：让 AI 先阅读，不要立即改代码
可以在 AI IDE 中给出这样的任务：
“请先阅读 `src/client.py`、`src/config.py`、`tests/test_client.py` 和项目配置文件。说明请求入口、异常类型、返回值约定及当前测试方式。暂时不要修改文件。列出实现重试机制需要确认的问题。”
理想输出应该能回答：
- 哪个函数是真正的网络调用入口。
- 当前使用同步还是异步客户端。
- 调用方依赖什么返回类型。
- 现有异常是否被包装。
- 测试使用 mock、fake transport 还是本地测试服务器。
如果回答含糊，应继续补充上下文，而不是马上点击“应用全部修改”。
### 第 2 步：固定变更边界和验收标准
接着给出明确约束：
“只允许修改 `src/client.py`、`src/config.py` 和对应测试。不要新增第三方依赖。最大尝试次数从配置读取，默认值为 3；仅连接超时以及 502、503、504 可重试；400、401、403、404 不重试；最后一次失败保留原有异常类型。测试必须使用 mock 或本地 fake，不访问互联网。先给出文件级修改计划。”
这种提示比“帮我增加重试功能”更有效，因为它把业务规则直接变成了可测试条件。
### 第 3 步：要求小步生成，而不是一次改十几个文件
建议先让 AI 只生成核心逻辑，再补测试。伪代码可以控制在如下结构：
for attempt in range(max_attempts):
try:
response = send_request()
if response.status_code not in retryable_statuses:
return response
except ConnectTimeout:
if attempt == max_attempts - 1:
raise
if attempt < max_attempts - 1:
sleep(calculate_delay(attempt))
审查时重点看三个边界：
1. `max_attempts` 表示总尝试次数，还是首次调用之后的重试次数。
2. 最后一次失败后是否仍然错误地 sleep。
3. 捕获范围是否过宽，例如 `except Exception` 会把编程错误也当成网络问题吞掉。
如果需要退避，测试中不要真的等待数秒。应将 sleep 函数或时间策略设计为可注入对象，或者在测试中 mock 掉等待函数。
### 第 4 步：让 AI 根据测试矩阵补齐用例
不要只写一个“成功请求”测试。可以先要求生成测试矩阵：
- 第一次请求成功：调用 1 次。
- 第一次 503、第二次成功：调用 2 次。
- 连续超时达到上限：抛出原有超时异常。
- 返回 400：立即返回或抛出原有业务异常，不重试。
- 返回 504 后重试：验证调用次数。
- 配置为 1：只尝试一次，不发生等待。
- 非法配置，例如 0 或负数：启动时拒绝，或按项目约定处理。
运行单个测试文件：
pytest tests/test_client.py -q
查看失败详情：
pytest tests/test_client.py -vv --maxfail=1
如果项目有覆盖率要求，可以执行：
pytest --cov=src --cov-report=term-missing
覆盖率不是唯一质量指标。更重要的是关键分支是否有明确断言，例如请求次数、异常类型、是否调用 sleep，以及不可重试状态是否被错误重试。
### 第 5 步：把终端错误交给 AI，但只提供必要日志
测试失败时，不要只说“还是不行”。应提供：
- 执行的完整命令。
- 首个失败堆栈。
- 相关函数和测试代码。
- Python、Node.js 或 JDK 版本。
- 期望行为与实际行为。
例如：
“执行 `pytest tests/test_client.py::test_timeout_keeps_original_exception -vv` 后，期望抛出 `ConnectTimeout`，实际变成了 `RuntimeError`。请沿异常链分析原因，只提出最小修复，不修改测试断言，除非能证明断言与既有接口冲突。”
这一句“不要为了通过而先改测试”很重要。AI 常会把失败测试视为阻碍，而工程上测试更可能是在表达不可破坏的契约。
### 第 6 步：执行分层验证
建议按照从快到慢的顺序验证：
ruff format --check .
ruff check .
mypy src
pytest tests/test_client.py -q
pytest -q
先检查格式和类型，可以更早发现导入错误、未定义名称和返回类型不一致。最后再运行全量测试，确认局部修改没有破坏其他模块。
如果项目使用 pre-commit，可以运行：
pre-commit run --all-files
然后检查改动：
git diff --stat
git diff -- src/client.py src/config.py tests/test_client.py
不要只阅读 AI IDE 的摘要。摘要可能遗漏细节，最终应以 Git diff 和实际执行结果为准。
## 四、把调试从“猜原因”改成“验证假设”
AI 很适合帮助整理调试思路，但不应让它连续盲改。更高效的调试提示可以要求它输出三项内容：
1. 最可能的三个根因，按概率或证据排序。
2. 每个根因对应的最小验证方法。
3. 验证后分别应该采取什么修复。
例如调用次数比预期多一次，可能来自：循环边界错误、底层库自身启用了重试、测试 mock 的副作用列表配置错误。应先打印或断言调用路径，而不是立刻重写重试模块。
可以临时增加结构化日志，但不要记录令牌、完整请求头、密码、Cookie 和敏感业务数据。调试结束后，还要判断临时日志是否应该删除，避免生产环境持续泄漏信息。
## 五、适合放进仓库的 AI 协作规则
如果团队频繁使用 AI IDE，可以在仓库中维护一份简短规则文件，并根据具体工具支持的规则机制进行配置。内容可包含：
- 修改前必须阅读 README、贡献指南和相邻测试。
- 不允许直接修改生成文件、锁文件或数据库迁移，除非任务明确要求。
- 不新增依赖，除非说明必要性、许可证和替代方案。
- 不得读取或输出 `.env`、私钥、访问令牌和生产配置。
- 修复缺陷时先新增可复现测试，再修改实现。
- 保持公开接口兼容；如必须破坏兼容性，需要明确说明迁移方案。
- 完成后列出实际执行过的命令，不得把“建议运行”表述成“已经通过”。
最后一条尤其重要：AI 可以生成命令，但只有终端真实执行并返回结果，才能证明检查通过。
## 六、风险与注意事项
### 1. 上下文泄漏
不要把生产日志、客户数据、密钥文件和内部凭证直接发送给外部模型服务。必要时使用脱敏日志、最小复现项目，或采用符合组织数据策略的部署方式。日志中的 URL 查询参数也可能携带敏感信息。
### 2. 幻觉式 API
AI 可能生成不存在的库方法、错误的参数名，或者混用不同版本文档。遇到不熟悉的 API，应查看项目已安装版本、类型提示和官方文档，并在本地执行最小示例验证。
### 3. 过度修改
一个小需求如果产生几十个文件的差异，通常意味着任务边界失控。可以要求“禁止无关重构”“每一步最多修改三个文件”“先展示计划再应用”。
### 4. 测试被弱化
需要警惕删除断言、扩大异常捕获、随意增加 skip、把精确比较改成模糊比较等做法。测试通过不代表行为正确，有时只是验收标准被降低了。
### 5. 自动执行命令的权限
不建议让 AI IDE 无确认执行删除文件、覆盖配置、发布包、操作云资源或连接生产数据库的命令。命令自动审批应限定在低风险范围，例如格式检查和本地单元测试。涉及安全测试时，只能在授权靶场、本地实验环境或明确的防御场景中进行。
## 七、常见问题
### Q1：应该让 AI 一次生成完整功能吗？
小型、独立且验收标准明确的函数可以一次生成。涉及公开接口、数据库、并发、权限、支付或跨模块状态时，应该拆成计划、实现、测试和审查多个阶段。
### Q2：AI 写了测试，是否还需要人工补充？
需要。AI 往往优先覆盖主路径，人工应重点检查边界值、异常传播、幂等性、并发行为、资源释放和兼容性。还要确认测试没有复制实现逻辑，否则实现和测试可能同时犯同一个错误。
### Q3：代码补全和聊天式生成应该如何选择？
局部、可预测的重复代码适合代码补全，例如类型定义、序列化字段和测试参数。需要理解多个文件、分析报错或设计接口时，更适合使用聊天或代理模式，但应明确文件范围和验收命令。
### Q4：为什么 AI 修改后单元测试通过，CI 仍失败？
常见原因包括运行时版本不同、依赖锁文件未同步、大小写敏感差异、时区或区域设置不同、遗漏格式检查，以及本地存在未提交文件。应对照 CI 配置，在本地复现相同命令和环境变量。
### Q5：如何判断一次 AI 生成是否值得保留？
至少检查四点：是否符合现有架构、是否缩小而不是扩大风险面、是否有可重复验证的测试、后续维护者能否读懂。生成速度不应成为唯一指标。
## 总结
AI IDE 真正的价值，不只是把代码写得更快，而是缩短“提出假设—实现修改—运行验证—定位失败”的反馈周期。要实现这一点，仓库必须有清晰规则，任务必须有边界，测试必须能重复执行，最终结果必须通过真实命令和 Git diff 验证。
我自己的实践原则可以压缩成一句话：让 AI 多读、多计划、小步改、勤验证；把接口契约、安全边界和最终合并决定留在人手里。这样使用 AI 编程工具，速度提升才不会以技术债和线上风险为代价。
