debug-by-commits
通过 Git Commit 二分法调试前端白屏/卡死问题。 当用户报告页面白屏、无响应、卡死，且怀疑是代码问题时使用。 特别适用于： 1. 开发服务器能启动但页面显示白屏 2. 页面无响应或卡死（可能是死循环） 3. 需要快速定位引入问题的具体 commit 4. 需要排除缓存、配置等干扰因素
Best use case
debug-by-commits is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
通过 Git Commit 二分法调试前端白屏/卡死问题。 当用户报告页面白屏、无响应、卡死，且怀疑是代码问题时使用。 特别适用于： 1. 开发服务器能启动但页面显示白屏 2. 页面无响应或卡死（可能是死循环） 3. 需要快速定位引入问题的具体 commit 4. 需要排除缓存、配置等干扰因素
Teams using debug-by-commits should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/debug-by-commits/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How debug-by-commits Compares
| Feature / Agent | debug-by-commits | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
通过 Git Commit 二分法调试前端白屏/卡死问题。 当用户报告页面白屏、无响应、卡死，且怀疑是代码问题时使用。 特别适用于： 1. 开发服务器能启动但页面显示白屏 2. 页面无响应或卡死（可能是死循环） 3. 需要快速定位引入问题的具体 commit 4. 需要排除缓存、配置等干扰因素
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Debug by Commits
## 核心思想
当页面出现白屏或卡死时，通过 Git 回退到之前的 commit，逐个验证，快速定位问题引入点。
## 使用步骤
### 1. 保存当前工作
```bash
# 查看当前状态
git status --short
git log --oneline -10
# 保存当前工作（包括未跟踪文件）
git stash push -m "stash: debug 问题" --include-untracked
```
### 2. 确定检查范围
```bash
# 查看最近提交历史
git log --oneline -10
```
选择要回退的目标 commit（通常是已知正常的版本）。
### 3. 回退并清理
```bash
# 回退到指定 commit
git checkout <commit-hash>
# 清理依赖（关键！排除缓存干扰）
rm -rf node_modules .nuxt
# 杀掉残留进程
pkill -f "nuxt" || true
```
### 4. 安装依赖并测试
```bash
pnpm install && pnpm dev
```
让用户验证页面是否正常：
- **正常** → 问题在后面的 commit，继续向前检查
- **白屏/卡死** → 问题在这个 commit 或之前，继续往回检查
### 5. 二分定位
重复步骤 3-4，使用二分法快速缩小范围：
```
正常 ←——————————————————→ 白屏
↑
检查中间点
```
### 6. 定位问题 commit
找到第一个出现问题的 commit 后：
```bash
# 查看该 commit 的具体改动
git show <commit-hash>
# 查看改动的文件列表
git show <commit-hash> --stat
# 查看具体改动内容
git show <commit-hash> --no-patch
```
### 7. 修复问题
根据改动内容分析可能的问题。重点检查该 commit 引入的新代码：
**分析思路：**
1. 查看改动的文件数量和类型
2. 关注新增的逻辑、hooks、组件
3. 检查是否有新的异步操作或副作用
4. 对比正常版本和问题版本的差异
**不要预设立场** - 白屏可能由多种原因导致，需要根据具体改动分析，而不是套用固定模式。
### 8. 恢复工作
修复完成后，恢复之前 stash 的工作：
```bash
# 回到原分支
git checkout <branch-name>
# 恢复 stash
git stash pop
```
## 关键注意事项
1. **必须清理依赖** - 每次切换 commit 后都要删除 `node_modules` 和 `.nuxt`，排除缓存干扰
2. **杀掉残留进程** - 确保旧的 dev server 完全停止
3. **不要依赖截图** - 白屏问题需要用户实际验证，不能只看 snapshot
4. **关注用户反馈** - 用户说"不是缓存问题"时要相信，专注于代码本身
5. **保持开放** - 问题可能出现在任何地方，不要过早下结论
## 反思模板
定位到问题后，记录：
```
问题 commit: <hash>
问题文件: <file-path>
问题类型: <死循环/异步/生命周期/响应式/其他>
根本原因: <具体解释>
修复方案: <如何修复>
```Related Skills
rebase-commits
将零散的 commits 整合为清晰的逻辑提交，使 Git 历史更易读。 Use when: (1) 用户说 "rebase commits"、"整理提交历史"、"让历史更干净" (2) 用户想将多个相关 commits 合并为逻辑单元 (3) 完成一个功能后需要清理 commit 历史 (4) 提交历史混乱，需要重新组织
css-debug
Systematic CSS debugging. Covers specificity analysis, inheritance tracing, computed value inspection, layout debugging (overflow, unexpected sizing, collapsing margins), CSS containment issues, z-index stacking context mapping, custom property resolution chains, and paint/layout performance diagnosis. Uses outline technique for visual debugging. Use when debugging CSS, fixing layout bugs, resolving specificity conflicts, tracing z-index issues, or diagnosing rendering performance.
open-u-dashboard
open understand dashboard for user
sync-template-skill
这是一个技能文件的模板，展示了技能的基本结构和内容组织方式。
talk-humanize
Be direct and informative. No filler, no fluff, but give enough to be useful.
search-web
使用 Evaluator-optimizer 模式进行系统性多轮网络搜索，采用结构化 Ask 流程在搜索前澄清研究目标。基于 YC Office Hours 的提问方法论，确保搜索方向清晰、结果可验证。当用户需要深入调查复杂主题、验证假设或全面收集信息时使用。
save-to-eagle
归档网络内容到 Eagle 素材库。支持：(1) Behance/Pixiv 图片归档，(2) 网页视频录制（页面动画、滚动录制）。使用方式：'归档 [URL]' 归档图片；'录制网页视频 [URL]' 录制页面动画；'滚动录制 [URL]' 自动滚动截图。支持评分如 '归档 [URL], 3/5'。
save-ob-chaos
将对话内容快速存档到 Obsidian Chaos 文件夹。触发词："存档到 Obsidian"、"保存到 Chaos"、"ob 存档"、"记下这个"、"保存这段内容"、"存到 chaos"。
save-ob-chaos-mermaid
将 Mermaid 图表保存到 Obsidian Chaos 文件夹。触发词："保存 mermaid 到 chaos"、"mermaid 存档"。
save-ob-chaos-excalidraw
绘制 Excalidraw 图表并存档到 Obsidian Chaos 文件夹。触发词："画个图存到 Obsidian"、"excalidraw 存档"、"画个流程图保存"、"画图存到 chaos"、"创建图表并存档"、"画架构图到 ob"。
release-project
项目版本发布流程指导，帮助用户完成版本规划、Changelog 管理、版本号升级、Git 标签创建和 npm 首次发布准备。Use when: (1) 用户需要发布新版本 (2) 需要创建版本发布流程 (3) 需要管理版本号和 Changelog (4) 需要自动化版本发布 (5) 需要检查 release 分支同步 (6) 首次 npm 发布准备
recognize-codebase-branch-flow
识别并记忆项目 git 分支模型