| name | pitfalls |
| description | 跨项目复用的通用工程踩坑库速查。在写 bash/shell 脚本、改 git 历史、做 macOS 文件/locale 相关操作、写正则/grep、配 DNS/Docker/反向代理部署、用 Read/Edit 改大文件之前，先查 LIBRARY.md，避免在新项目里重踩别的项目早就踩过的坑；也用于把新踩到的「通用工程坑」按统一格式加进库。触发：/pitfalls、「查坑 / 避坑 / 这类坑查一下」，以及上述高危操作前主动自查。 |
pitfalls：通用工程踩坑库
同一个坑，不该让不同项目各踩一遍。
这是一个跨项目复用的「通用工程坑」精选库。一个项目踩过、抽象出来的坑，进了这里，之后任何项目动同类活之前查一眼就能绕开。
单人同时跑很多项目时，最浪费的不是写代码，是在 B 项目重踩 A 项目三周前已经踩明白的坑。每个项目的 Claude 记忆是项目隔离的，A 项目 memory 里的教训，B 项目的 session 默认看不见。这个 skill 就是那条跨项目的「共享记忆」。
核心纪律：它是 pull 模型，该查的时候真去查才有用
这个库不会自动弹出来。它的全部价值取决于「在快要踩坑的那一刻，你真的来查了」。所以只有一条铁律：
干下面这几类「高危活」之前，先扫一眼 LIBRARY.md 对应域。
⚠️ 装好这个 skill 后，请在全局 ~/.claude/CLAUDE.md 里加一句 always-on 纪律（如「写 bash / 改 git 历史 / macOS 文件/locale 操作 / 配 DNS·Docker·反代 / Read·Edit 改大文件前，先查 pitfalls」）。skill 的 description 只给 harness 一个主动想起本 skill 的机会，对「正要写 heredoc」这种当下时刻并不可靠；这条全局纪律才是让 pull 模型稳定在对的时刻触发的关键（没有它，就只能靠你显式 /pitfalls）。
高危域（= 本库覆盖的域，也写进 description，给 harness 一个在这些活儿出现时主动浮现本 skill 的机会；但如上所述不可靠，需靠全局纪律兜底）：
| 域 | 典型动作 |
|---|
| Claude Code 工具 | 用 Read/Edit 改大文件、靠 grep 的返回值做判断 |
| Bash / Shell | 写脚本、heredoc、管道里用 grep/lsof 等命令的退出码 |
| macOS 特有 | grep/sed 处理中文、写校验脚本、装 Python 包、判断目录存在 |
| Git | 删除 + 修改混合提交、改历史、批量 add |
| 部署 / 基础设施 | 新子域配 HTTPS、Docker pull、配反向代理 |
| 文件同步 | 把开发项目放进 iCloud/网盘同步区 |
查不到对应坑 ≠ 没坑，只是本库还没收。但凡库里有，就别再用血换一次。
查（默认动作）
- 按当前要干的活，定位
LIBRARY.md 里对应的域（## 一级标题）。
- 扫该域下的坑条（每条一个
### 标题 = 一句话坑名），挑和当前操作相关的。
- 照「正确做法」改写你即将执行的命令 / 代码，再执行。
LIBRARY.md 刻意做窄、做高信号：只收真·反复踩 + 可泛化的坑。宁可少而准，不要堆成读不完的百科。
加（踩到新坑时）
判断标准：这条坑是「单项目」还是「通用工程」?
- 单项目（只对这个项目的技术栈 / 领域 / 业务成立）：留在项目自己的记忆里（用 stash），不进本库。
- 通用工程（换个项目、换个人也会踩，与具体业务无关）：进本库。
加的时候，在 LIBRARY.md 对应域下追加一条，统一用这个格式（保证全库一致、可扫）：
### <一句话把坑说清>
- **症状**：<不报错但给错结果的现象，或具体报错信息>
- **根因**：<为什么会这样>
- **正确做法**：<怎么绕开，给可直接抄的命令/写法>
- **触发场景**：<什么情况下会撞上>（可选）
写库条的红线：
- 只写通用知识，不写任何项目/客户/雇主的具体信息（域名、IP、账号 ID、主机名、私有仓名、人名一律抽象成占位符）。本库是公开作品（进 personal-skills 仓），committed 即可被检索缓存。
- 不写 key / secret / 凭证 / PII。
- 一条坑一个
###，放进最贴切的那个域；域不够用了再加 ## 新域。
三层提纯阶梯（本库在中间一层）
坑按「局部性」分三层，本库是中间那层。理解这个阶梯，才知道什么进本库、什么不进：
| 层 | 是什么 | 存哪 | 谁投递 |
|---|
| 单项目坑 | 只对单个项目成立 | 该项目自己的 memory（stash 写） | 项目内 session 自动加载 |
| 通用工程坑 | 任何项目都可能踩 | 本库 LIBRARY.md | 高危活前主动查（本 skill） |
| 全局铁律 | 最高频最致命的少数几条 | 全局 ~/.claude/CLAUDE.md | 每个 session 自动加载 |
提纯方向：项目里踩到坑，判断可泛化，升进本库；本库里被反复查到、最致命的那几条，再蒸馏一句进全局 CLAUDE.md（always-on）。越往上越贵、越要克制：全局只放「每次都该记得」的极少数，本库放长尾。
关联
- stash：记项目本地记忆的 skill。两者分工 = stash 管「这个项目的事」，pitfalls 管「所有项目都该知道的工程坑」。踩到坑时先问一句「这是单项目还是通用」，决定进哪边。
- 全局
~/.claude/CLAUDE.md：阶梯顶层。本库里被验证最致命的坑，蒸馏一句上去当 always-on 铁律。
