1
月
在社区成长 1 月
LEVEL 1
1 XP
一、背景：AI 编程 IDE 的问题不只是“补全准不准”
AI 编程 IDE 已经不再局限于单行代码补全。当前常见能力包括：理解项目文件、生成和修改多个文件、调用终端命令、执行测试、分析报错、连接文档或其他工具，以及根据上下文持续完成任务。真正影响生产效率的，往往不是模型能否写出一段代码，而是它是否能在明确边界内完成一个可验证的工程闭环：理解需求、定位代码、提出方案、实施修改、运行检查、分析失败、修复回归，并保留人可以审查的变更。
如果把 IDE 中的 Agent 当成“会自动改代码的聊天窗口”，很容易遇到几个问题：上下文过长导致重点丢失；一次修改范围过大导致回滚困难；测试失败后反复重试却没有新的证据；工具调用权限过宽，可能误删文件或泄漏配置；补全代码看似合理，但没有经过类型检查、单元测试和边界条件验证。因此，比较可靠的做法是把 AI IDE 设计成一个受约束的工程协作者，而不是完全自动驾驶系统。
二、核心原理：上下文、工具、验证三条链必须闭环
1. 上下文链：先给 IDE 足够但有限的信息。优先提供需求、相关目录、入口文件、接口定义、数据结构和已有测试，而不是把整个仓库无差别塞给模型。上下文应当能够回答“改什么、为什么改、不能改什么”。
2. 工具链：将工具调用划分为只读工具和写入工具。搜索文件、查看 Git diff、读取测试结果属于低风险只读操作；修改文件、安装依赖、执行数据库迁移、删除目录属于高风险操作，应该要求确认，或限制在实验分支和沙箱目录内。
3. 验证链：每次修改都必须有可执行的验收标准。小改动至少运行格式化、静态检查和相关测试；涉及接口、并发、权限或数据格式时，还要补充边界测试。验证失败后，不要让 Agent 盲目重试，而应把错误分类为环境问题、依赖问题、实现问题或测试本身的问题。
这三条链共同构成一个最小闭环：计划—修改—验证—反馈。缺少任何一环，自动化程度越高，潜在返工成本越大。
三、前置条件：先把项目整理成适合 Agent 工作的形状
1. 使用 Git，并在开始任务前创建独立分支：
命令示例：
git checkout -b feature/ai-user-cache
git status
git log -5 --oneline
2. 确保项目能够在没有 AI 参与的情况下完成基础检查。至少准备一个稳定的测试命令，例如：
npm ci
npm run lint
npm test
Python 项目可以使用：
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pytest -q
3. 在仓库根目录提供简短的工程说明，例如 README、CONTRIBUTING 或 AGENTS.md。内容建议包括启动方式、测试命令、目录职责、代码风格、禁止修改的文件、环境变量来源以及提交前检查。
4. 将密钥、生产配置、用户数据和大体积构建产物排除在 Agent 上下文之外。使用 .gitignore、IDE 的工作区排除规则和环境变量模板，避免把真实凭据放入提示词、日志或错误信息。
5. 明确任务验收标准。例如“为缓存查询增加过期时间”不够具体，应该写成“缓存命中时返回缓存值；超过 60 秒重新查询；查询失败时不覆盖已有有效缓存；增加命中、过期和异常三类测试”。
四、分步骤实践：以增加带过期时间的缓存为例
第一步：让 Agent 先调查，不要立即改代码
可以在 IDE 的 Agent 面板输入：
“请先只读分析本项目中用户信息查询的调用链。找出接口入口、缓存实现、数据模型和相关测试。不要修改文件，不要执行写入命令。输出当前行为、可能影响的文件、风险点，以及你建议增加的测试。”
这一步的目的不是获得漂亮的总结，而是检查 Agent 是否理解了真实代码。若它引用了不存在的文件、混淆了测试环境和生产环境，应该先修正上下文，不能直接进入实施阶段。
第二步：把方案压缩成可审查的任务清单
要求 Agent 给出类似下面的计划：
“仅允许修改 src/cache/userCache.ts、src/user/userService.ts 和 test/userCache.test.ts。先定义 TTL 配置，再实现命中和过期判断，保留查询失败时的旧值策略，最后新增三组测试。不得修改数据库结构、依赖版本和公共 API。每完成一个逻辑单元先展示 diff。”
这里的关键是限定修改范围、禁止事项和验证顺序。对于多文件任务，最好让 Agent 每次只处理一个小目标，而不是一次生成几十个文件的“大重构”。
第三步：先生成测试，再实现代码
对于行为明确的需求，可以采用测试驱动方式。让 IDE 先增加失败测试：
“请先只修改测试文件，增加以下用例：缓存未命中时查询一次；TTL 内第二次读取不访问后端；超过 TTL 后重新读取；后端异常时不写入错误结果。执行相关测试并报告失败原因。”
然后再允许修改实现。这样做能防止 Agent 通过修改测试来掩盖实现错误，也能把需求转化为可重复的判定条件。
第四步：分阶段授权工具调用
建议把权限分为四级：
只读级：搜索、读取文件、查看 diff、查看 Git 状态、读取测试输出。
低风险写入级：修改当前任务明确列出的源文件和测试文件。
需确认级：安装依赖、修改配置、生成迁移、批量重命名、执行网络请求。
禁止级：读取真实密钥、访问生产数据库、删除非任务目录、向外部服务上传源码。
在支持工具权限配置的 IDE 中，应尽量使用工作区范围限制和命令白名单。对于终端命令，优先允许 npm test、pytest、go test 等明确命令，避免直接允许带有删除、覆盖或远程执行含义的命令。任何涉及真实数据的调试，都应改用脱敏样本或本地授权靶场。
第五步：建立“失败分类”而不是无限重试
测试失败后，可以要求 Agent 按如下格式处理：
“请不要立即修改代码。先读取完整错误堆栈，判断失败属于：A 环境或依赖；B 测试数据或时区；C 实现逻辑；D 测试预期错误。给出证据、最小修复方案和需要重新运行的命令。只有在我确认后修改文件。”
例如，TypeScript 报错可能来自类型定义版本不一致，不一定是业务代码错误；测试偶发超时可能是共享状态未清理，也不应通过简单增加等待时间掩盖。对于每次修复，都应重新运行最小相关测试，再运行完整检查。
第六步：用 diff 和回归检查收尾
完成修改后，不要只相信 Agent 的总结，至少执行：
git diff --check
git diff --stat
git diff
npm run lint
npm test
git status --short
审查重点包括：是否有无关文件变更；是否新增了不必要的依赖；异常路径是否吞掉错误；缓存是否存在并发竞态；时间单位是否混用秒和毫秒；测试是否真正覆盖失败分支；日志中是否包含令牌、密码或个人数据。
五、代码补全的高效用法：让补全服务于局部决策
代码补全最适合处理局部、结构清晰、可立即验证的任务，例如根据已有接口补齐适配器、生成重复的 DTO 映射、补全测试样板和错误处理分支。不要在函数签名、数据约束和异常策略尚未确定时盲目接受长段补全。
建议采用“短上下文、短接受、快验证”原则：先写出函数签名和关键不变量，再让 IDE 补全内部实现；一次接受一个逻辑块；立即运行类型检查或单个测试。对于生成的正则、并发代码、权限判断、序列化代码和 SQL，必须人工审查，因为这些位置通常存在表面正确但边界错误的实现。
六、调试工作流：从现象到证据
调试时先给 Agent 可复现步骤、输入样例、期望结果、实际结果、运行环境和完整堆栈。不要只说“这里不工作了”。可以使用以下模板：
问题现象：
复现命令：
期望结果：
实际结果：
最近变更：
相关日志：
限制条件：不得扩大修改范围，不得删除失败测试。
让 Agent 先提出三个以内的假设，并为每个假设列出验证方法。只有验证结果支持某个假设时，才进入修复。对于不稳定问题，还应记录复现次数、耗时、并发数和随机种子，避免把偶发性误判为确定性逻辑错误。
七、风险与注意事项
1. 上下文污染：无关文档、历史错误方案和自动生成文件可能误导 Agent。应通过目录范围、忽略规则和任务摘要控制输入。
2. 过度修改：Agent 可能顺手重命名、格式化整个目录或升级依赖。使用独立分支，并要求每一步展示 diff。
3. 虚假完成：生成了测试不代表测试有效，测试通过也不代表覆盖了业务边界。检查断言是否足够严格，避免只验证“不抛异常”。
4. 安全泄漏：不要把令牌、生产日志、客户数据和内部地址复制到对话中。调试安全问题时只使用本地实验、授权靶场或防御性样例，不对真实目标进行扫描、利用或数据访问。
5. 工具调用副作用：安装依赖可能执行安装脚本，迁移命令可能改变数据，网络工具可能把源码发送到外部。高风险动作必须明确确认，并优先在容器、临时数据库或离线环境执行。
八、常见问题
问：应该让 Agent 一次完成整个功能吗？
答：除非功能非常小，否则不建议。先调查，再计划，再按文件或逻辑单元实施，每步都有测试和 diff，失败时更容易定位。
问：为什么补全代码看起来很合理，测试却失败？
答：补全通常利用局部语法和常见模式，未必理解项目的隐含约束，例如时区、事务、并发、权限或历史兼容性。把接口契约和边界测试写清楚，才能减少这种偏差。
问：测试失败后能否让 Agent 自动修到通过？
答：可以在低风险本地项目中有限使用，但应设置最大尝试次数，并要求每次说明新增证据和修改原因。连续重复同一修复通常说明诊断阶段不足。
问：是否应该把整个仓库都加入上下文？
答：通常不应该。优先提供任务相关目录、接口、配置模板和测试；只有在确认存在跨模块影响时再扩大范围。
九、总结
高效使用 AI 编程 IDE 的核心，不是把更多权限交给 Agent，而是建立更短、更清晰、更可验证的反馈回路。先用只读分析确认上下文，再用小步计划限制修改范围；先写可执行的测试和验收标准，再允许 Agent 实施；工具调用按风险分级，失败按证据分类；最后通过 diff、静态检查、单元测试和回归测试确认结果。
当补全、Agent、终端和测试被组织成这套工程流程后，AI IDE 才真正适合进入日常开发：它可以承担搜索、样板代码、局部重构、错误归因和测试生成等重复工作，但关键边界、数据安全、变更审查和最终验收仍然必须保持清晰。可控的自动化，通常比无边界的全自动更快，也更容易长期维护。
AI 编程 IDE 已经不再局限于单行代码补全。当前常见能力包括：理解项目文件、生成和修改多个文件、调用终端命令、执行测试、分析报错、连接文档或其他工具，以及根据上下文持续完成任务。真正影响生产效率的，往往不是模型能否写出一段代码，而是它是否能在明确边界内完成一个可验证的工程闭环：理解需求、定位代码、提出方案、实施修改、运行检查、分析失败、修复回归，并保留人可以审查的变更。
如果把 IDE 中的 Agent 当成“会自动改代码的聊天窗口”，很容易遇到几个问题：上下文过长导致重点丢失；一次修改范围过大导致回滚困难；测试失败后反复重试却没有新的证据；工具调用权限过宽，可能误删文件或泄漏配置；补全代码看似合理，但没有经过类型检查、单元测试和边界条件验证。因此，比较可靠的做法是把 AI IDE 设计成一个受约束的工程协作者，而不是完全自动驾驶系统。
二、核心原理：上下文、工具、验证三条链必须闭环
1. 上下文链：先给 IDE 足够但有限的信息。优先提供需求、相关目录、入口文件、接口定义、数据结构和已有测试，而不是把整个仓库无差别塞给模型。上下文应当能够回答“改什么、为什么改、不能改什么”。
2. 工具链：将工具调用划分为只读工具和写入工具。搜索文件、查看 Git diff、读取测试结果属于低风险只读操作；修改文件、安装依赖、执行数据库迁移、删除目录属于高风险操作，应该要求确认，或限制在实验分支和沙箱目录内。
3. 验证链：每次修改都必须有可执行的验收标准。小改动至少运行格式化、静态检查和相关测试；涉及接口、并发、权限或数据格式时，还要补充边界测试。验证失败后，不要让 Agent 盲目重试，而应把错误分类为环境问题、依赖问题、实现问题或测试本身的问题。
这三条链共同构成一个最小闭环：计划—修改—验证—反馈。缺少任何一环，自动化程度越高，潜在返工成本越大。
三、前置条件：先把项目整理成适合 Agent 工作的形状
1. 使用 Git，并在开始任务前创建独立分支：
命令示例：
git checkout -b feature/ai-user-cache
git status
git log -5 --oneline
2. 确保项目能够在没有 AI 参与的情况下完成基础检查。至少准备一个稳定的测试命令，例如：
npm ci
npm run lint
npm test
Python 项目可以使用：
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pytest -q
3. 在仓库根目录提供简短的工程说明，例如 README、CONTRIBUTING 或 AGENTS.md。内容建议包括启动方式、测试命令、目录职责、代码风格、禁止修改的文件、环境变量来源以及提交前检查。
4. 将密钥、生产配置、用户数据和大体积构建产物排除在 Agent 上下文之外。使用 .gitignore、IDE 的工作区排除规则和环境变量模板，避免把真实凭据放入提示词、日志或错误信息。
5. 明确任务验收标准。例如“为缓存查询增加过期时间”不够具体，应该写成“缓存命中时返回缓存值；超过 60 秒重新查询；查询失败时不覆盖已有有效缓存；增加命中、过期和异常三类测试”。
四、分步骤实践：以增加带过期时间的缓存为例
第一步：让 Agent 先调查，不要立即改代码
可以在 IDE 的 Agent 面板输入：
“请先只读分析本项目中用户信息查询的调用链。找出接口入口、缓存实现、数据模型和相关测试。不要修改文件，不要执行写入命令。输出当前行为、可能影响的文件、风险点，以及你建议增加的测试。”
这一步的目的不是获得漂亮的总结，而是检查 Agent 是否理解了真实代码。若它引用了不存在的文件、混淆了测试环境和生产环境，应该先修正上下文，不能直接进入实施阶段。
第二步：把方案压缩成可审查的任务清单
要求 Agent 给出类似下面的计划：
“仅允许修改 src/cache/userCache.ts、src/user/userService.ts 和 test/userCache.test.ts。先定义 TTL 配置，再实现命中和过期判断，保留查询失败时的旧值策略，最后新增三组测试。不得修改数据库结构、依赖版本和公共 API。每完成一个逻辑单元先展示 diff。”
这里的关键是限定修改范围、禁止事项和验证顺序。对于多文件任务，最好让 Agent 每次只处理一个小目标，而不是一次生成几十个文件的“大重构”。
第三步：先生成测试，再实现代码
对于行为明确的需求，可以采用测试驱动方式。让 IDE 先增加失败测试：
“请先只修改测试文件，增加以下用例：缓存未命中时查询一次；TTL 内第二次读取不访问后端；超过 TTL 后重新读取；后端异常时不写入错误结果。执行相关测试并报告失败原因。”
然后再允许修改实现。这样做能防止 Agent 通过修改测试来掩盖实现错误，也能把需求转化为可重复的判定条件。
第四步：分阶段授权工具调用
建议把权限分为四级：
只读级：搜索、读取文件、查看 diff、查看 Git 状态、读取测试输出。
低风险写入级：修改当前任务明确列出的源文件和测试文件。
需确认级：安装依赖、修改配置、生成迁移、批量重命名、执行网络请求。
禁止级：读取真实密钥、访问生产数据库、删除非任务目录、向外部服务上传源码。
在支持工具权限配置的 IDE 中，应尽量使用工作区范围限制和命令白名单。对于终端命令，优先允许 npm test、pytest、go test 等明确命令，避免直接允许带有删除、覆盖或远程执行含义的命令。任何涉及真实数据的调试，都应改用脱敏样本或本地授权靶场。
第五步：建立“失败分类”而不是无限重试
测试失败后，可以要求 Agent 按如下格式处理：
“请不要立即修改代码。先读取完整错误堆栈，判断失败属于：A 环境或依赖；B 测试数据或时区；C 实现逻辑；D 测试预期错误。给出证据、最小修复方案和需要重新运行的命令。只有在我确认后修改文件。”
例如，TypeScript 报错可能来自类型定义版本不一致，不一定是业务代码错误；测试偶发超时可能是共享状态未清理，也不应通过简单增加等待时间掩盖。对于每次修复，都应重新运行最小相关测试，再运行完整检查。
第六步：用 diff 和回归检查收尾
完成修改后，不要只相信 Agent 的总结，至少执行：
git diff --check
git diff --stat
git diff
npm run lint
npm test
git status --short
审查重点包括：是否有无关文件变更；是否新增了不必要的依赖；异常路径是否吞掉错误；缓存是否存在并发竞态；时间单位是否混用秒和毫秒；测试是否真正覆盖失败分支；日志中是否包含令牌、密码或个人数据。
五、代码补全的高效用法：让补全服务于局部决策
代码补全最适合处理局部、结构清晰、可立即验证的任务，例如根据已有接口补齐适配器、生成重复的 DTO 映射、补全测试样板和错误处理分支。不要在函数签名、数据约束和异常策略尚未确定时盲目接受长段补全。
建议采用“短上下文、短接受、快验证”原则：先写出函数签名和关键不变量，再让 IDE 补全内部实现；一次接受一个逻辑块；立即运行类型检查或单个测试。对于生成的正则、并发代码、权限判断、序列化代码和 SQL，必须人工审查，因为这些位置通常存在表面正确但边界错误的实现。
六、调试工作流：从现象到证据
调试时先给 Agent 可复现步骤、输入样例、期望结果、实际结果、运行环境和完整堆栈。不要只说“这里不工作了”。可以使用以下模板：
问题现象：
复现命令：
期望结果：
实际结果：
最近变更：
相关日志：
限制条件：不得扩大修改范围，不得删除失败测试。
让 Agent 先提出三个以内的假设，并为每个假设列出验证方法。只有验证结果支持某个假设时，才进入修复。对于不稳定问题，还应记录复现次数、耗时、并发数和随机种子，避免把偶发性误判为确定性逻辑错误。
七、风险与注意事项
1. 上下文污染：无关文档、历史错误方案和自动生成文件可能误导 Agent。应通过目录范围、忽略规则和任务摘要控制输入。
2. 过度修改：Agent 可能顺手重命名、格式化整个目录或升级依赖。使用独立分支，并要求每一步展示 diff。
3. 虚假完成：生成了测试不代表测试有效，测试通过也不代表覆盖了业务边界。检查断言是否足够严格，避免只验证“不抛异常”。
4. 安全泄漏：不要把令牌、生产日志、客户数据和内部地址复制到对话中。调试安全问题时只使用本地实验、授权靶场或防御性样例，不对真实目标进行扫描、利用或数据访问。
5. 工具调用副作用：安装依赖可能执行安装脚本，迁移命令可能改变数据，网络工具可能把源码发送到外部。高风险动作必须明确确认，并优先在容器、临时数据库或离线环境执行。
八、常见问题
问：应该让 Agent 一次完成整个功能吗？
答：除非功能非常小，否则不建议。先调查，再计划，再按文件或逻辑单元实施，每步都有测试和 diff，失败时更容易定位。
问：为什么补全代码看起来很合理，测试却失败？
答：补全通常利用局部语法和常见模式，未必理解项目的隐含约束，例如时区、事务、并发、权限或历史兼容性。把接口契约和边界测试写清楚，才能减少这种偏差。
问：测试失败后能否让 Agent 自动修到通过？
答：可以在低风险本地项目中有限使用，但应设置最大尝试次数，并要求每次说明新增证据和修改原因。连续重复同一修复通常说明诊断阶段不足。
问：是否应该把整个仓库都加入上下文？
答：通常不应该。优先提供任务相关目录、接口、配置模板和测试；只有在确认存在跨模块影响时再扩大范围。
九、总结
高效使用 AI 编程 IDE 的核心，不是把更多权限交给 Agent，而是建立更短、更清晰、更可验证的反馈回路。先用只读分析确认上下文，再用小步计划限制修改范围；先写可执行的测试和验收标准，再允许 Agent 实施；工具调用按风险分级，失败按证据分类；最后通过 diff、静态检查、单元测试和回归测试确认结果。
当补全、Agent、终端和测试被组织成这套工程流程后，AI IDE 才真正适合进入日常开发：它可以承担搜索、样板代码、局部重构、错误归因和测试生成等重复工作，但关键边界、数据安全、变更审查和最终验收仍然必须保持清晰。可控的自动化，通常比无边界的全自动更快，也更容易长期维护。