---

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/网盘同步区

查不到对应坑 ≠ 没坑，只是本库还没收。但凡库里有，就别再用血换一次。

---

查（默认动作）

1. 按当前要干的活，定位 LIBRARY.md 里对应的域（## 一级标题）。
2. 扫该域下的坑条（每条一个 ### 标题 = 一句话坑名），挑和当前操作相关的。
3. 照「正确做法」改写你即将执行的命令 / 代码，再执行。

LIBRARY.md 刻意做窄、做高信号：只收真·反复踩 + 可泛化的坑。宁可少而准，不要堆成读不完的百科。

---

加（踩到新坑时）

判断标准：这条坑是「单项目」还是「通用工程」?

• 单项目（只对这个项目的技术栈 / 领域 / 业务成立）：留在项目自己的记忆里（用 stash），不进本库。
• 通用工程（换个项目、换个人也会踩，与具体业务无关）：进本库。

加的时候，在 LIBRARY.md 对应域下追加一条，统一用这个格式（保证全库一致、可扫）：

### <一句话把坑说清>
- **症状**：<不报错但给错结果的现象，或具体报错信息>
- **根因**：<为什么会这样>
- **正确做法**：<怎么绕开，给可直接抄的命令/写法>
- **触发场景**：<什么情况下会撞上>（可选）

写库条的红线：

1. 只写通用知识，不写任何项目/客户/雇主的具体信息（域名、IP、账号 ID、主机名、私有仓名、人名一律抽象成占位符）。本库是公开作品（进 personal-skills 仓），committed 即可被检索缓存。
2. 不写 key / secret / 凭证 / PII。
3. 一条坑一个 ###，放进最贴切的那个域；域不够用了再加 ## 新域。

---

三层提纯阶梯（本库在中间一层）

坑按「局部性」分三层，本库是中间那层。理解这个阶梯，才知道什么进本库、什么不进：

层	是什么	存哪	谁投递
单项目坑	只对单个项目成立	该项目自己的 memory（stash 写）	项目内 session 自动加载
通用工程坑	任何项目都可能踩	本库 LIBRARY.md	高危活前主动查（本 skill）
全局铁律	最高频最致命的少数几条	全局 ~/.claude/CLAUDE.md	每个 session 自动加载

提纯方向：项目里踩到坑，判断可泛化，升进本库；本库里被反复查到、最致命的那几条，再蒸馏一句进全局 CLAUDE.md（always-on）。越往上越贵、越要克制：全局只放「每次都该记得」的极少数，本库放长尾。

---

关联

• stash：记项目本地记忆的 skill。两者分工 = stash 管「这个项目的事」，pitfalls 管「所有项目都该知道的工程坑」。踩到坑时先问一句「这是单项目还是通用」，决定进哪边。
• 全局 ~/.claude/CLAUDE.md：阶梯顶层。本库里被验证最致命的坑，蒸馏一句上去当 always-on 铁律。