dev-pitfalls

🚀 一个用于初始化和管理项目坑点知识系统的 CLI 工具。

English | 简体中文

什么是坑点知识系统？

坑点知识系统是一个项目特定的技术知识库，帮助团队记录和查询那些需要多轮调试才能解决的棘手问题。通过记录这些"坑点"，你可以：

• ✅ 避免重复相同的调试过程
• ✅ 积累项目特定的技术知识
• ✅ 帮助新成员快速了解项目特点
• ✅ 识别需要改进的架构或配置问题

特性

• 📁 完整的目录结构，按分类组织坑点
• 📝 预配置的模板，确保文档一致性
• 🔍 可搜索的索引系统
• 🤖 与 Claude Code 集成，智能管理坑点
• 📚 完善的文档和示例
• ⚡ 一行命令完成初始化

安装

# 使用 npx（推荐，无需安装）
npx dev-pitfalls init

# 或全局安装
npm install -g dev-pitfalls
pitfalls init

使用方法

在新项目中初始化

cd your-project
npx dev-pitfalls init

这将创建：

• pitfalls/ - 主目录及分类子目录
• .claude/skills/pitfall/SKILL.md - 用于坑点管理的 Claude Code skill
• CLAUDE.md - 自动检测和查询坑点的配置（创建或更新）

命令选项

# 使用默认设置初始化（包含示例，遇到冲突时提示）
npx dev-pitfalls init

# 强制覆盖，不提示
npx dev-pitfalls init --force

# 跳过示例坑点
npx dev-pitfalls init --no-examples

# 组合选项
npx dev-pitfalls init --force --no-examples

生成的内容

目录结构

your-project/
├── pitfalls/
│   ├── .template.md          # 记录坑点的模板
│   ├── index.json            # 可搜索索引
│   ├── README.md             # 使用文档
│   ├── build/                # 构建相关坑点
│   ├── api/                  # API相关坑点
│   ├── component/            # 组件相关坑点
│   ├── config/               # 配置相关坑点
│   └── other/                # 其他坑点
├── .claude/
│   └── skills/
│       └── pitfall/
│           └── SKILL.md      # Claude Code skill
└── CLAUDE.md                 # 已更新或创建

示例坑点（可选）

包含示例时，你会获得 2 个示例坑点来理解格式：

1. 构建类: Vite 别名路径解析失败
2. 组件类: SSE 流式数据重连问题

与 Claude Code 一起使用

初始化后，你可以在 Claude Code 中使用 /pitfall 命令：

/pitfall record              # 记录新坑点
/pitfall search <关键词>      # 搜索坑点
/pitfall list                # 列出所有坑点
/pitfall list --category=build  # 按分类列出
/pitfall show <id>           # 查看坑点详情
/pitfall stats               # 查看统计信息
/pitfall help                # 显示帮助

自动功能

系统会自动：

• 检测潜在坑点 - 当调试需要多轮时
• 查询知识库 - 当错误发生时
• 建议相关方案 - 从过往坑点中

文档

初始化后，查看项目中的 pitfalls/README.md 了解：

• 详细使用说明
• 记录坑点的最佳实践
• 搜索和查询示例
• 贡献指南

何时记录坑点

应该记录:

• 非标准配置
• 框架特定的怪异行为
• 环境特定问题
• 不明显的错误原因
• 与官方文档不同的解决方案

不应记录:

• 通用知识（可在文档/StackOverflow找到）
• 简单的拼写错误或失误
• 用户特定环境问题
• 临时性问题（新版本已修复）

使用场景示例

场景1: 团队协作

团队成员在调试一个 Vite 构建问题时，花了2小时才找到原因。使用 /pitfall record 记录后，其他成员遇到相同问题时，系统会自动在坑点库中查询并提示解决方案，节省大量时间。

场景2: 新成员入职

新成员加入项目时，通过 /pitfall list 可以快速了解项目中常见的技术陷阱，避免重复踩坑。

场景3: 问题复盘

定期使用 /pitfall stats 查看高频问题，识别需要优化的架构或配置，从根本上解决反复出现的问题。

系统要求

• Node.js >= 16.0.0
• Claude Code（用于使用 /pitfall skill）

工作原理

1. 自动检测: 当 Claude Code 检测到对话轮次 > 5 且包含错误关键词时，会询问是否记录为坑点
2. 自动查询: 当错误发生时，自动在坑点库中搜索相关问题
3. 智能匹配: 通过标签、标题、分类计算相关度分数，返回最相关的解决方案

常见问题

Q: 坑点知识系统存在哪里？

A: 所有内容都存储在你的项目目录中的 pitfalls/ 文件夹，完全本地化，不依赖外部服务。

Q: 可以在多个项目中使用吗？

A: 可以！每个项目都有独立的坑点知识库，记录项目特定的技术问题。

Q: 如何备份坑点知识？

A: pitfalls/ 目录应该提交到 git 仓库，这样团队成员都能共享这些知识。

Q: 不使用 Claude Code 可以用吗？

A: 可以，但会失去自动检测和查询功能。你仍然可以手动管理 pitfalls/ 目录中的 markdown 文件。

Q: 如何迁移到新项目？

A: 如果新项目与旧项目技术栈相似，可以直接复制 pitfalls/ 目录，或使用 dev-pitfalls init 初始化后手动迁移相关坑点。

贡献

欢迎贡献！如果你有建议或发现 bug，请提交 issue 或 pull request。

许可证

MIT

作者

xinbaiyu

相关链接

• npm 包
• GitHub 仓库

更新日志

1.0.0 (2026-01-18)

• 🎉 首次发布
• ✨ 支持一键初始化坑点知识系统
• ✨ 支持 --force 和 --no-examples 选项
• ✨ 智能 CLAUDE.md 追加功能
• 📝 完整的文档和示例

用 ❤️ 为想从调试经历中学习的开发者打造