AI 协作开发记录

一、启动阶段：先学习，后动手 (丰富版)

启动阶段的核心目标是同步上下文，确保 AI 和你在同一个“频道”上思考。直接命令 AI 写代码，就像让一个不熟悉厨房的厨师直接做菜，结果往往是灾难性的。

1.1 用「探索模式」开局：从“命令”到“请教”

经验：直接让 AI 写代码往往会导致方向性错误和大量不符合项目规范的代码。在动手前，先让 AI “学习”现有代码、数据结构和项目规范。

有效做法：

✅ 分析代码结构：“在开始写代码前，我们先学习一下 src/utils 目录下的文件结构，分析一下各个工具函数的功能和模块依赖关系。”
✅ 理解数据模型：“这是我们的核心数据结构 ProjectData 的 TypeScript 定义，请先阅读并解释每个字段的用途，特别是 scenes 和 tracks 的嵌套关系。”
✅ 学习 API 规范：“我需要你实现一个新的 API 端点。请先分析一下 routes/user.js 中现有 API 的路由定义、请求/响应格式和错误处理方式，并总结出规范。”
✅ 掌握项目目标：“我们正在开发一个视频剪辑工具。在开始之前，请阅读我们的产品需求文档（PRD），并用你的话总结一下核心功能、目标用户和关键技术挑战。”

更多反例：

❌ 模糊的指令：“帮我写一个用户登录功能。”
- 后果：AI 可能会使用它最熟悉的 JWT + Passport.js 方案，但这可能与你项目中已有的 session-based 认证完全不符，导致代码无法集成。
❌ 直接的功能请求：“在 main.js 里加一个导出视频的函数。”
- 后果：AI 不知道你项目中已经有了 exportManager.js 模块专门处理导出任务，它会在 main.js 中重复造轮子，破坏了代码的模块化设计。
❌ 无上下文的算法实现：“写一个快速排序算法。”
- 后果：AI 写出了一个通用的快排，但你的需求是针对一个包含复杂对象的数组、按特定属性排序，并且需要是稳定排序。通用算法完全不适用。

原理：AI 在“学习阶段”会构建一个关于项目的心智模型。这一步投入的时间，会在后续开发中以“减少返工”、“提高代码质量”和“减少沟通成本”的形式十倍地回报给你。

1.2 上下文供给：代码片段、截图、文档三位一体

经验：AI 的记忆是有限且易失的。高效的上下文传递是成功的关键。纯文字描述在复杂场景下几乎必然失败。

有效做法：

✅ 代码片段 + 意图：“我需要修改这个函数 calculateLayout 的逻辑。这是它现在的代码：[粘贴代码片段]。目标是让它在计算时能额外考虑 padding 属性。”
✅ 截图 + 文字：“bg_id 的值需要从这里获取。如图所示，SceneConfig 对象中已经有了这个值，请看看能否直接调用获取？” + [代码截图]
✅ 文档 + 总结：“这是我们组件库的 Button 组件文档 [粘贴文档链接或内容]。请总结一下它的 props，特别是 variant 和 size 有哪些可选值和默认值。”

更多反例：

❌ 指代不明：“把那个背景 ID 改一下。”
- 后果：AI 不知道“那个”是哪个。是用户配置里的 bg_id？是场景数据里的 background_id？还是 CSS 里的 #background-id？它只能猜测。
❌ 口语化描述 UI：“就是那个在右上角的红色按钮，点一下应该弹出一个框。”
- 后果：AI 无法将“右上角的红色按钮”精确映射到代码中的 Header.vue 里的 <el-button type="danger">。它可能会去修改一个完全不相关的组件。
❌ 描述数据流而非结构：“数据先从 A 过来，然后处理一下给 B，B 再存起来。”
- 后果：AI 不清楚数据的具体形态。是 { "id": 1, "value": "text" } 还是 [1, "text"]？数据结构的不明确会导致后续所有处理逻辑的错误。

原理：精确的上下文是消除歧义的唯一方法。代码片段、截图和文档就像是给 AI 的“GPS 坐标”，让它能精确地定位到问题所在，而不是在大海里捞针。

二、需求沟通：消除歧义的关键技巧

2.1 给出具体数值映射，而非抽象描述

经验：抽象描述（如"改坐标的Z值"）会导致 AI 猜测具体实现方式。

有效做法：

❌ "人物大小通过改坐标的Z值实现"
✅ "人物大小：小→Z为0，中→Z为-300，大→Z为-500"

❌ "不同位置有不同的坐标"
✅ "偏左: x=-200, y=0; 居中: x=0, y=0; 偏右: x=200, y=0"

原理：精确的 属性名 = 具体值 映射表不留任何解读空间。这是避免返工的最有效手段之一。

2.2 有歧义的术语，必须配截图

经验：某些术语在不同语境下有不同含义。例如"镜头位置"——AI 会自然联想到 Camera 组件，但实际上可能指的是完全不同的 UI 元素。

实际案例：

👤 "补充两个配置项，对应 '镜头位置' 和 '背景缩放'"
🤖 → AI 理解为修改 Camera 子轨道的属性 ❌

👤 "不是 Camera 子轨道，是如下的'人镜'对象" + [截图指出具体控件]
🤖 → AI 修正理解 ✅

规则：凡是涉及 UI 元素的描述，一律附截图。 文字描述 UI 的失败率极高。

2.3 双向规则描述：正常 + 异常都要说

经验：只描述一个方向的规则（如"溢出就延长"），AI 可能遗漏另一个方向的处理。

有效做法：

❌ "如果时间溢出就延长时长"
✅ "如果 A 的结束时间在 B 之前 → 延长 A；反之，如果 A 超过了 B → 延长 B 并级联调整后续"

原理：AI 倾向于只实现你明确提到的逻辑。双向描述确保正常路径和异常路径都被覆盖。

三、验证阶段：发现隐藏错误的方法

3.1 反向确认法（最重要的技巧，丰富版）

核心理念：人类的思维是发散和联想的，而 AI 的“思维”是基于概率和模式匹配的。我们认为理所当然的上下文，AI 可能完全没有get到。与其盲目相信 AI “听懂了”，不如让它把“听懂的内容”复述出来，由我们来做最终的判断。这是一种成本最低的“认知同步”手段。

经验：与其自己单向描述需求让 AI 执行，不如让 AI 先说出它的理解，由你来判断对错。

有效做法（更多场景化案例）：

在实现复杂逻辑前，要求 AI 预演
- ✅ 提问方式：“在写代码之前，请用自然语言描述一下你将要实现的步骤。比如，当用户点击‘保存’按钮后，数据会经过哪些处理，最终存储到哪里？”
- 反例：直接说“实现保存功能”，结果 AI 可能漏掉了数据校验、状态更新、API 调用失败回滚等关键步骤。
在修改现有代码时，确认影响范围
- ✅ 提问方式：“我需要修改 User 这个数据模型，增加一个 level 字段。请告诉我，这个改动可能会影响到哪些文件和函数？列一个清单我来检查。”
- 反例：“给 User 模型加个 level 字段”，结果 AI 只改了模型定义，却漏掉了所有使用到 User 模型的查询、更新和前端展示部分，导致整个系统多处报错。
在进行数据处理时，核对数据模型
- ✅ 提问方式：“你理解的数据模型是什么样的？请用 Markdown 表格或者 JSON 格式画出来，我来核对一下字段名、数据类型和嵌套关系是否正确。”
- 反例：“把这些数据导入数据库”，结果 AI 可能把 user_id 理解成了字符串而非数字，或者把扁平结构错误地理解成了嵌套结构。
在开始一个新任务时，让 AI 总结目标
- ✅ 提问方式：“我们这次的目标是重构支付模块。根据我们刚才的讨论，请用你的话总结一下这次重构要达成的 3 个主要目标和 2 个禁止改动的地方。”
- 反例：滔滔不绝讲了半小时需求，然后说“开始吧”，结果 AI 可能抓错了重点，把次要的 UI 优化当作了核心任务。

为什么这个方法如此有效：

暴露隐藏的假设：AI 可能会有一些基于它训练数据的“默认假设”（例如：ID 都是自增整数、所有 API 都遵循 RESTful 风格）。反向确认能将这些隐藏的、可能错误的假设暴露出来。
成本前置，收益最大化：在沟通阶段花 5 分钟进行反向确认，可能避免后续数小时的编码、测试和修复工作。这是成本最低的“单元测试”。
打破“惯性思维”：当你发现 AI 反复犯同一个错误时，通常是它的底层“心智模型”出了问题。强制它复述新的、正确的模型，是打破这种惯性的最有效方法。

一个典型的成功案例：

你：“我们需要实现一个分段上传功能。”
AI：（直接开始写代码…）❌

你：“停。在开始前，先告诉我你打算怎么实现这个分段上传，画一个简单的流程图。”
AI：“好的。我的理解是：

前端将文件切片。

前端为每个切片调用一次上传接口 POST /upload_chunk。

所有切片上传完毕后，前端调用合并接口 POST /merge_chunks。”

你：“你的理解基本正确，但漏了一点：我们的系统要求每次上传切片时，都要在请求头里带上一个全局的 transaction_id，用于服务端追踪整个上传过程。请把这一点加到你的流程里再复述一遍。”
AI：“收到。修正后的流程是…” ✅

通过这次简单的反向确认，你成功地在代码编写前就发现并修复了一个会导致功能异常的关键逻辑遗漏。

3.2 渐进式确认：一次只确认一个概念

经验：一次性抛出大量信息，AI 容易遗漏或混淆其中的关键点。

有效做法：

第一步：✅ "确认一下：同一个场景下可能有多个不同角色？"
         🤖 "是的，理解了"

第二步：✅ "多个角色在时间轴上串行排列，中间有间隔，对吗？"
         🤖 "是的"

第三步：✅ "间隔默认为 0.5 秒，加到配置里"

对比：

❌ "同一场景有多个角色，串行排列，间隔0.5秒，每个角色有独立的位置大小动作模糊配置，最后一个角色的最后一帧要对齐到场景结束..."

原理：渐进式确认让 AI 逐步构建正确的心智模型，每一步都有校验机会。

处理“渐进式确认”与“Token溢出”矛盾的最佳实践

1. 主动分块，而非被动总结（您的“分步讨论”思路的延伸）

这是最重要的一步。与其等到 Token 溢出时让 AI 被动地总结，不如我们从一开始就主动控制对话的“事务边界”。

做法：在开始一个复杂话题时，先和 AI 约定好一个“议程”。
提示词示例：
- "接下来我们要讨论一个新的功能模块，它比较复杂，包含 A、B、C 三个部分。为了避免信息过载和遗忘，我们一个一个来。首先，我们只讨论 A 部分的实现，完全搞定之后，我会说‘A部分确认完毕’，然后我们再进入 B 部分。你同意吗？"
优势：
- 你掌握主导权：由你来决定何时“提交”一个阶段的讨论，而不是由 Token 限制来决定。
- 上下文聚焦：在讨论 A 部分时，AI 的全部“注意力”（上下文窗口）都集中在 A 上，理解更深入，细节更准确。

2. “滚动上下文” + “外部记忆”（您的“总结成md”思路的实践）

将“主动分块”与“外部记忆”结合，形成一个强大的工作流。

做法：每完成一个“议程块”（比如 A 部分），就让 AI 生成一个该块的“最终结论文档”，然后你将其存入 Obsidian 笔记。在进入下一块讨论时，将这个“结论”作为新的、高度浓缩的上下文提供给 AI。
工作流示例：
1. 讨论 A 部分：深入讨论所有细节。
2. 生成 A 的“记忆”：
  - "好的，A 部分我们已经讨论清楚了。现在，请将关于 A 部分的所有最终结论、数据结构和关键决策，整理成一个独立的 Markdown 文档。确保包含所有细节，因为这将作为我们后续工作的唯一参考依据。"
3. 存入 Obsidian：你将生成的 Markdown 存入笔记，并进行人工核对和修正（这是关键！）。
4. 开启 B 部分：开始一个新的对话（或者在旧对话中明确告知 AI 忽略之前的细节），然后提供 A 的“记忆”作为上下文。
  - "现在我们开始讨论 B 部分。B 部分需要与 A 部分进行交互。这是我们已经确定的 A 部分的最终规范 [粘贴 A 部分的 Markdown 结论]，请基于这个规范来设计 B。"
优势：
- 规避 Token 限制：每个新阶段都从一个清爽的上下文开始。
- 建立“真理之源”：Obsidian 中的笔记成为不可变的、经过你确认的“真理”，而不是依赖 AI 易失的、模糊的内部记忆。
- 降低总结损失：总结的范围从“全部对话历史”缩小到“一个独立的议程块”，信息密度更高，损失更小。

3. 使用“角色扮演”和“元指令”来强化 AI 的行为模式

在对话开始时，就给 AI 设定好规则。

提示词示例：
- "在我们的合作中，请扮演一个严谨的软件工程师。当任何一个话题的讨论内容变得过长时，请主动提醒我：‘当前话题信息量较大，建议先进行阶段性总结，以免超出上下文限制。’"
优势：
- 将一部分“流程管理”的认知负担转移给 AI。
- 让 AI 成为你流程中的一个主动参与者，而不仅仅是被动的执行者。

总结与对比

方法	做法	优点	缺点
被动总结（不推荐）	等 Token 快满了，让 AI 总结之前的对话。	简单，不需要提前规划。	信息丢失严重，总结质量不可控，容易丢失关键细节。
主动分块	事先规划好议程，一次只讨论一个块。	上下文聚焦，理解深入，你掌握主导权。	需要前期投入少量时间进行规划。
外部记忆（推荐）	将每个块的结论存入 Obsidian，作为后续的上下文。	建立真理之源，彻底解决 Token 限制，信息可靠。	操作步骤略多，但长期收益巨大。
元指令	让 AI 主动提醒你需要总结。	减轻你的心智负担，让 AI 辅助流程管理。	AI 可能不会 100% 遵守指令，仍需你主导。

我的最终建议是：

采用 “主动分块” + “外部记忆” 的组合策略。这是目前在有限的上下文窗口内进行大规模、高精度 AI 协作的最可靠方法。虽然前期需要一些规划和“纪律”，但它能从根本上解决信息丢失和理解偏差的问题，将返工率降到最低。您的想法完全正确，将其流程化、系统化，就能发挥出最大的威力。

3.3 对照信息：提供"预期 vs 实际"

经验：报告问题时，同时提供"应该是什么"和"实际是什么"，能让 AI 快速定位根因。

有效做法：

❌ "这个 ID 找不到"
✅ "表里填的 11027 在编辑器里能正常找到，但生成器中返回了空路径"

原理：对照信息直接缩小了排查范围——问题一定出在"编辑器能做到但生成器做不到"的那个差异点上。

四、纠错阶段：当 AI 理解错误时怎么做

4.1 数据模型假设错误 = 最大的返工风险

经验：如果 AI 对数据模型的基本假设是错的（比如"属性属于哪一行"），后续所有代码都会建立在错误基础上。

信号识别：当你发现 AI 的输出在"小细节上对，但大方向上偏"时，很可能是数据模型假设有误。

纠正方式：

✅ 用表格对比旧假设和实际情况：

| 维度     | AI的假设           | 实际情况           |
|----------|-------------------|--------------------|
| 属性归属 | 属性在场景行上      | 属性在对话行上 ✅   |
| 数量关系 | 一场景 = 一角色    | 一场景 = 多角色 ✅  |

原理：AI 对已有理解有"惯性"，单纯的文字纠正可能不够。结构化对比表 + 截图 是最有效的纠正方式。

4.2 不要只说"你错了"，要说"错在哪、应该是什么"

经验：模糊的否定会让 AI 在错误方向上继续尝试。

❌ "你理解的不对"
✅ "你理解的不对，不是改变 Camera 子轨道的属性，而是改变'人镜'Widget 的 position。具体来说是..." + [截图]

五、流程管理：让协作更高效的习惯

5.1 请求多方案，而非接受第一个

有效做法：

✅ "考虑在 Tools 下创建一个新目录... 你有什么看法？"
🤖 → 提供了三个方案（A/B/C），各有优劣

✅ "我建议用方案C，因为..."

原理："你有什么看法？" 让 AI 进入分析模式，会主动提供多个选项和权衡。直接给指令则只会得到一个结果。

5.2 阶段性整理 + 核对

有效做法：

✅ "先将所有讨论整理成一个总览文档，我需要在你整理完后进一步核对其中的细节"

为什么有效：

汇总分散信息，暴露遗漏和矛盾
明确告知"后续会核对"，AI 会更谨慎
给双方一个同步理解的检查点

5.3 交互式验证优于大批量实现

经验：一次性实现全部功能后再测试，发现问题的修复成本远高于逐步验证。

建议：

每完成一个模块，立即验证输出是否正确
关键算法先用日志输出中间结果，确认正确后再继续
保留历史输出作为基准（baseline），代码变更后做对比

5.4 复杂逻辑用流程图沟通

经验：涉及条件分支、时间轴、级联影响等复杂逻辑时，纯文字沟通失败率极高。

建议：

在实现前要求 AI 先画 Mermaid 流程图，确认理解一致
用具体数值举例（如"角色A 在 0~2s，间隔 0.5s，角色B 在 2.5~4s"）
流程图中标注关键变量名和判断条件

六、常见失败模式与对策

失败模式	表现	对策
抽象描述	“改坐标的Z值” → AI 猜错属性	给出 `属性名=具体值` 的映射
有歧义的术语	“镜头位置” → AI 理解为 Camera	截图指出具体 UI 元素
一次性大量信息	10 条需求一起说 → AI 遗漏关键点	分步确认，每步验证
只描述单方向	“溢出就延长” → AI 不处理正常情况	同时说明正常和异常路径
假设 AI 已理解	不做反向确认 → 发现时已大量返工	关键逻辑先让 AI 复述
数据模型偏差	AI 的基础假设与实际不符	表格对比 + 截图纠正
指令惯性	纠正后 AI 仍按旧理解行事	多次确认 + 要求 AI 用新模型复述

七、提示词速查表

开局

"在开始写代码前，我们先学习一下 XX 的结构..." → 进入分析模式
"你有什么看法？" → 获得多个方案供选择

确认理解

"告诉我你的理解是什么，我来核对" → 反向确认
"先确认一下：XX 是不是 YY？" → 渐进式确认
"先告诉我你打算怎么实现，不要直接写代码" → 前置审查

提供精确信息

"具体值：A→X, B→Y, C→Z" → 数值映射
"如图所示：" + [截图] → 消除 UI 歧义
"编辑器里能找到，但生成器找不到" → 对照信息

纠正错误

"你理解的不对，不是 XX 而是 YY，具体来说..." → 精确纠正
"旧假设 vs 实际情况（表格对比）" → 模型纠正

流程管理

"整理成一个总览文档，我需要核对细节" → 阶段性整理
"如果 A 则 B；反之则 C" → 双向规则描述
"先画个流程图，我们确认一下理解是否一致" → 复杂逻辑可视化

八、核心原则总结

先学后做：让 AI 理解上下文再动手，不要直接让它写代码
截图为王：涉及 UI、数据结构、代码位置时，截图比文字有效 10 倍
精确值优于描述：给 属性=值 映射，不给模糊描述
反向确认：让 AI 说出理解，你来判断对错
渐进确认：一次只确认一个概念，逐步构建正确理解
双向规则：正常和异常路径都要说明
小步验证：做一步验一步，不要一次性实现全部
流程图沟通：复杂逻辑用图表达，不用纯文字