convez.ai
SkillProdutividadeIntermediário
sjyinzju

Pitfalls Lesson — Gerenciador de Experiências de Erro

sjyinzju/pitfalls-lesson-skill

Transforme cada erro em conhecimento reutilizável e automático

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-skill

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 后,以下规则立即生效,不依赖任何经验积累:

#类别规则
1PLATFORMnode --version 确认版本后再运行(Windows nvm 需重开终端)
2PLATFORM文件写入用 -Encoding utf8(PS 5.1 默认 UTF-16 LE)
3PLATFORM不用 && 链式命令(PowerShell 不支持)
4PLATFORM路径用正斜杠或双引号包裹
5DEP用 npm ci 而非 npm install
6BUILD构建失败先清缓存
7DEPengines 字段声明 Node 版本
8DOCKER修改 service 名称后全局搜索
9DOCKER数据库服务加 depends_on + healthcheck
10DB自动生成的迁移文件必须人工 review
11DB提交前跑通 upgrade → downgrade → upgrade
12ENV修改 .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.ps1Git 分析脚本(Windows)
project-pitfalls-skill/scripts/git-analyze.shGit 分析脚本(Linux/Mac)
claude-commands/analyze-git-lessons.md/analyze-git-lessons 命令定义
claude-commands/claude-md-snippet.mdCLAUDE.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 条通用规则安装即生效。开发中遇到新踩坑会自动捕获并积累。

Ver o original no GitHub

Bom para

Relacionados