企业官网建设流程全解析

Awesome-Vibecoding-Guide是一份来自真实商业项目的 AI 辅助开发（Vibecoding）实战手册，其中故障排查（Troubleshooting）章节专门解决一个核心痛点：AI 编程调试失败大多不是模型不行，而是上下文失败。本文提炼了指南中的"95/5 法则"与 Human-First 调试法，帮你快速定位 AI 开发报错、幻觉、上下文丢失等问题，把数小时的瞎猜压缩成几分钟的一次性修复。

一、95/5 法则：AI开发失败的真相

指南给出了一个非常扎心的统计：如果你被迫"推倒重来"，只有5%的情况是真的在开发企业级超复杂系统，剩下95%都是没有正确指导 AI，就硬着头皮往前冲导致的。

问题不在 AI 工具、模型或上下文窗口，而在于人脑里缺少上下文知识。典型的失败循环长这样：

❌ "提交按钮坏了，修一下" → AI 瞎猜改代码 → 还是坏的 → 再猜 → 浪费 30 分钟 → "这 AI 真没用"

AI 不是千里眼，它只能看到你主动展示的内容：你贴的代码、你写的描述。你不给它控制台报错，它就看不见；你不给它复现步骤，它就只能蒙。

📖 该结论出自指南的《The Human Context Problem in AI Debugging》：human-context-debugging.md

二、Human-First 调试法：先调试"人"，再调试代码

指南提出的核心原则是：在让 AI 调试之前，先调试人类的上下文。正确流程对比：

第 1 步：人工收集 5 类上下文

1. 控制台报错：按F12打开 DevTools，复制完整错误信息和堆栈（stack trace）
2. 网络请求：查看 Network 面板，找到红色失败请求，记录状态码（404/500/401）和响应内容
3. 复现步骤：写下精确的点击、输入、时机
4. 期望 vs 实际：本应发生什么？实际发生了什么？
5. 环境细节：浏览器、操作系统、设备

第 2 步：给 AI 一份"完整案情"

指南强烈建议用结构化描述代替"修一下"，例如：

错误信息：[粘贴精确错误] 控制台：[错误 + 堆栈] 网络：[失败请求 + 响应] 复现步骤：[精确步骤] 期望：[应发生什么] 实际：[发生了什么] 代码位置：[文件:行号] 请帮我定位根因？

对比一个真实案例：登录功能坏了。坏方法贴 200 行代码让 AI 猜，浪费 30 分钟；Human-First 方法先打开 DevTools 发现请求体里密码是写死的password123，AI 立刻指出login.js第 23 行读错了表单字段——2 分钟收集上下文，30 秒修复。

📖 完整三步框架见：human-context-debugging.md

第 3 步：像侦探一样主导排查

复杂问题时，你是 AI 的眼睛：你先测试、发现规律（比如"80% 成功，页面加载完前快速点击就失败"），再把发现交给 AI 出方案。AI 基于你找到事实给出解法，而不是反过来。

三、AI 开发故障症状速查表

指南提供了一张"症状 → 原因 → 速修"对照表，精选最高频的几类：

💡 完整速查表（含 40+ 症状、工具专属问题如 Claude Code / Cursor / MCP 连接失败）见：troubleshooting/README.md

四、调试上下文收集清单（附 DevTools 快捷键）

每次出问题，按这张清单过一遍，再去找 AI：

• 打开 DevTools（Windows/Linux：F12；Mac：Cmd + Option + I）
• 复制 Console 中的完整错误 + 行号
• 检查 Network 中失败请求的方法、状态码、请求体、响应
• 写下可稳定复现的步骤，标注是必现还是偶发
• 记录"期望 vs 实际"的差异
• 定位涉及的文件:行号
• 记录环境（浏览器版本 / 系统 / 设备）

最低要求：控制台报错 + 你在做什么 + 实际发生了什么 + 复现步骤。理想状态：再加上网络请求详情、已尝试的方案、环境细节。

常用的 Chrome DevTools 快捷键（Ctrl+Shift+J直接打开 Console、Ctrl+Shift+R硬刷新清缓存等）完整清单见：debugging-commands.md

五、AI 搞砸了怎么救？Git 时间机器

AI 改坏了代码别慌，指南在 recovery-patterns.md 中总结了"最后已知良好状态"恢复套路，核心四步：

1. 找到最后能跑的 commit：git log --oneline -10
2. 先建安全分支：git branch broken-state（保住现场）
3. 回滚：git revert <坏commit>（温和）或git reset --hard <好commit>（核选项，慎用）
4. cherry-pick 好的部分，把坏分支里的可用改动逐个救回来

其他高频场景也有现成方案：

• 定位是哪次 AI 改动引入的 bug→git bisect二分查找，有测试还能git bisect run npm test全自动
• AI 自相矛盾（先说用 sessions 又改说 JWT）→ 停下来要求它澄清并写进docs/decisions/决策文档，同时更新.cursorrules
• 上下文丢失恢复→ 显式重置："停止。项目是 X，技术栈是 Y，当前任务是 Z，先读.cursorrules"
• AI 装错依赖→git checkout HEAD -- package.json回滚后，一次只升一个大版本

📖 完整恢复模式（含生产回滚、数据库迁移失败、依赖地狱）见：recovery-patterns.md

黄金法则：拿不准就先建分支——分支不花钱，丢工作才要命。

六、什么时候该"重新开始"？（防误判）

"推倒重来"的冲动通常来自挫败感，但指南把它拆得很清楚：

真正该新启动项目的场景极少：原型验证完转正式、架构选型根本性错误、技术栈用错。

正确的"重来"姿势：停手 30 分钟 → 打开 DevTools 系统排查 → 收集完整上下文 → 带着证据找 AI。指南里那个案例：20 小时项目卡死，以为要大修，收集上下文后发现只是环境变量拼写错误，2 分钟修复。

七、上下文管理：从源头减少故障

调试问题的另一半是预防。指南的上下文管理章节给出黄金规则：对话是短暂的，文件是永久的。把计划、决策、约定写进.md文件，比塞在对话里省 90% 上下文，还能跨会话、跨 Agent 共享：

传统：Plan → 讨论 → 实现 → 调试（吃满 200k tokens） .md 模式：写 plan.md → "实现 plan.md" → 更新 plan.md（仅 20k tokens）

配套实践：关键信息放上下文后段（利用近因偏好）、上下文用到 70% 就主动总结、.cursorrules写死技术栈和约定。详见：context-management/README.md

八、仓库故障排查资料地图

结语

AI 开发失败的根因，95% 不在模型，而在那句轻飘飘的"修一下"。AI 是你的结对程序员，不是千里眼——你负责看见运行时状态、收集报错和复现路径，它负责分析和出方案。把"开 DevTools → 看控制台 → 查网络 → 记复现步骤 → 给完整上下文"变成肌肉记忆，再配上 Git 安全分支和.md上下文外化，绝大多数"AI 调试不了"的困局都会变成一次精准的修复。

5 分钟读懂 Human-First 调试法 = 省下数小时的瞎猜调试 ⏱️