AI编码异常处理控制框架

AI编码异常处理控制框架。当用户要求"编写功能"、"实现接口"、"开发模块"、 "写代码"、"编码"、"需求分析"、"设计"、"测试"、"代码审查"、"重构"时触发。 通过七层防御机制（深度调研→需求引导→设计引导→规格书→架构→提示词→测试→审查→弯路闭环）， 从调研阶段开始强制AI完整思考异常路径，杜绝"只走正向流程、异常处理简化"的问题。 包含深度调研引导、引导式需求设计SOP、三维度失败场景穷举法、六层自动化测试框架、 弯路沉淀与持续改进闭环、Audit-Ledger审查交接、可直接复用的12套模板。 适用于任何语言/框架/平台的AI辅助开发项目。

核心问题

AI在编码时存在系统性偏差：只写happy path，异常处理敷衍了事。 根因：训练数据偏科、上下文压缩丢异常、缺乏后果感知、优化"能跑"而非"能扛"。

解决思路：不靠AI自觉，靠机制倒逼。

---

教训沉淀（为什么存在这个框架）

以下教训来自真实项目开发实践，2026-07总结。

教训1：AI编码天然偏科，不是个别现象

根因	表现	后果
训练数据偏差	开源代码/教程中happy path占80%+，异常处理代码稀疏	AI生成的代码天然"偏科"
上下文压缩	长代码生成时，AI优先保证主流程跑通，异常处理被"遗忘"	越复杂的功能，异常缺失越严重
缺乏后果感知	AI不知道异常缺失会导致生产事故	try-catch里放个console.log就交差
优化目标偏移	AI优化"代码能跑"而非"代码能扛"	能过测试 ≠ 能上线

教训：不能指望AI"自觉"处理异常。把"请处理异常"写在提示词里没用，AI会写一个空catch块交差。

教训2：真实项目的典型案例——catch{}静默吞没

全链路审查中发现：多个模块存在 catch (error) {} 空catch块或 catch (error) { console.log(error); return null; } 假处理。这不是某一个开发者的疏忽，而是项目级系统性缺失——所有模块都有这个问题。

教训：异常处理缺失是系统性的，不是个别bug。必须从流程层面解决，而非逐个修复。

教训3：事后审查不够，已经晚了

最初只有L5审查层（代码写完后审查），发现问题时代码已经写完、测试已跑通、甚至已经部署。修复成本极高——要改异常处理意味着改函数签名、改调用链、改测试用例。

教训：异常处理必须从L1规格书阶段就开始控制。越早发现，修复成本越低。规格书里没写失败场景，编码时就不可能处理。

教训4：一次性投入，永久收益

L1规格书模板写一次，每个功能点都复用；L2架构层的统一异常中间件搭一次，所有业务代码都受益。这两层的投入产出比远高于L3-L5的日常执行。

教训：优先把L1+L2做扎实。基础设施层一次到位，后续每个功能都自动受保护。

教训5：方法不固化到skill里，就只是一次性聊天

这次五层框架如果只存在对话里，下次专家团队写代码时该偷懒还是偷懒。只有固化到skill里，让框架在编码时自动触发、在审查时强制执行，才能真正改变行为。

教训：凡是重复出现的问题，必须写成skill；凡是多步骤的流程，必须标准化为SOP。凡是走过的弯路，必须记录、分析、改进、预防——不记录就白走了，不改进就还会再走。

---

防御体系（L0→L5，从需求到审查全链路）

L0 需求与设计层：引导式质量保障（最前置防线）

完整引导SOP见 references/requirements-design-sop.md（深度调研5方向+七维需求引导+五层设计引导+三道质量门，68步引导）

核心认知：需求阶段的模糊 = 编码阶段的自由发挥 = 测试阶段的无的放矢 = 上线后的事故。 需求和设计阶段的每一分投入，会在后面三个阶段产生3倍回报。

AI在需求设计阶段同样会偷懒（只写happy path / 验收条件模糊 / 非功能需求缺失 / 跳过设计直接编码），必须用引导式流程倒逼。

L0-R 深度调研引导（5方向，20步引导）

在定义需求之前，先搞清楚"别人怎么做的、最好的实践是什么、有什么坑"。AI必须使用WebSearch/WebFetch/Grep/Glob等工具进行实际调研，禁止只凭训练数据编造最佳实践。

方向	引导目标	核心问题	喂给后续
① 同类产品	行业标杆长什么样	至少3个产品？做得好的/差的？用户痛点？	→ 维度三·失败场景
② 技术方案	选最合适的技术路线	至少2种方案对比？最新最佳实践？现成库/SDK？	→ 设计阶段
③ 标准规范	遵循行业标准不是自己发明	行业标准？安全合规？官方Best Practices？	→ 维度四·非功能需求
④ 失败案例	别人的坑就是你的预防清单	至少3个已知坑？事故复盘？SO高频问题？	→ 维度三·失败场景 + 测试·混沌注入
⑤ 参考实现	让AI"有样学样"不是从零发明	开源实现？官方示例？现有代码库类似实现？	→ 设计·异常架构

调研质量门（6项全过才允许进入需求）： R1同类产品 / R2技术方案 / R3标准规范 / R4失败案例 / R5参考实现 / 调研-需求映射

L0a 需求引导（七维模型，28步引导）

维度	引导目标	核心问题
① 用户故事	谁+做什么+为什么	服务对象具体到画像？不同角色诉求分别是什么？
② 验收条件	Given-When-Then格式	正常/异常/业务规则限制下分别看到什么？异常AC≥正向AC？
③ 失败场景	三维度穷举	十大域逐个过？每个参数问8问？状态机非法转换全列出？
④ 非功能需求	具体数值+验证方式	性能P95是多少？安全覆盖传输/校验/存储？
⑤ 接口契约	请求+响应+错误码+降级	每个参数有校验规则？每个失败场景有错误码？降级有独立格式？
⑥ 数据模型	字段+约束+索引+迁移	每个字段有约束？查询字段有索引？迁移向后兼容？
⑦ 依赖地图	外部+内部+降级策略	每个依赖挂了怎么办？fail-open还是fail-close？

需求质量门（8项全过才允许进入设计）： D1用户故事 / D2验收条件 / D3失败场景穷举 / D4非功能需求 / D5接口契约 / D6数据模型 / D7依赖地图 / 整体一致性

L0b 设计引导（五层防御，20步引导）

设计层	引导目标	核心问题
① 异常架构	框架兜底，AI想偷懒都没机会	全局中间件存在？降级链4级？每个调用有超时+重试？
② API规范	AI只需"填空"不需"发明"	统一响应格式？错误码体系复用？分页+认证定义？
③ DB设计	事务+索引+迁移全规划	事务范围？索引策略？迁移可回滚？
④ 安全设计	认证+授权+校验+限流	token生命周期？数据级隔离？前后端分离校验？限流分级？
⑤ 测试策略	分层+覆盖率+来源映射	测试分几层？用例从哪来？CI/CD怎么自动化？

设计质量门（6项全过才允许进入编码）： S1异常架构 / S2 API规范 / S3 DB设计 / S4安全设计 / S5测试策略 / 需求-设计一致性

关键衔接：

• 调研的"失败案例" → 需求的"失败场景清单"（第四维度·经验维度） → 设计的"异常处理架构" → 编码L3的"异常优先模板" → 测试L4的"异常路径测试"+ 混沌注入
• 调研的"标准规范" → 需求的"非功能需求" → 设计的"安全设计" → 编码的"安全实现" → 测试的"安全测试"
• 调研的"技术方案" → 需求的"接口契约" → 设计的"API规范" → 编码的"参数校验" → 测试的"参数轴测试"
• 调研的"参考实现" → 设计的"异常处理架构" → 编码的"实现模式" → 审查的"对比参考"
• 需求的"状态机" → 设计的"状态机设计" → 编码的"状态校验" → 测试的"非法转换测试"

---

L1 规格书层：把异常处理写成硬性约束

在工程规格书中，每个功能点必须包含"失败场景清单"表格，异常AC与正向AC同等地位。

核心方法：三维度失败场景穷举法 — 不靠"灵感"想几个，靠"工具"系统化穷举。

完整穷举模板见 references/templates.md 第7节（十大域+参数轴+状态机+合并去重+AI穷举指令）

三维度穷举法

维度	方法	穷举公式	预期场景数
维度一·十大域	对10个失败域逐个检查	每域2-3个 × 10域	20-30个
维度二·参数轴	每个参数问8个问题	参数数 × 8	24-40个
维度三·状态机	列出所有非法状态转换	状态数×(状态数-1) - 合法转换	5-15个
合并去重	三维度结果合并去重	—	15-50个

十大失败域： 输入层 / 认证授权 / 网络通信 / 数据层 / 并发冲突 / 外部依赖 / 资源耗尽 / 业务逻辑 / 安全攻击 / 环境配置

参数轴8问： 缺失 / 空值 / 格式错 / 类型错 / 超长 / 特殊字符 / 注入 / 边界值

状态机公式： 状态数 × (状态数-1) - 合法转换数 = 非法转换数 = 失败场景数

规格书模板：

markdown

## 功能点：[功能名称]

### 正向流程
1. [步骤描述]

### 失败场景清单（三维度穷举，合并去重后）
| # | 来源维度 | 场景 | 异常类型 | 处理方式 | 用户感知 | HTTP状态码 | 优先级 |
|---|---------|------|---------|---------|---------|-----------|--------|
| F1 | D9安全 | SQL注入 | SecurityError | 清洗+400 | "输入不合法" | 400 | P0 |
| F2 | D2认证 | token伪造 | AuthError | 401 | "请重新登录" | 401 | P0 |
| F3 | D5并发 | 重复提交 | ConflictError | 幂等返回 | 无感知 | 200 | P0 |
| F4 | D6外部 | AI服务超时 | TimeoutError | 降级 | "分析中" | 200 | P1 |
| ... | ... | ... | ... | ... | ... | ... | ... |

### 验收标准
- AC-1（正向）：[正向验收条件]
- AC-2（异常）：[异常验收条件，对应F1]
- 异常AC数量 >= 正向AC数量

关键原则：

• 每个功能点必须按三维度穷举，不允许"灵感式"列举
• 合并去重后失败场景数量 ≥ 5个（复杂接口推荐≥15个）
• 每个场景标注来源维度（D1-D10 / 参数轴 / 状态机）
• 每个场景标注优先级（P0必须实现+测试 / P1必须 / P2必须 / P3可选测试）
• 定义标准异常分类：网络/权限/数据/并发/超时/资源不足
• 禁止"其他错误"这类笼统描述，必须具体到异常类型
• 异常AC必须可测试、可验证

---

L2 架构层：用设计模式让异常无法跳过

核心策略：把异常处理从"AI的责任"变成"框架的责任"。

Result/Either模式（强制错误通道）

typescript

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

// AI写函数时，必须返回Result类型
// 不处理Error分支 → 编译报错 → AI被迫处理
async function login(phone: string, code: string): Promise<Result<Token, AuthError>> {
  // AI必须考虑：验证码错了返回什么？网络超时返回什么？
}

统一异常中间件（AI不需要手写catch）

typescript

// 所有异常自动冒泡到中间件统一处理
// AI只管抛异常，不需要在每个函数里写try-catch
app.use(errorHandlerMiddleware);
// AI想偷懒都没机会——框架兜底

其他架构约束

• 熔断降级：失败超阈值自动降级，而非崩溃
• 幂等重试：网络失败自动重试，带指数退避
• 超时控制：所有外部调用必须设置超时
• 资源清理：使用RAII或finally确保资源释放

---

L3 提示词层：对抗AI偷懒本能

核心策略：异常优先——先说异常，后说正向。利用AI注意力衰减特性。

编码指令模板：

text

请实现以下功能，必须按此顺序执行：

第一步：列出所有可能的失败场景（至少5个）
- 网络异常、权限不足、数据不存在、并发冲突、超时、资源不足...

第二步：为每个失败场景定义处理策略
- 返回什么错误码？用户看到什么提示？是否重试？是否降级？

第三步：先编写所有异常处理代码
第四步：最后才编写正向流程代码

约束：
- 禁止空catch块
- 禁止catch中仅console.log
- 每个catch必须有明确的恢复策略或向上传播
- 异常日志必须包含上下文（请求参数、用户ID、时间戳）
- 错误提示对用户友好，不暴露技术细节

填空式模板（比自由式更可控）：

text

请填充以下代码骨架中的异常处理部分：

[提供已标好异常处理位置的代码骨架]
[每个位置标注：// TODO: 处理[具体异常场景]

---

L4 测试层：用测试倒逼异常处理

核心策略：异常没处理，测试就过不了。

完整测试SOP见 references/testing-sop.md（六层框架30+项检查，含用例生成指令、一键测试脚本、异常用例模板、混沌注入矩阵、覆盖率验证、结构化报告）。

AI全量自动化测试六层框架

AI测试同样会偷懒（只测happy path/断言敷衍/不验证覆盖率/报告太简），必须用六层流水线倒逼：

层	目标	核心手段
L1 用例生成	从规格书自动派生测试用例	失败场景→测试用例映射，边界值自动枚举，异常用例≥正向
L2 自动执行	CI/CD管线一键跑全部	run-all-tests.sh一键脚本，覆盖率阈值80%自动卡
L3 异常路径	测"不该发生的事"	断言四要素（状态码+错误信息+降级行为+副作用），安全测试
L4 覆盖率验证	证明"测够了"	行覆盖>80% + 异常分支覆盖>80% + 未覆盖代码风险分析
L5 混沌注入	模拟"世界崩溃"	DB断连/Redis不可用/第三方超时/磁盘满，验证降级而非崩溃
L6 测试报告	结构化输出	覆盖率矩阵+未覆盖代码清单+混沌结果+通过/不通过判定

核心原则：AI不能只"跑测试" → 必须证明"测够了" → 必须报告"哪里没测到"。

测试指令模板：

text

请为本功能编写测试，要求：
1. 异常用例数量 >= 正向用例
2. 覆盖以下异常场景（必须全部通过）：
   - [场景1]: 期望返回 [错误码]
   - [场景2]: 期望触发 [降级策略]
   - [场景3]: 期望 [重试] 后成功
3. 每个异常用例必须验证四要素：状态码 + 错误信息 + 降级行为 + 副作用
4. 混沌注入：mock DB断连/Redis不可用/第三方API超时，验证降级行为
5. 运行测试，如果异常用例失败，先修复异常处理代码
6. 报告异常分支覆盖率，目标 > 80%

---

L5 审查层：AI审查AI

核心策略：用第二个AI角色专做异常审计，找第一个AI写的代码中的异常漏洞。

异常处理审计清单：

text

□ 所有外部调用（网络/DB/文件）是否有异常处理？
□ catch块是否有具体处理（非空、非仅console.log）？
□ 异常信息是否包含足够的调试上下文？
□ 是否有降级策略（而非直接崩溃）？
□ 是否有重试机制（对可重试异常）？
□ 并发场景是否考虑了竞态条件？
□ 超时是否被正确处理？
□ 用户看到的错误提示是否友好（非堆栈信息）？
□ 异常是否被正确分类和传播？
□ 是否有"静默吞异常"的情况？

审计员提示词：

text

你是一个严格的异常处理审计员。请审查以下代码，仅关注异常处理：
1. 找出所有缺少异常处理的外部调用
2. 找出所有"假处理"的catch块（空catch、仅console.log、仅return null）
3. 找出所有可能导致崩溃的未处理路径
4. 列出缺失的异常场景

输出格式：
- 严重问题：[文件:行号] 问题描述 → 修复建议
- 一般问题：[文件:行号] 问题描述 → 修复建议

---

L6 反馈闭环层：弯路沉淀与持续改进（贯穿全链路的反馈回路）

完整闭环SOP见 references/lessons-feedback-loop.md（四阶段：实时记录→定期分析→改进闭环→预防注入） 弯路记录模板见 references/templates.md 第11节

核心认知：静态的教训沉淀（写死在skill里的5条）解决不了动态的问题。每次开发都会遇到新的坑，不记录就白走了，不分析就还会再走，不改进就永远在原地打转。

AI同样会走弯路（选错方案/调试方向错误/实现路径绕路/异常遗漏），而且AI走弯路不自知、不记录、不学习。必须用机制倒逼。

弯路分类（6大类）

类型	代号	典型场景	改进到哪个文件
技术选型弯路	T-SELECT	选了库A踩坑后换库B	requirements-design-sop.md 调研方向②
调试方向弯路	D-DIRECT	以为是前端bug实际是后端	coding-sop.md 阶段三
实现路径弯路	I-PATH	先方案X后改方案Y	coding-sop.md 阶段一
异常处理弯路	E-MISS	漏处理某异常场景	templates.md 第7节·经验维度
测试弯路	T-WRONG	测试本身有bug	testing-sop.md L3层
架构弯路	A-DESIGN	设计漏了某约束	requirements-design-sop.md 设计阶段

四阶段闭环

阶段	目标	触发时机	产出
① 实时记录	走弯路后立即记录	调试中/编码自检/审查发现/测试暴露	单条弯路记录→lessons-learned.md
② 定期分析	聚类找模式	每功能/每周/里程碑/累计≥10条	分析报告+Top3高频+重复模式+改进优先级
③ 改进闭环	高频弯路→skill/SOP规则	每次分析后立即执行	更新对应文件+标注来源弯路编号
④ 预防注入	下次编码时自动预防	编码前加载skill时	历史弯路检查+预防措施确认

弯路记录文件

• 项目级：.workbuddy/memory/lessons-learned.md（当前项目，追加不修改）
• 跨项目通用：提炼后追加到本文件"教训沉淀"部分

关键约束：每条弯路必须有根因分析（不允许"粗心"）+ 预防措施（不允许"注意"，必须是检查项或规则）。

---

执行顺序（每次功能任务必走）

0. 调研阶段 → 5方向深度调研（同类产品/技术方案/标准规范/失败案例/参考实现），通过调研质量门（6项）
1. 需求阶段 → 七维引导式走完，基于调研结果填充，通过需求质量门（8项）
2. 设计阶段 → 五层防御引导式走完，基于调研结果设计，通过设计质量门（6项）
3. 规格书阶段 → 三维度穷举失败场景（十大域+参数轴+状态机），定义异常AC
4. 架构阶段 → 确认Result模式/中间件/熔断等基础设施就位
5. 编码阶段 → 使用"异常优先"提示词模板，先异常后正向
6. 测试阶段 → 六层框架：用例生成→自动执行→异常路径→覆盖率→混沌注入→报告
7. 审查阶段 → 用审计清单做异常专项审查，AI审查AI
8. 弯路记录 → 编码/调试中走的弯路记录到 lessons-learned.md，定期分析改进skill/SOP

与其他skill的配合

需求与设计阶段（L0）

• references/requirements-design-sop.md：引导式需求设计SOP（深度调研5方向20步+七维需求28步+五层设计20步+三道质量门20项检查）
• product-manager：需求定义时引用L0-R调研引导→L0a七维模型引导
• engineering-software-architect：架构设计时引用L0-R调研结果→L0b五层防御引导
• engineering-backend-architect：后端架构设计时引用L0b异常处理架构

编码阶段（L1-L3）

• engineering-backend-architect：架构设计时引用L2架构约束（Result模式/中间件/熔断）
• engineering-frontend-developer：前端编码时引用L3提示词模板
• engineering-senior-developer：全栈开发时遵循L1-L4执行顺序
• engineering-wechat-mini-program-developer：小程序开发时引用L3异常优先模板
• ponytail：懒人模式下也必须遵守异常处理铁律（不可省略）

测试阶段（L4）— 六层自动化测试框架

• references/testing-sop.md：完整测试SOP（六层框架30+项检查，含用例生成/自动执行/异常路径/覆盖率/混沌注入/结构化报告）
• 项目级全链路审查skill：执行六层框架全部检查（用户可基于本框架创建项目专属审查skill）
• 部署验证skill：部署后异常路径API测试，验证错误码/降级/泄露（用户可基于本框架创建项目专属部署验证skill）

审查阶段（L5）

• engineering-code-reviewer：每次PR审查执行🛡️12项异常专项审计
• 项目级全链路审查skill：全链路审查时包含L5异常审计+项目级教训（用户可基于本框架创建）

SOP文档

• references/requirements-design-sop.md — 引导式需求设计SOP（深度调研5方向20步+七维需求引导28步+五层设计引导20步+三道质量门20项检查）
• references/coding-sop.md — 完整编码SOP（需求设计前置+开发前8项+架构4项+编码6项+测试10项+审查12项+弯路记录）
• references/testing-sop.md — 完整测试SOP（六层框架30+项检查）
• references/lessons-feedback-loop.md — 弯路沉淀与持续改进闭环SOP（四阶段：实时记录+定期分析+改进闭环+预防注入）
• references/audit-ledger-spec.md — Audit-Ledger 文件系统交接规范（编码者↔审查者结构化交接面，Ralph模式物理实现层）

参考文件

• references/templates.md — 完整模板集合（规格书/提示词/骨架/测试/审计清单/异常分类表/三维度穷举/需求模板/设计模板/调研模板/弯路记录模板）
• references/requirements-design-sop.md — 引导式需求设计SOP（深度调研5方向+七维需求引导+五层设计引导+三道质量门+AI引导指令）
• references/coding-sop.md — 编码SOP（阶段零需求设计+开发前8项+架构4项+编码6项+测试10项+审查12项+弯路记录）
• references/testing-sop.md — 测试SOP（六层框架：用例生成/自动执行/异常路径/覆盖率/混沌注入/报告，30+项检查）
• references/lessons-feedback-loop.md — 弯路沉淀SOP（四阶段闭环：实时记录+定期分析+改进闭环+预防注入，6大弯路分类+改进映射表）
• references/audit-ledger-spec.md — Audit-Ledger 交接规范（编码者↔审查者结构化交接面，5文件格式+状态流转+权限约定+Ralph模式集成）
• references/reverse-requirements.md — 逆向需求规格（本体系自验证产出，28个失败场景+18条AC，可作为使用范例）
• references/reverse-design.md — 逆向技术设计（本体系自验证产出，5层设计+3状态机，可作为使用范例）