Pitfalls Lesson — Gerenciador de Experiências de Erro
sjyinzju/pitfalls-lesson-skill
Transforme cada erro em conhecimento reutilizável e automático
Ver no GitHubSkill que captura automaticamente erros e lições aprendidas durante o desenvolvimento, criando um repositório permanente de conhecimento. Claude memoriza os pitfalls do projeto entre sessões, evita repetição de erros e propõe automação de regras preventivas quando padrões se repetem.
Instalação
npx convez-ai sjyinzju/pitfalls-lesson-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Documentar bugs e erros recorrentes em projetos
- Prevenir repetição de erros em novas sessões de desenvolvimento
- Gerar regras automáticas para interceptar operações de alto risco
- Analisar histórico git para extrair lições de correções passadas
- Manter knowledge base compartilhável entre projetos
Veredito

Skill bem estruturado que resolve um problema real: a perda de contexto entre sessões do Claude Code. A implementação em PowerShell/shell é técnica e prática, com automação robusta (captura em 3 camadas, deduplicação por similaridade, análise de git). Recomendado para equipes que querem transformar erros recorrentes em regras preventivas permanentes.
README
A tradução para o português deste README ainda está na fila.
Project Pitfalls — Claude Code 踩坑经验管理 Skill
让 Claude Code 记住每一次踩坑,越用越懂你的项目。安装即用,自动运转,不需要记忆任何命令。
解决什么问题
Claude Code 的上下文在会话结束后清空。上周踩过的坑、排查了半小时才解决的报错、框架那个没说清楚的隐性行为——下次新开会话,Claude 全部忘记,你不得不再踩一遍。
这个 skill 把每次踩坑的代价转化为永久知识资产:
- 踩坑时:自动检测并记录(你不需要说"记一下")
- 新会话:自动加载已知教训,主动提醒你
- 高风险操作前:拦截并展示预防规则
- 反复踩坑:主动建议内化为专属 skill 自动拦截
- 跨项目:知识库文件可以复制到其他项目,通用教训直接生效
安装(2 步)
步骤 1:复制文件
将整个仓库复制到你项目的 .claude/ 目录下:
你的项目/
├── .claude/
│ ├── skills/
│ │ └── project-pitfalls/ ← 复制 project-pitfalls-skill/ 到这里
│ │ ├── SKILL.md
│ │ ├── references/
│ │ │ ├── lessons-template.md
│ │ │ └── pitfalls-skill-template.md
│ │ └── scripts/
│ │ ├── git-analyze.ps1
│ │ └── git-analyze.sh
│ ├── commands/
│ │ └── analyze-git-lessons.md ← 复制 claude-commands/analyze-git-lessons.md
│ └── lessons-learned.md ← 自动创建(首次会话)
├── CLAUDE.md ← 见步骤 2
└── ...
步骤 2:更新 CLAUDE.md
将 claude-commands/claude-md-snippet.md 的内容追加到你项目的 CLAUDE.md 末尾。
# 在项目根目录执行
cat claude-commands/claude-md-snippet.md >> CLAUDE.md
如果项目还没有
CLAUDE.md,直接创建并将 snippet 内容写入。
[可选] 步骤 3:配置 Stop Hook
将 settings-example.json 中的配置合并到 .claude/settings.json。Hook 的作用是会话结束时兜底检查遗漏的踩坑记录。不配置不影响 skill 正常运行。
验证安装
新开一个 Claude Code 会话。如果安装成功,Claude 会输出:
📝 已创建 .claude/lessons-learned.md,我会在开发过程中自动记录踩坑经验。
如何使用
日常开发(自动,不需要你做任何事)
你:帮我改一下 Docker Compose 的服务名
Claude:⚠️ 检测到高风险操作。
本项目的已知教训:[DOCKER] 改 service 名后未全局搜索(已发生 2 次)
预防规则:修改后 grep 搜索旧名称全局替换
是否继续?
你:继续
Claude:[执行修改...]
[自动 grep 搜索旧名称...]
📝 已自动更新命中记录
遇到报错(Claude 自动记录)
你:为什么接口一直 500?
Claude:[排查...] 是数据库迁移没有应用。
[修复...] alembic upgrade head
✅ 已解决。
📝 已记录:[DB] 迁移未应用导致接口 500(第 2 次出现)→ lessons-learned.md
手动命令(需要时)
| 你说 | Claude 做什么 |
|---|---|
/analyze-git-lessons 或 "分析 git 教训" | 从 git 历史挖掘修复提交,分类,去重,生成报告,询问是否内化为 skill |
| "记录这个坑" | 强制触发捕获(即使不符合自动检测条件) |
| "最近踩了哪些坑" | 展示分类汇总 |
| "检查失效" | 扫描长期未触发的条目,询问是否标记为过时 |
| "我们升级了 Next.js 15" | 检查涉及 Next.js 的条目是否仍适用 |
反复踩坑(Claude 主动提醒)
你:又报这个错了...
Claude:⚠️ "[DB] 迁移未应用" 已发生 3 次!
建议内化为专属 skill 规则以自动拦截。
是否需要我现在生成?[回复 Y/N]
你:Y
Claude:✅ 已生成 .claude/skills/yourproject-pitfalls/SKILL.md
包含 3 条内化规则。后续开发中遇到相关操作会自动拦阻。
作用机制
三条核心链路
链路 1(预防)─ 会话开始时自动运行
│
├── 读取 .claude/lessons-learned.md 的"预防速查表"(紧凑表格,<500 tokens)
├── 匹配当前任务与已知教训(按技术栈、操作类型、文件路径)
├── 有匹配 → 在第一条回复中主动提醒
└── 内置 12 条通用规则安装即生效(不依赖 lessons-learned.md)
链路 2(捕获)─ 开发过程中自动触发
│
├── 检测对话信号(A 级:报错反复/用户纠正 Claude → 强制捕获)
│ (B 级:多轮排查/方案被纠正 → Claude 判断后决定)
│ (C 级:拼写错误/功能开发 → 跳过)
├── 提取症状、排查路径、根因、解决方案、预防规则
├── 去重检查(四维相似度计算,≥80% 合并)
├── 三源融合评估严重度(对话信号 + 频次 + 问题性质)
└── 写入 lessons-learned.md + 更新预防速查表
链路 3(回顾)─ 用户手动或系统提醒触发
│
├── 阶段 1:Claude 逐条阅读 git 提交标题(语义判断,非 grep 关键词)
├── 阶段 2:对可疑提交执行 git show,Claude 阅读 diff 做语义分析
├── 阶段 3:按 10 类体系分类 + 标记 scope
├── 阶段 4:去重合并(四维相似度 + 六种边界情况处理)
├── 阶段 5:三源融合评估严重度
├── 阶段 6:生成结构化报告
└── 阶段 7:用户选择 Y/N/S/D → 生成专属 skill 或更新知识库
四层触发保障
Layer 1 — CLAUDE.md(每次会话必定加载)
→ 会话开始预防 + 开发中自动捕获 + 高风险操作拦阻
Layer 2 — Skill Description(会话中智能匹配)
→ 用户提踩坑关键词时自动调用
Layer 3 — Stop Hook(可选,会话结束安全网)
→ 检查遗漏的踩坑记录
Layer 4 — 阈值报警(开发中实时触发)
→ 同一错误 ≥3 次主动建议内化
踩坑知识库文件
.claude/lessons-learned.md 是整个系统的唯一数据源。结构:
┌──────────────────────────────────┐
│ 预防速查表(会话必读,<500 tokens)│
│ 紧凑表格:类别 | 标题 | 预防规则 │
│ | 出现次数 | scope | 状态 │
├──────────────────────────────────┤
│ 详细记录(按需读取) │
│ 每条包含: │
│ 症状 → 排查路径 → 根因 → 解决方案 │
│ → 预防规则 → 相关文件 → 关联提交 │
└──────────────────────────────────┘
条目字段:date, category, severity, scope, source_project, tags, status, occurrence_count, hit_count, last_hit
跨项目复用
将 .claude/lessons-learned.md 复制到另一个项目的 .claude/ 目录:
scope: universal的条目 → 直接生效,自动纳入预防规则scope: project-specific的条目 → 作为参考,标注来源,用户确认后本地化- 被 ≥3 个项目验证的条目 → 标注"高置信度"
踩坑分类体系
| 类别 | 名称 | 典型场景 |
|---|---|---|
ENV | 环境配置 | Node 版本、Python venv、PATH、环境变量 |
DEP | 依赖冲突 | npm peer dependency、pip 版本冲突 |
FRAMEWORK | 框架陷阱 | Next.js App Router 行为、Pydantic v2 变更 |
PLATFORM | 平台差异 | PowerShell vs bash、CRLF/LF、路径分隔符 |
DB | 数据库/迁移 | Alembic 迁移、nullable 变更、外键约束 |
ASYNC | 异步/并发 | asyncio 事件循环、race condition |
DOCKER | 容器/网络 | 服务发现、端口映射、健康检查 |
AUTH | 认证/授权 | JWT 过期、CORS 配置、中间件顺序 |
BUILD | 构建/打包 | Turbopack 缓存、webpack loader |
OTHER | 其他 | 不属于以上类别。积累 ≥3 条同类后可提议新类别 |
严重度评估
严重度由三个维度综合判定(文件变更数量不参与):
- 对话信号分(权重最高):用户说"又报错了" → critical;排查 ≥5 轮 → high
- 频次分:occurrence_count ≥3 → high+
- 性质分:安全问题 → critical;框架陷阱 → high
内置通用规则(安装即生效)
安装 skill 后,以下规则立即生效,不依赖任何经验积累:
| # | 类别 | 规则 |
|---|---|---|
| 1 | PLATFORM | node --version 确认版本后再运行(Windows nvm 需重开终端) |
| 2 | PLATFORM | 文件写入用 -Encoding utf8(PS 5.1 默认 UTF-16 LE) |
| 3 | PLATFORM | 不用 && 链式命令(PowerShell 不支持) |
| 4 | PLATFORM | 路径用正斜杠或双引号包裹 |
| 5 | DEP | 用 npm ci 而非 npm install |
| 6 | BUILD | 构建失败先清缓存 |
| 7 | DEP | engines 字段声明 Node 版本 |
| 8 | DOCKER | 修改 service 名称后全局搜索 |
| 9 | DOCKER | 数据库服务加 depends_on + healthcheck |
| 10 | DB | 自动生成的迁移文件必须人工 review |
| 11 | DB | 提交前跑通 upgrade → downgrade → upgrade |
| 12 | ENV | 修改 .env 后检查 .env.example |
文件说明
| 文件 | 用途 |
|---|---|
project-pitfalls-skill/SKILL.md | 主 skill 定义(完整工作流) |
project-pitfalls-skill/references/lessons-template.md | 知识库文件模板 |
project-pitfalls-skill/references/pitfalls-skill-template.md | 专属 skill 生成模板 |
project-pitfalls-skill/scripts/git-analyze.ps1 | Git 分析脚本(Windows) |
project-pitfalls-skill/scripts/git-analyze.sh | Git 分析脚本(Linux/Mac) |
claude-commands/analyze-git-lessons.md | /analyze-git-lessons 命令定义 |
claude-commands/claude-md-snippet.md | CLAUDE.md 安装片段 |
settings-example.json | 可选 Stop hook 配置 |
常见问题
Q: 安装后需要手动做什么? A: 不需要。新会话自动加载,开发中自动捕获。只有两种情况下你会意识到它的存在:(1) 它提醒你已知风险时 (2) 你想主动分析 git 历史时。
Q: 知识库会不会变得很大? A: 不会。去重引擎自动合并相同问题。预防速查表在会话开始时只读紧凑表格(<500 tokens),详情按需加载,不会浪费 token。
Q: 可以跨项目复用吗?
A: 可以。将 .claude/lessons-learned.md 复制到其他项目的 .claude/ 目录。通用教训直接生效,项目专属教训作为参考展示。被多个项目验证的条目会标注"高置信度"。
Q: 同一个文件频繁改动(如 package.json),会不会被误判为频繁踩坑? A: 不会。去重引擎按 category + 根因关键词 + 文件路径三重匹配,功能迭代的提交不会被识别为踩坑。且文件数量不参与严重度评估。还有"枢纽文件排除规则"——同一文件出现在 ≥3 条不同 category 的条目中 → 自动跳过其影响范围加成。
Q: 没有 git 历史的新项目能用吗? A: 能。内置 12 条通用规则安装即生效。开发中遇到新踩坑会自动捕获并积累。