1
月
在社区成长 1 月
LEVEL 1
1 XP
## 背景
AI 编程 IDE 的价值不只是“更快地产生代码”。在真实项目里，代码要符合现有架构、通过测试、便于审查，还不能悄悄扩大修改范围。只让模型根据当前文件补全，往往会遇到几类问题：它不了解仓库约定，猜测不存在的接口；生成的修改看似完整，却遗漏调用方和边界条件；或者为了修一个小问题，改动了大量无关文件。
更可靠的做法，是把 AI IDE 当作一个需要明确输入、逐步执行并经过验证的工程协作者。本文以一个常见的 Python 仓库为例，说明如何建立上下文、拆解任务、控制修改范围，并用测试和差异审查形成闭环。其他语言和 IDE 也可以沿用这套方法。
## 原理：上下文、约束与反馈
模型生成结果的质量，通常受三类信息影响：
1. **上下文**：当前文件、相关定义、调用关系、测试和项目文档。上下文不足时，模型只能根据常见模式猜测。
2. **约束**：要解决的问题、不能改变的行为、允许修改的目录、接口和编码规范。约束越可检查，越容易判断结果是否合格。
3. **反馈**：格式检查、静态分析、单元测试和人工审查。模型的首次输出应当视为候选修改，而不是已验证的最终结果。
因此，比较稳定的循环是：定位问题 → 提供必要上下文 → 先制定方案 → 小步修改 → 运行检查 → 审查差异 → 根据失败信息修正。IDE 能帮助完成其中的搜索、编辑和命令执行，但验证责任仍然要落在工程流程上。
## 前置条件
- 在本地拥有项目仓库和正常的开发环境；以下命令均用于自己的项目。
- 仓库至少有 README、依赖说明或测试说明中的一项，最好也有 CI 使用的检查命令。
- 使用版本控制，并在开始前确认工作区状态：
```bash
git status --short
git branch --show-current
```
- 在 IDE 中只开启当前任务需要的仓库或目录。不要为了方便把密码、令牌、客户数据或生产配置放进提示词、聊天记录或不必要的索引范围。
## 分步骤实践
### 第一步：先让 IDE 解释项目，不要马上让它改代码
选择入口文件、相关模块和测试目录，先提出可验证的问题，例如：
> 请根据仓库现有代码，指出用户资料更新接口的入口、调用到的服务层函数、相关测试文件，以及当前字段校验在哪里完成。先只做分析，不修改文件；每个结论请注明文件路径和符号名，不确定的地方明确标出。
这样的提问能减少模型凭经验补全项目结构。检查它给出的路径和符号是否真实存在；若只查看了一个文件，就继续补充调用方或测试文件，而不是立刻授权它重写整个模块。
可以先用命令核对候选位置：
```bash
rg -n "update_profile|ProfileService" src tests
find tests -maxdepth 3 -type f | sort | head -80
```
### 第二步：把需求写成可检查的修改契约
假设任务是“更新资料接口在邮箱为空字符串时应返回校验错误”。不要只说“修复邮箱校验”，而是写清楚输入、预期行为和边界：
- 仅修改资料更新相关逻辑及其测试；
- `email` 缺失时保持现有行为；
- `email` 为 `""` 或只包含空白字符时返回项目已有的校验错误；
- 合法邮箱的处理方式不变；
- 不修改数据库结构和公开接口格式；
- 先增加或调整测试，再实现最小改动。
然后要求 IDE 先给出计划和拟修改文件。计划若涉及无关模块，应先追问原因并收窄范围。对需求尚未明确的地方，不要让模型自行挑一个业务规则；应先查项目文档、现有行为或由负责人确认。
### 第三步：先补测试，再应用小范围修改
先检查仓库已有的测试框架和命名方式，再为边界条件增加测试。以下只是示意，实际断言和 fixture 应沿用项目写法：
```python
def test_update_profile_rejects_blank_email(client):
response = client.patch("/profile", json={"email": " "})
assert response.status_code == 422
```
测试跑通前，先确认它确实覆盖了预期问题，而不是只验证了某个内部实现细节。之后再让 IDE 根据现有校验逻辑做最小修复。提示时可以明确要求：“保留公开接口和其他字段行为，只处理本次定义的空白邮箱情形；完成后列出修改文件和未处理的假设。”
对 IDE 的修改建议逐项应用，不要默认接受整个补丁。重点看：是否新增了不必要的依赖、是否改变了错误码或响应结构、是否把校验放到了不合适的层，以及是否产生了重复逻辑。
### 第四步：分层运行检查，保留失败证据
优先运行最相关的单测，然后再运行格式化、静态检查和更大范围的测试。命令应以仓库文档或 CI 配置为准。例如项目使用 pytest 时，可先执行：
```bash
pytest -q tests/api/test_profile.py
```
如果项目使用 Ruff，再按项目配置运行：
```bash
ruff check src tests
ruff format --check src tests
```
这里的命令不是所有仓库都适用；不要为了照抄而引入项目没有使用的工具。若测试失败，把完整错误、相关测试和修改后的代码位置提供给 IDE，并要求它先解释失败原因，再提出最小修复。不要只输入“修一下”，否则模型可能为了让测试变绿而放宽断言或跳过测试。
### 第五步：用差异审查确认“改对了且只改了该改的”
运行以下命令检查修改范围：
```bash
git diff --check
git diff --stat
git diff
```
审查时至少确认：
- 代码是否符合本仓库的错误处理、日志和命名约定；
- 测试是否覆盖空字符串、空白字符，以及原有合法输入；
- 是否改动了锁文件、生成文件或与任务无关的文件；
- 是否出现硬编码凭据、调试输出、宽泛异常捕获或被关闭的检查；
- 文档和测试描述是否与实际行为一致。
如果 IDE 能显示行级差异，就按差异逐块阅读；对无法解释的改动要求它说明原因。最终提交前再次运行相关测试，并确认工作区中没有混入个人的未提交修改。
## 提示词模板
可以把下面模板放进 IDE 对话框，并按任务填写：
> 目标：……
> 当前行为：……
> 期望行为：……
> 限制：仅修改……；保持……不变；不要新增依赖。
> 验收条件：……（列出测试或可观察结果）
> 请先阅读相关实现和测试，先给出文件路径、计划及不确定项，不要立即编辑。计划确认后再分步修改。修改完成后列出变更、运行过的命令和结果；若有未验证事项，请明确说明。
这类模板的重点不在于措辞复杂，而在于把“目标、边界、验收、报告”都写清楚。
## 风险与注意事项
- **上下文可能不完整**：IDE 的仓库索引、忽略规则或打开文件范围可能导致它漏看关键实现。重要结论应通过搜索和源码核对。
- **测试通过不等于需求正确**：模型也可能生成过窄的测试，只验证自身实现。测试用例应根据业务行为设计，而不是照抄模型给出的断言。
- **不要让模型处理秘密信息**：凭据、生产数据和未授权的第三方代码不应粘贴到外部服务。具体数据处理方式应遵守组织政策和所用工具的配置说明。
- **谨慎使用自动执行和批量改写**：脚本、迁移和删除操作先在本地隔离环境评估影响；执行前看清命令目标与差异，不要让不可信的生成内容直接进入生产环境。
- **保持可回滚性**：按小任务提交或保留清晰的 Git 差异，发生意外时才能快速定位和撤销。
## 常见问题
**问：代码补全经常给出不存在的函数，怎么减少？**
答：在补全前打开定义文件和调用点，明确要求只使用仓库中已存在的接口；对关键符号用搜索核实。不要仅凭补全文本判断接口存在。
**问：让 IDE 一次性完成整个功能，为什么容易返工？**
答：任务跨度过大时，模型需要同时猜测需求、架构和边界，且错误会扩散到多个文件。先拆成测试、实现、文档或调用方调整等可审查的小步，通常更容易定位问题。
**问：应该先写测试还是先改实现？**
答：修复缺陷时，优先添加能够重现缺陷的测试；新功能则先明确验收行为，再让测试和实现围绕同一契约推进。若项目有既定测试流程，应优先遵循项目规范。
**问：AI IDE 生成的代码能否直接合并？**
答：不能仅依据生成来源或测试结果决定。仍需检查需求覆盖、差异范围、依赖和安全影响，并按团队的代码审查与 CI 流程验收。
## 总结
高效使用 AI 编程 IDE，不是把编辑权一次性交出去，而是让它在明确上下文和验收标准下完成可控的小任务。先定位真实代码与测试，再写清修改契约；先验证测试意图，再检查最小补丁；最后用仓库既有的测试和 Git 差异审查确认结果。这样既能利用代码补全和对话式修改节省检索、样板代码与排错时间，也能把模型的猜测限制在可发现、可验证、可回滚的范围内。
AI 编程 IDE 的价值不只是“更快地产生代码”。在真实项目里，代码要符合现有架构、通过测试、便于审查，还不能悄悄扩大修改范围。只让模型根据当前文件补全，往往会遇到几类问题：它不了解仓库约定，猜测不存在的接口；生成的修改看似完整，却遗漏调用方和边界条件；或者为了修一个小问题，改动了大量无关文件。
更可靠的做法，是把 AI IDE 当作一个需要明确输入、逐步执行并经过验证的工程协作者。本文以一个常见的 Python 仓库为例，说明如何建立上下文、拆解任务、控制修改范围，并用测试和差异审查形成闭环。其他语言和 IDE 也可以沿用这套方法。
## 原理：上下文、约束与反馈
模型生成结果的质量，通常受三类信息影响：
1. **上下文**：当前文件、相关定义、调用关系、测试和项目文档。上下文不足时，模型只能根据常见模式猜测。
2. **约束**：要解决的问题、不能改变的行为、允许修改的目录、接口和编码规范。约束越可检查，越容易判断结果是否合格。
3. **反馈**：格式检查、静态分析、单元测试和人工审查。模型的首次输出应当视为候选修改，而不是已验证的最终结果。
因此，比较稳定的循环是：定位问题 → 提供必要上下文 → 先制定方案 → 小步修改 → 运行检查 → 审查差异 → 根据失败信息修正。IDE 能帮助完成其中的搜索、编辑和命令执行，但验证责任仍然要落在工程流程上。
## 前置条件
- 在本地拥有项目仓库和正常的开发环境；以下命令均用于自己的项目。
- 仓库至少有 README、依赖说明或测试说明中的一项，最好也有 CI 使用的检查命令。
- 使用版本控制，并在开始前确认工作区状态：
```bash
git status --short
git branch --show-current
```
- 在 IDE 中只开启当前任务需要的仓库或目录。不要为了方便把密码、令牌、客户数据或生产配置放进提示词、聊天记录或不必要的索引范围。
## 分步骤实践
### 第一步：先让 IDE 解释项目，不要马上让它改代码
选择入口文件、相关模块和测试目录，先提出可验证的问题，例如：
> 请根据仓库现有代码，指出用户资料更新接口的入口、调用到的服务层函数、相关测试文件，以及当前字段校验在哪里完成。先只做分析，不修改文件；每个结论请注明文件路径和符号名，不确定的地方明确标出。
这样的提问能减少模型凭经验补全项目结构。检查它给出的路径和符号是否真实存在；若只查看了一个文件，就继续补充调用方或测试文件，而不是立刻授权它重写整个模块。
可以先用命令核对候选位置：
```bash
rg -n "update_profile|ProfileService" src tests
find tests -maxdepth 3 -type f | sort | head -80
```
### 第二步：把需求写成可检查的修改契约
假设任务是“更新资料接口在邮箱为空字符串时应返回校验错误”。不要只说“修复邮箱校验”，而是写清楚输入、预期行为和边界：
- 仅修改资料更新相关逻辑及其测试；
- `email` 缺失时保持现有行为；
- `email` 为 `""` 或只包含空白字符时返回项目已有的校验错误；
- 合法邮箱的处理方式不变；
- 不修改数据库结构和公开接口格式；
- 先增加或调整测试，再实现最小改动。
然后要求 IDE 先给出计划和拟修改文件。计划若涉及无关模块，应先追问原因并收窄范围。对需求尚未明确的地方，不要让模型自行挑一个业务规则；应先查项目文档、现有行为或由负责人确认。
### 第三步：先补测试，再应用小范围修改
先检查仓库已有的测试框架和命名方式，再为边界条件增加测试。以下只是示意，实际断言和 fixture 应沿用项目写法：
```python
def test_update_profile_rejects_blank_email(client):
response = client.patch("/profile", json={"email": " "})
assert response.status_code == 422
```
测试跑通前，先确认它确实覆盖了预期问题，而不是只验证了某个内部实现细节。之后再让 IDE 根据现有校验逻辑做最小修复。提示时可以明确要求：“保留公开接口和其他字段行为，只处理本次定义的空白邮箱情形；完成后列出修改文件和未处理的假设。”
对 IDE 的修改建议逐项应用，不要默认接受整个补丁。重点看：是否新增了不必要的依赖、是否改变了错误码或响应结构、是否把校验放到了不合适的层，以及是否产生了重复逻辑。
### 第四步：分层运行检查，保留失败证据
优先运行最相关的单测，然后再运行格式化、静态检查和更大范围的测试。命令应以仓库文档或 CI 配置为准。例如项目使用 pytest 时，可先执行：
```bash
pytest -q tests/api/test_profile.py
```
如果项目使用 Ruff，再按项目配置运行：
```bash
ruff check src tests
ruff format --check src tests
```
这里的命令不是所有仓库都适用；不要为了照抄而引入项目没有使用的工具。若测试失败，把完整错误、相关测试和修改后的代码位置提供给 IDE，并要求它先解释失败原因，再提出最小修复。不要只输入“修一下”，否则模型可能为了让测试变绿而放宽断言或跳过测试。
### 第五步：用差异审查确认“改对了且只改了该改的”
运行以下命令检查修改范围：
```bash
git diff --check
git diff --stat
git diff
```
审查时至少确认：
- 代码是否符合本仓库的错误处理、日志和命名约定；
- 测试是否覆盖空字符串、空白字符，以及原有合法输入；
- 是否改动了锁文件、生成文件或与任务无关的文件；
- 是否出现硬编码凭据、调试输出、宽泛异常捕获或被关闭的检查；
- 文档和测试描述是否与实际行为一致。
如果 IDE 能显示行级差异，就按差异逐块阅读；对无法解释的改动要求它说明原因。最终提交前再次运行相关测试，并确认工作区中没有混入个人的未提交修改。
## 提示词模板
可以把下面模板放进 IDE 对话框，并按任务填写：
> 目标：……
> 当前行为：……
> 期望行为：……
> 限制：仅修改……；保持……不变；不要新增依赖。
> 验收条件：……（列出测试或可观察结果）
> 请先阅读相关实现和测试，先给出文件路径、计划及不确定项，不要立即编辑。计划确认后再分步修改。修改完成后列出变更、运行过的命令和结果；若有未验证事项，请明确说明。
这类模板的重点不在于措辞复杂，而在于把“目标、边界、验收、报告”都写清楚。
## 风险与注意事项
- **上下文可能不完整**：IDE 的仓库索引、忽略规则或打开文件范围可能导致它漏看关键实现。重要结论应通过搜索和源码核对。
- **测试通过不等于需求正确**：模型也可能生成过窄的测试，只验证自身实现。测试用例应根据业务行为设计，而不是照抄模型给出的断言。
- **不要让模型处理秘密信息**：凭据、生产数据和未授权的第三方代码不应粘贴到外部服务。具体数据处理方式应遵守组织政策和所用工具的配置说明。
- **谨慎使用自动执行和批量改写**：脚本、迁移和删除操作先在本地隔离环境评估影响；执行前看清命令目标与差异，不要让不可信的生成内容直接进入生产环境。
- **保持可回滚性**：按小任务提交或保留清晰的 Git 差异，发生意外时才能快速定位和撤销。
## 常见问题
**问：代码补全经常给出不存在的函数，怎么减少？**
答：在补全前打开定义文件和调用点，明确要求只使用仓库中已存在的接口；对关键符号用搜索核实。不要仅凭补全文本判断接口存在。
**问：让 IDE 一次性完成整个功能，为什么容易返工？**
答：任务跨度过大时，模型需要同时猜测需求、架构和边界，且错误会扩散到多个文件。先拆成测试、实现、文档或调用方调整等可审查的小步，通常更容易定位问题。
**问：应该先写测试还是先改实现？**
答：修复缺陷时，优先添加能够重现缺陷的测试；新功能则先明确验收行为，再让测试和实现围绕同一契约推进。若项目有既定测试流程，应优先遵循项目规范。
**问：AI IDE 生成的代码能否直接合并？**
答：不能仅依据生成来源或测试结果决定。仍需检查需求覆盖、差异范围、依赖和安全影响，并按团队的代码审查与 CI 流程验收。
## 总结
高效使用 AI 编程 IDE，不是把编辑权一次性交出去，而是让它在明确上下文和验收标准下完成可控的小任务。先定位真实代码与测试，再写清修改契约；先验证测试意图，再检查最小补丁；最后用仓库既有的测试和 Git 差异审查确认结果。这样既能利用代码补全和对话式修改节省检索、样板代码与排错时间，也能把模型的猜测限制在可发现、可验证、可回滚的范围内。