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` 对应域下追加一条，**统一用这个格式**（保...