> 这篇文章记录了我在构建 Debug Skill 过程中的三次重要迭代，每一次都源于实际使用中发现的痛点。希望这些经验能帮助大家在构建 AI 技能时少走弯路。 你可以直接向我要整篇文章的原文，然后丢给claude skills，我也开源了这个skills，你可以通过plugin marketplace liuxiaoyusky/ai-developer-skills 获取我全部7个skills。

>

> ## 第一次迭代：5 Whys - 找到根本原因 

>

> ### 起因 最初创建 Debug Skill 时，我发现 AI 经常犯一个错误：**只治标不治本**。

>

> 用户: "我的页面加载很慢"

>

> AI: "加个缓存吧" 

>

> 问题：都没搞清楚慢在哪里，就建议加缓存

>

> 这让我意识到：AI 需要一个**强制性的根因分析框架**。 

>

> ### 解决方案：5 Whys 

>

> 我设计了一个基于 5 Whys 的 Debug Skill，核心思想很简单，举个例子你就知道了： 

>

> 问题: API 返回 500 错误 

>

> Why 1? → 数据库查询超时

>

> Why 2? → 连接池耗尽

>

> Why 3? → 连接未关闭

>

> Why 4? → 错误路径没调用 close()

>

> Why 5? → 缺少 finally 块 

>

> ROOT CAUSE: 缺少 finally 块

>

> SOLUTION: 添加 finally 块 

>

> 在skills里加上生产环境验证（不相信本地构建，只信任运行时错误），一个 ~205 行的 Debug Skill 诞生了。 

>

> ### 效果 

>

> ✅ **解决的问题**：- AI 不再猜测，而是先用工具调查- 强制执行根因分析，避免症状修复- 生产环境验证避免了"本地可行，线上失败" 

>

> ⚠️ **遇到的新问题**：

>

> 1. "性能问题用 5 Whys 找不到满意答案"

>

> 2. "有些系统本身设计就有问题，修复它没有意义

>

> "3. "AI 只会'修复'，不会'质疑'" 

>

> ## 第二次迭代：第一性原理 - 质疑设计本身

>

> ### 痛点爆发 有一次遇到这样一个问题：

>

> 问题: API 查询需要 10 秒 

>

> 5 Whys 分析:- 慢？ → 返回 1000 条记录

>

> - 1000 条？ → 没有分页

>

> - 没有分页？ → 产品要求显示全部

>

> - 产品要求？ → 需求文档这么写的 

>

> SOLUTION: 添加分页 

>

> 但这个方案需要改动：后端、前端、产品文档...而且，用户真的需要一次看 1000 条吗？

>

> 我意识到：**5 Whys 是在"现有框架内优化"，但问题可能出在"框架本身"**

>

> ### 顿悟时刻 马斯克的第一性原理思维给了我启发： 

>

> > "不要用类比思维（别人怎么做），而要从基本真理重建" 

>

> 对于这个 API 问题：

>

> 基本真理:

>

> - 数据库查询: 1000 条记录 = 5s

>

> - 网络传输: 1MB / 10Mbps = 0.8s

>

> - 人眼处理: 只能同时看 10-20 条 

>

> 质疑假设:

>

> - "用户真的需要 1000 条吗？"→ 观察: 99% 用户只看前 20 条 

>

> - "为什么是一次性查询？"→ 真相: 用户需要搜索/筛选，而不是浏览 

>

> 重建方案:不添加分页，改用搜索/筛选结果: 不需要修改产品逻辑，10s → 0.5s

>

> ### 解决方案：双轨制 

>

> 我重新设计了 Debug Skill，从单轨（5 Whys）升级到双轨： 

>

> Layer 1: 问题分类

>

> 明确错误？ → 轨道 A (5 Whys)

>

> 性能/设计问题？ → 轨道 B (第一性原理) 

>

> Layer 2: 调查方法

>

> 轨道 A: 5 Whys（自顶向下）→ 找根本原因

>

> 轨道 B: 第一性原理（自底向上）→ 质疑设计 

>

> Layer 3: 解决路径（四重选择）

>

> 修复系统 or 修改预期 or 重构系统 ir 接受差异 

>

> 从 ~205 行扩展到 ~614 行，但覆盖范围从"明确错误"扩展到"所有问题类型"。 

>

> ### 效果

>

> ✅ **解决的问题**：- 性能问题不再盲目优化，而是质疑设计假设- 可以 10x 优化（质疑设计）vs 10% 优化（修复实现）

>

> - 提供了"重构系统"的路径，而不是"在错误的基础上修复"

>

> ⚠️ **又遇到新问题**：

>

> 1. "同样的问题在项目中出现了 3 次，每次都重新分析"

>

> 2. "上次用 Redis 缓存失败了，这次 AI 又建议用 Redis"

>

> 3. "这个 API 超时问题上个月解决过，但不记得具体方案了" 

>

> ## 第三次迭代：错题集 

>

> - 从无状态到有状态 

>

> ### 痛点：重复掉进同一个坑 最近一个项目，我遇到了一个诡异的现象： 

>

> 第 1 周: API 超时AI 分析: 5 Whys → 发现 N+1 查询 → 修复 

>

> 第 3 周: API 又超时AI 分析: 5 Whys → 发现 N+1 查询 → 修复我: "我们不是上周刚修复过吗？" 

>

> 第 5 周: API 还是超时AI 建议: "要不试试 Redis 缓存？"我: "等等，第 2 周我们试过 Redis，失败了啊！" 我突然意识到：**AI 是无状态的，每次 debug 都从零开始，完全不记得历史**。 

>

> ### 人类怎么做？ 

>

> 如果是我遇到重复问题，我会：

>

> 1. 翻翻之前的笔记

>

> 2. 看看上次怎么解决的

>

> 3. 避免上次失败的路径 这就像学生的**错题集**：

>

> - ✅ 记录成功的解法（下次参考）

>

> - ❌ 记录失败的尝试（下次避免）

>

> ### 第一性原理思考 

>

> **基本真理**：

>

> 1. 学习是迭代的 - 人类和 AI 的进步都建立在"经验积累"之上

>

> 2. Debug 本质是模式识别 - 很多问题在不同项目中重复出现

>

> 3. 局部性原理 - 每个项目的问题模式是独特的 

>

> **质疑假设**：

>

> - ❌ "每次 debug 都应该独立分析"→ 真的吗？如果同样的 API 超时出现了 3 次，第 4 次还要从头？

>

> - ❌ "存储经验会增加复杂度"→ 复杂度 vs 价值？如果每次能节省 10 分钟，值得吗？

>

> **重建方案**： 为每个项目建立本地的"错题集"：

>

> .claude/debug-experiences/ 

>

> 1. INDEX.md # 轻量级索引

>

> 2. 2025-01-15-api-timeout.md # 成功经验

>

> 3. 2025-01-10-redis-cache.md # 失败经验

>

> 4. 2025-01-08-memory-leak.md 

>

>

> ### 关键设计：分层架构 

>

> 我最初想把所有经验存在一个文件里，但很快发现一个问题： 

>

> > "如果项目运行了一年，积累了 100 条经验，每次 debug 都读 100 条，得浪费多少 tokens？" 于是改用 INDEX + Details 

>

> 分层架构： 

>

> ## INDEX.md（只读前 50 行，< 100 tokens）

>

> ## 🔥 High-Frequency Issues 

>

> ### [Performance] API Timeout - 5 occurrences

>

> **Pattern**: N+1 queries → Add eager loading

>

> **Quick Fix**: Check for `.include()`→ [detail](2025-01-15-api-timeout.md) 

>

> Detail Files（按需读取）：# API Timeout - 2025-01-15 

>

> **Problem**: API returns 500, timeout 30s

>

> **5 Whys**: ...

>

> **Root Cause**: N+1 query problem

>

> **Solution**: Added `.include('posts')`

>

> **Result**: 30s → 0.2s 

>

> 检索流程：

>

> 1. 读取 INDEX 前 50 行

>

> 2. 匹配标签/关键词

>

> 3. 选择 Top 3-5 条

>

> 4. 按需读取详细经验 

> ### 语义激活：零认知负担 

>

> 最初我设计了一个显式命令：/debug-history 但很快意识到：

>

> 用户不应该记住"去查错题集"。

>

> 更自然的方案是：AI 自动识别 debug 场景 

>

> 场景 1: 强信号（立即激活）

>

> 用户粘贴: "Error: 500 at api.js:123"AI: 🔍 检测到错误信号，自动启动 debug skill📚 找到 2 条相关经验，是否参考？[Y/n] 

>

> 场景 2: 中等信号（询问后激活）

>

> 用户: "API 最近响应很慢"AI: 🤔 看起来是性能问题，是否启动 debug skill？[Y/n] 

>

> 场景 3: 弱信号（不激活）

>

> 用户: "如何实现用户登录？"AI: [正常回答，不激活 debug] 

>

> ### 避坑指南：失败路径标记 

>

> 最重要的功能之一：记录失败的尝试。 

>

> ### 预期效果 - 首次问题: 标准流程（无变化）

>

> - 重复问题: 减少 50-70% 时间（参考历史）

>

> - 高频问题: 减少 80% 时间（模式识别）

>

> - 失败避坑: 避免 100% 重复错误 

>

> ## 三次迭代的共同启示 

>

> ### 1. 问题驱动，而非技术驱动 每一次迭代都不是"我想用什么技术"，而是"遇到了什么问题"： 

>

> 第一次: AI 不做根因分析 → 5 Whys

>

> 第二次: 只会修复不会质疑 → 第一性原理

>

> 第三次: 重复掉坑 → 错题集 

>

> ### 2. 从"通用"到"定制" 

>

> 第一次: 通用的根因分析方法

>

> 第二次: 针对不同问题类型的方法

>

> 第三次: 针对特定项目的经验积累 

>

> ### 3. 保持简洁，避免过度工程 

>

> 第二次迭代时，我曾经把 Debug Skill 扩展到 800+ 行，包含大量"高级功能"。 

>

> 后来问自己："这是必需的吗？" 于是删减回 614 行，只保留核心：

>

> - ✅ 双轨制（5 Whys + 第一性原理）

>

> - ✅ 决策树（自动选择轨道）

>

> - ✅ 四重解决路径

>

> - ❌ 删除了"诊断工具"、"性能分析器"等过度功能 

>

> 原则：Less is More 

> ### 4. 向后兼容，渐进增强 

>

> 错题集功能设计时，我特别强调：

>

> - ✅ 首次使用无感知（自动创建）

>

> - ✅ 完全向后兼容（老项目也能用）

>

> - ✅ 可选功能（可用 flag 禁用） 

>

> 这样用户不会因为"升级"而感到困扰。

>

> ## 未来可能的迭代方向 

>

> ### 1. 跨项目经验迁移 当前每个项目有独立的错题集，但某些模式是通用的： 项目 A: N+1 查询问题 → 解决项目 B: 也遇到 N+1 查询 → 能否复用经验？ 可能的方案：- "经验库"（存储通用模式）

>

> - "相似项目匹配"（推荐相关经验）

>

> ### 2. 团队协作 如果团队多人使用同一个项目：

>

> - 错题集可以通过 Git 共享

>

> - 团队成员可以互相参考经验

>

> - 形成团队的"知识库" 

>

> ### 3. 自动化经验提取 

>

> 当前需要手动记录经验，未来能否：

>

> - 自动检测重复问题

>

> - 自动提炼模式

>

> - 自动生成"避坑指南" 

>

> ## 总结 Debug Skill 的三次迭代，其实反映了 AI 技能构建的通用模式： 

>

> 第一阶段: 解决核心问题（5 Whys）

>

> 第二阶段: 扩展适用范围（第一性原理）

>

> 第三阶段: 持续积累经验（错题集） 

>

> 每一次迭代都不是"推倒重来"，而是在前一版的基础上发现不足 → 设计改进 → 验证效果。 

>

> 关键原则：

>

> 1. 问题驱动 - 从真实痛点出发

>

> 2. 第一性原理 - 质疑所有假设

>

> 3. 保持简洁 - Less is More

>

> 4. 向后兼容 - 渐进增强

>

> 5. 持续迭代 - 没有完美版本 

>

> 希望这些经验能帮助大家在构建 AI 技能时少走弯路。