核心论点：AI 编码返工最常见的根因不是信息缺失，而是流程错误------用错了模式。了解三种模式的适用边界，比学会"怎么写更好的 prompt"更优先。
三种模式的核心差异
CodeBuddy 提供了三种对话模式，差异不仅在功能，更在AI 的决策权限：
| Ask | Craft | Plan | |
|---|---|---|---|
| 本质 | 只读对话 | 读+写 | 设计+写 |
| AI 能改文件吗 | ❌ | ✅ | ✅（但先出计划） |
| 适用步骤数 | 不限 | 1-2 步 | 3+ 步（跨文件） |
| 你验证的时机 | 每轮对话 | 改完后 | 计划阶段 + 改完后 |
| 风险 | 零（只读） | AI 可能在错误方向一路狂奔 | 低（计划阶段拦截） |
模式一：Ask------讨论和探索
什么时候用
- 设计讨论："三层漏斗里，@ 引用和搜索后生成哪个先做？"
- 代码理解："这个 mcp_client.py 的 connect_all 是怎么处理重连的？"
- 方案对比："参数抽取从正则升级到 LLM，有哪几种方案？"
- 问题诊断："为什么加载模型卡在 Loading weights: 0%？"
- 审查已有代码："review 一下 tool_registry.py 的错误处理"什么时候不用
- "帮我改一行"------这种直接 Craft，Ask 只出建议不出代码改
- "帮我写一个新模块"------Ask 出的代码你需要手动粘贴，Plan 更合适
- 连续讨论超过 5 轮------如果你和 Ask 在反复讨论一个实现细节，
说明你已经明确要做什么了，切换到 Craft 或 Plan一个真实案例
Shop-Agent 项目里，MCP Server 的优先级 fallback 逻辑在 Ask 模式下讨论了降级策略、工具粒度 fallback、与 tool_registry 的兼容性。三轮后方案成型，切 Plan 模式实施------不需要在实现过程中反复讨论架构。
Ask 的价值：零风险地探索方案空间。用错了 Craft 可能改出 200 行废弃代码，改用 Ask 只消耗了几轮对话 token。
模式二：Craft------精准的单文件改动
什么时候用
- 改一行/一个方法："把 get_user() 改成 async"
- 加一个新字段："UserSchema 加 phone 字段"
- 修一个小 bug："format_time() 时区处理错了，用 pytz 修"
- 重构一个函数："把这个正则改成 Pydantic validator"
- 依赖已知上下文："@ llm_service.py，给 chat() 加 temperature 参数"什么时候不用
- 涉及 3 个以上文件------AI 到了第 3 个文件容易漂移
- 方案不确定------你还在想"用方案 A 还是方案 B"
- 有连锁影响------改 model 会影响到 schema、service、router、test
- 新模块/新功能------AI 需要先理解调用关系才能写好关键技巧：小步快跑
Round 1：改 model（加字段）→ 验证
Round 2：改 schema（同步字段）→ 验证
Round 3：改 router（新入参）→ 验证不要"一口气改完 model + schema + router + test"。每轮一个文件，每轮验证。AI 在一次对话里改第 3 个文件时就容易忘记前两个文件的细节。
模式三：Plan------复杂任务的施工图
什么时候用
- 跨 3+ 文件的改动
- 新功能/新模块
- 方案不确定（需要先讨论方案再实施）
- 有依赖顺序（必须先改 model 再改 schema 再改 service）
- 重构------改一个核心类会影响多处调用Plan 模式的核心优势
Plan 模式分两步：
- 计划阶段：AI 出计划，你审核，来回讨论直到方案 OK
- 执行阶段：AI 按计划逐步实施
这解决了一个关键问题：Craft 模式下，如果你发现第 3 步有更好的做法，前面两步已经写完了，需要返工。Plan 模式下，计划阶段就发现并修正了。
一个真实案例：参数抽取升级
Shop-Agent 项目里，把参数抽取从正则模式升级到 LLM 模式：
我（Plan 模式）：参数抽取目前是基于正则的，我要升级到 LLM 模式。
保持现有接口不变，调用方不受影响。
AI：[计划]
1. 分析 param_extractor.py 的当前接口和调用方
2. 确认 router/chat.py、chat_agent.py、intent_recognizer.py 的调用方式
3. 改造方案：
a. param_extractor.py：extract() 内部从正则切换为 llm_service.chat()
b. config.py：加 PARAM_EXTRACT_MODE 配置项（支持 'regex' / 'llm'）
c. 保持 extract() 签名不变，返回类型不变
4. 实现顺序：config.py → param_extractor.py → 验证
5. 不修改 router、chat_agent、intent_recognizer（接口兼容）
我：第 3 条，降级逻辑呢？如果 LLM 超时，fallback 到 regex 吗？
AI：[更新计划]
3. 改造方案：
a. extract() 内部优先 llm_service.chat()，超时 3s
b. 超时或异常时 fallback 到原有正则逻辑
c. 降级时打 warning 日志，写 metrics
d. config.py 加 LLM_EXTRACT_TIMEOUT 配置
我：OK，执行。
AI：[逐步实施 config → param_extractor，不改其他文件]如果在 Craft 模式下做这个改动：
- AI 也许会重写整个
extract()，然后把 router 里的调用方式也改了 - 降级逻辑在"改完发现跑不动"后才加上
- 最后可能改了 5 个文件，其中 3 个不需要改
Plan 模式的价值不是"多了一个步骤"，而是"把架构决策提前到不产生代码的阶段"。
模式选择矩阵
每次开始任务前，用这个流程图快速判断：
| 1-2 个文件 | 3+ 个文件 | |
|---|---|---|
| 方案确定 | Craft 直接改 | Plan 先出计划再改 |
| 方案不确定 | Ask 先讨论 | Ask→Plan 讨论后再计划 |
最常见的三个错误
错误 1：方案不确定就用 Craft
用户（Craft）：给订单模块加个缓存
AI： [写了 50 行]
用户：不对，我要用 Redis 不是内存
AI： [改写 50 行]
用户：等等，应该先看已有的缓存方案
AI： [发现 redis_cache_service，再改]
→ 两次返工，全是没必要的正确做法：先用 Ask 问"项目里有没有现成的缓存方案"，1 轮对话，然后 Craft 直接改。
错误 2：4 个文件的改动用 Craft
用户（Craft）：给所有 API 加上请求日志
AI： 改 router_1 → 改 router_2 → 改到 router_3 忘了前面怎么写的
→ 3 个 router 的日志格式不一致，需要统一返工正确做法：Plan 模式先出统一方案，然后逐个实施。
错误 3：用 Ask 讨论实现细节超过 5 轮
你：这个怎么实现？
AI：[方案]
你：那如果并发高呢？
AI：[调整]
你：超时怎么处理？
AI：[调整]
（10 轮后）
你：好了开始写吧
AI：[开始写，但已经忘了第 1 轮的上下文]正确做法：Ask 3-5 轮定方案，然后切 Plan 实施。不要在一个模式里做所有事。
核心要点
- 用错模式是 AI 编码返工的第一大根因。 不是 prompt 不够好，是模式选错了。
- Ask 定方向 → Plan 出施工图 → Craft 精准执行。 这是"一次通过"的标准流程。
- 不确定方案时，永远先用 Ask。 讨论不产生代码------零返工风险。
- 超过 2 个文件的改动，默认用 Plan。 多花 2 分钟在计划上，省 20 分钟返工。
- 小步快跑：一个文件一个文件改，每次验证。 不要一口气改 5 个文件。