AI编程协作三步法：从规划到审查，告别代码幻觉

1. 从“AI代码缝合怪”到“高效协作者”的思维转变

最近在社区和团队里，一个现象越来越普遍：大家用AI生成代码时，常常陷入一种“复制-粘贴-调试”的循环。AI给出一大段代码，看起来功能都对，但塞进项目里，要么变量命名混乱、要么逻辑结构诡异、要么引入了项目里根本不存在的依赖。更头疼的是，当你试图让它解释或修改时，它可能会开始“编造”一些不存在的API或方法，让你在排查上浪费大量时间。这感觉就像请了一个想象力过于丰富的实习生，活儿是干了，但留下的烂摊子得自己收拾。

我自己在React项目、Python脚本乃至一些系统配置中，都踩过类似的坑。比如，让AI写一个React组件，它可能把状态逻辑、副作用和渲染模板全揉在一个超长的函数里，完全无视项目已有的Hooks使用规范或组件拆分模式。又或者，让它写一段文件处理的Python代码，它可能会用上一些冷门库，而不是团队约定的标准库方法。

问题的根源，在于我们和AI的协作模式错了。我们习惯于把它当作一个“代码生成器”，丢一个模糊的需求过去，然后指望它吐出一份完美的、可直接运行的解决方案。但AI大模型（无论是Claude Code、Cursor的内置AI，还是其他工具）的本质，是一个基于概率预测的“文本补全专家”。它擅长根据上下文和训练数据，生成“看起来合理”的下一段文本，但它并不真正理解你项目的完整上下文、架构约束和团队规范。

因此，我们需要一套新的方法论，将AI从“天马行空的代码编写者”，转变为“严格遵循蓝图施工的工匠”。这套方法的核心，我称之为“先规划，再胶水”。“规划”是指由我们人类开发者，定义清楚的任务边界、输入输出、接口规范和关键逻辑；“胶水”则是指利用AI强大的代码补全和片段生成能力，去填充那些重复、繁琐但定义明确的实现细节。下面，我就结合React、Python等具体场景，拆解这三个步骤该如何落地。

2. 第一步：深度规划——为AI绘制精确的“施工图纸”

规划是决定成败的第一步。一个模糊的指令（如“写一个登录组件”）必然导致混乱的结果。规划的目标是产出一份机器可读、无歧义的任务规格说明书。这不仅是为了AI，更是为了理清你自己的思路。

2.1 定义清晰的输入与输出接口

这是规划的基石。你必须明确告诉AI，这个函数、组件或模块，它从哪里获取数据，最终要交出什么。

以React组件为例：模糊指令：创建一个用户卡片组件。规划后指令：

请创建一个名为 `UserCard` 的React函数组件。 - **Props（输入）**: - `user`: 对象，必需。结构为 `{ id: number, name: string, avatarUrl: string, role: 'admin' | 'user' | 'guest', lastActive: string (ISO日期格式) }` - `onClick`: 函数，可选。类型为 `(userId: number) => void`。当卡片被点击时调用。 - `compact`: 布尔值，可选，默认为 `false`。为`true`时显示简洁视图。 - **输出/渲染要求**: - 默认视图：显示用户头像（圆形，48x48像素）、姓名（加粗）、角色（标签形式，不同角色配不同颜色：admin红色、user蓝色、guest灰色）、最后活跃时间（格式化为“X分钟前”或“今天 HH:mm”）。 - 简洁视图 (`compact=true`)：仅显示头像（32x32像素）和姓名。 - 点击交互：整个卡片区域可点击，有悬停效果。如果提供了`onClick`，点击时调用它并传入`user.id`。 - **样式要求**：使用CSS Modules，组件文件名为`UserCard.module.css`。样式需包含基本的卡片布局、间距和颜色变量引用（如`var(--color-primary)`）。

以Python数据处理函数为例：模糊指令：写个函数处理数据。规划后指令：

请编写一个Python函数 `clean_and_validate_data`。 - **输入**: - `raw_data_list`: 一个列表，其中每个元素是一个字典。字典预期包含 `'user_id'` (整数或字符串), `'amount'` (数值), `'timestamp'` (字符串，格式为 `'%Y-%m-%d %H:%M:%S'`) 键。 - `config`: 一个可选字典，可包含 `'min_amount'` (默认值0) 和 `'required_keys'` (默认值 `['user_id', 'amount', 'timestamp']`) 键。 - **输出**: - 返回一个元组 `(valid_data, error_reports)`。 - `valid_data`: 列表，包含所有通过清洗和验证的字典。`user_id`统一转为整数，`timestamp`统一转为datetime对象。 - `error_reports`: 列表，每个元素是一个字典，记录无效数据的原始索引和错误原因（如`{'index': 0, 'error': 'missing key: amount'}`）。 - **处理逻辑**: 1. 遍历 `raw_data_list`。 2. 检查每个字典是否包含 `config['required_keys']` 中的所有键。 3. 尝试转换：`user_id` -> `int`, `timestamp` -> `datetime.datetime.strptime(...)`。 4. 检查 `amount` 是否大于等于 `config['min_amount']`。 5. 任何一步失败，则该条数据进入 `error_reports`，不加入 `valid_data`。 6. 所有转换使用try-except捕获异常。

通过如此详细的接口定义，AI生成代码的边界就非常清晰了，它几乎不可能在核心数据流上“编造”内容。

2.2 划定技术栈与依赖边界

明确告诉AI能使用什么，不能使用什么，防止它引入“黑科技”或过时的库。

指令示例：“本项目使用React 18 + TypeScript + Tailwind CSS。请勿使用任何类组件（Class Component）或过时的生命周期方法。状态管理仅使用React内置的useState,useReducer,useContextHooks。副作用处理使用useEffect。对于异步操作，可以使用axios库（已安装），不要使用fetch或jQuery.ajax。” “这个Python脚本运行环境是Python 3.9。数据处理请优先使用pandas(已安装版本1.5.x)，如果操作简单，也可用标准库。禁止使用numpy进行直接数值计算（除非pandas操作内部调用）。文件读写使用标准库pathlib和json。”

2.3 提供关键算法或业务逻辑的伪代码/描述

对于复杂逻辑，AI容易在细节上迷失。将核心逻辑用人类语言或伪代码描述出来，能极大提升生成代码的准确性。

指令示例：“需要实现一个防抖搜索钩子useDebouncedSearch。核心逻辑描述：

1. 接收一个异步搜索函数searchApi和延迟时间delay。
2. 返回一个元组[searchValue, setSearchValue, isLoading, results]。
3. 当用户通过setSearchValue改变搜索词时，启动一个定时器。
4. 如果在delay毫秒内搜索词再次变化，则取消前一个定时器，创建新的。
5. 定时器到期后，才调用searchApi(searchValue)。
6. 调用期间，isLoading设为true。
7. 调用成功，用返回数据更新results；失败，需在控制台错误提示，但results保持不变。
8. 组件卸载时，必须清理所有定时器。”

这种描述将“防抖”和“异步请求”这两个容易出错的概念，转化为了具体的、可执行的步骤序列。

3. 第二步：结构化提示——与AI进行“需求评审会”

有了详细的规划书，下一步就是如何有效地把它“喂”给AI。直接粘贴大段文字可能不是最优解。我们需要结构化提示，引导AI按照我们设定的框架去思考和工作。

3.1 使用角色扮演与上下文设定

在提示开头，为AI设定一个明确的角色和任务背景，这能激活它相关领域的知识。

提示模板：“你是一个经验丰富的前端工程师，正在为一个大型SaaS应用开发可复用的React组件库。请遵循以下TypeScript和React Hooks最佳实践来完成任务。” “你是一个专注于数据质量的Python后端开发工程师。请编写健壮、可读、易于测试的代码来处理可能不干净的数据源。”

3.2 分步骤、分模块地交付任务

不要试图让AI一口气吃成胖子。将大任务拆解成顺序执行的子任务，特别是在使用Cursor的Chat模式或Claude Code的对话中时。

交互流程示例：

1. 第一步（规划确认）：“我将创建一个表单验证钩子。这是它的完整规格：useFormValidation需要...（输入输出接口）。请先复述一遍你的理解，确认关键点。”
2. 第二步（生成骨架）：“根据以上规格，请先只生成这个Hook的TypeScript接口定义（Interface）和函数骨架，包括所有输入参数和返回类型，暂时不写实现。”
3. 第三步（分块实现）：“很好。现在，请首先实现验证规则引擎部分，即validateField函数。规则包括：必填、邮箱格式、最小长度。注意，它应该是纯函数。”
4. 第四步（集成与胶水）：“现在，请将validateField函数集成到useFormValidation的主逻辑中，并添加表单整体验证 (validateForm) 和重置功能 (resetForm)。”
5. 第五步（审查与优化）：“检查生成的代码，确保没有使用任何已废弃的React API，并添加必要的React依赖项数组 (useEffect,useCallback的 deps`)。”

这种分步对话，就像你在和一个初级程序员结对编程，你负责架构和评审，他负责按指令填空，极大降低了AI“自由发挥”导致偏离主线的风险。

3.3 利用现有代码作为上下文

这是Cursor等IDE插件的巨大优势。你可以直接打开一个文件，选中一段代码，然后让AI基于此进行修改或补充。

实操技巧：

• 生成相似代码：选中一个写好的、规范的组件，对AI说：“请参考这个Button组件的代码风格和项目结构，创建一个新的IconButton组件，规格是...”
• 代码转换：选中一段旧的类组件代码，指令：“请将这段React类组件转换为使用函数组件和Hooks的等效实现。”
• 添加功能：在Hook函数内部，将光标放在合适位置，指令：“在这里添加一个防抖逻辑，延迟300毫秒。”

AI会以你选中的代码为最强上下文，生成的代码在风格和模式上会高度一致，这就是最高效的“胶水”。

4. 第三步：批判性审查与迭代——当好AI的“质检员”

AI生成代码后，工作只完成了一半。我们必须以审查真实同事代码的严谨态度来审查AI的产出。审查的重点不是语法（AI语法通常不错），而是逻辑一致性、架构符合度和边界情况。

4.1 逻辑一致性审查：警惕“幻觉”

AI“幻觉”是指它自信地生成错误或不存在的信息。在代码中，常表现为：

1. 编造不存在的API：例如，生成array.findByIndex(...)这样的方法（正确应为array.findIndex）。
2. 错误理解业务逻辑：在条件判断中，将“与”(&&)和“或”(||)关系弄反。
3. 数据流错误：在React中，错误地在渲染函数中直接修改状态，或设定了会产生循环依赖的useEffect。

审查方法：

• 逐行阅读：不要假设AI是对的。特别是条件分支、循环和状态更新处。
• 运行静态检查：立即用TypeScript编译器 (tsc) 或IDE的Linter检查类型错误。AI生成的TypeScript类型有时会不够精确。
• 询问AI解释：对存疑的代码块，可以反问AI：“请解释一下第X行到第Y行的代码逻辑，特别是当输入为null时会怎样？” 这能迫使AI暴露其推理过程，有时它能自己发现矛盾。

4.2 架构与风格审查：融入项目肌理

生成的代码必须在风格上成为项目的一部分，而不是异物。

1. 导入与依赖：检查它是否引入了未声明的依赖，或者使用了项目明确禁止的库/方法。
2. 命名规范：变量名、函数名是否符合项目的命名约定（如驼峰、下划线）？useFormValidation比formValidator更好吗？
3. 错误处理：AI生成的代码往往乐观，缺乏错误处理。检查网络请求、数据解析、文件操作等是否有try-catch或错误状态返回。
4. 性能与副作用：在React中，检查useEffect的依赖数组是否正确，是否可能导致无限渲染。在循环中，是否创建了不必要的函数或对象？

4.3 边界测试与安全审查：填补AI的盲区

AI基于常见模式训练，容易忽略边缘情况和安全漏洞。

必须手动检查的边界：

• 空值/空状态：输入null,undefined, 空字符串'', 空数组[], 空对象{}时，代码会崩溃吗？
• 极端值：数字输入非常大或非常小（包括负数）时，逻辑还成立吗？
• 并发与竞态：对于异步操作（如搜索），快速连续触发时，返回结果的顺序是否正确？是否会以旧的请求结果覆盖新的？
• 安全：生成的SQL片段（如果涉及）是否有注入风险？生成的HTML渲染是否可能包含未转义的用户输入？

一个有效的做法是，直接让AI为生成的代码补充测试用例：“请为上面生成的clean_and_validate_data函数编写3个Pytest测试用例，分别覆盖：1. 正常数据通过；2. 数据缺失关键键；3. 时间戳格式错误。”

如果AI能写出合理的测试，那说明它对自己生成的代码逻辑有较好的把握；如果它写的测试用例暴露了问题，那正好提前修复。

5. 实战案例：用“三步法”重构一个混乱的AI生成组件

假设我们最初用一个模糊指令，让AI生成了一个“用户列表”组件，结果代码冗长、状态混乱、难以维护。现在我们用“三步法”来重做。

原始模糊指令：“用React写一个能显示用户列表、可以搜索和筛选的组件。”

第1步：深度规划我们规划出两个更清晰的组件：

1. UserList：一个展示组件，只负责接收一个users数组和渲染。
2. useUserManagement：一个自定义Hook，负责管理用户数据、搜索词、筛选状态，以及封装数据获取逻辑。

并明确技术栈：React 18, TypeScript, TanStack Query (用于数据获取)，UI组件使用Ant Design。

第2步：结构化提示我们首先与AI协作创建Hook。提示1（角色与骨架）：“你是一个熟悉React Hooks和TanStack Query的前端开发者。请创建一个名为useUserManagement的Hook。它的返回值应包含：{ users, isLoading, searchKeyword, setSearchKeyword, filterRole, setFilterRole, refetch }。请先给出完整的TypeScript接口定义。”提示2（分步实现）：“基于上面的接口，现在实现Hook内部逻辑。假设有一个API函数fetchUsers(params)可以获取用户列表，它接受{ keyword, role }参数。请使用useQueryfrom ‘@tanstack/react-query’ 来管理数据获取，将searchKeyword和filterRole作为查询键的一部分。注意防抖处理搜索词（300ms延迟）。”提示3（生成组件）：“现在，请创建一个UserList展示组件。它接收users,isLoading,onSearchChange,onFilterChange作为props。使用Ant Design的List,Input.Search和Select组件进行布局。”

第3步：批判性审查

• 审查Hook：检查useQuery的查询键[‘users’, searchKeyword, filterRole]是否正确。检查防抖逻辑是否在searchKeyword变化时正确清理定时器。检查是否处理了查询错误状态（isError）。
• 审查组件：检查UserList是否是一个纯函数组件，没有内部状态。检查Ant Design组件的属性绑定是否正确。检查列表为空 (users.length === 0) 和加载中 (isLoading) 的状态是否都有UI展示。
• 测试：手动模拟快速输入搜索词，观察网络请求是否按防抖预期发送。切换筛选条件，观察列表是否更新。

通过这个过程，我们最终得到的是两个职责分离、逻辑清晰、易于测试的模块，而不是一个长达数百行的“巨无霸”组件。AI在这个过程中，完美地扮演了“填空”和“实现细节”的胶水角色，而整体的架构设计和质量控制，始终掌握在我们自己手中。

6. 进阶技巧：将“三步法”融入开发工作流

掌握了基本方法后，可以将其固化到日常开发流程中，形成肌肉记忆。

在Cursor/VS Code中的操作流：

1. 新建文件时：先自己或用AI（通过Cmd+K）生成文件的基础模板和接口定义。
2. 编写复杂函数时：在函数上方用注释写下详细的伪代码和边界条件，然后用AI（选中注释，Cmd+L）生成函数体。
3. 遇到重复模式时：写好一个模式实例（例如一个API Service类的方法），让AI参考它生成其他类似方法。
4. 代码审查时：对AI生成的大段代码，使用“解释代码”（Cmd+L）功能，让它自己阐述逻辑，你边听边找破绽。

针对不同场景的提示词优化：

• 调试与解释：不要问“为什么错了？”，而是问“如果输入是X，这段代码的执行路径是怎样的？第Y行的这个变量值会是什么？”
• 代码优化：指令要具体。“请优化这段循环的性能，重点在时间复杂度。” 比 “让这段代码更快” 好得多。
• 学习新技术：“用三个不同的简单示例，演示ReactuseTransitionHook在哪些场景下使用，并对比有它和没有它时UI响应的区别。”

这套“先规划，再胶水”的方法，其本质是将人类的架构设计、系统思维和批判性审查能力，与AI的海量代码记忆、快速生成和模式匹配能力相结合。它要求我们在前期投入更多思考，但换来的后期调试和维护成本的大幅降低。当你开始习惯为AI绘制精确的图纸时，你会发现，它不再是那个制造混乱的“实习生”，而变成了一个极其高效、听话的“执行伙伴”。你的角色，也从疲于奔命的“纠错员”，升级为了从容不迫的“总工程师”。