AI编码异常处理控制框架

SKILL.md

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

# 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注意力衰减特性。**

**编码指令模板：**

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

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

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

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

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

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

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

[提供已标好异常处理位置的代码骨架]
[每个位置标注：// 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不能只"跑测试" → 必须证明"测够了" → 必须报告"哪里没测到"。**

**测试指令模板：**

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

---

### L5 审查层：AI审查AI

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

**异常处理审计清单：**

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

**审计员提示词：**

```
你是一个严格的异常处理审计员。请审查以下代码，仅关注异常处理：
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项）
0. **需求阶段** → 七维引导式走完，基于调研结果填充，通过需求质量门（8项）
0. **设计阶段** → 五层防御引导式走完，基于调研结果设计，通过设计质量门（6项）
1. **规格书阶段** → 三维度穷举失败场景（十大域+参数轴+状态机），定义异常AC
2. **架构阶段** → 确认Result模式/中间件/熔断等基础设施就位
3. **编码阶段** → 使用"异常优先"提示词模板，先异常后正向
4. **测试阶段** → 六层框架：用例生成→自动执行→异常路径→覆盖率→混沌注入→报告
5. **审查阶段** → 用审计清单做异常专项审查，AI审查AI
6. **弯路记录** → 编码/调试中走的弯路记录到 `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状态机，可作为使用范例）