# Pitfalls

> 跨项目复用的通用工程踩坑库速查。在写 bash/shell 脚本、改 git 历史、做 macOS 文件/locale 相关操作、写正则/grep、配 DNS/Docker/反向代理部署、用 Read/Edit 改大文件之前，先查 LIBRARY.md，避免在新项目里重踩别的项目早就踩过的坑；也用于把新踩到的「通用工程坑」按统一格式加进库。触发：/pitfalls、「查坑 / 避坑 / 这类坑查一下」，以及上述高危操作前主动自查。

- Skill: `iyuenan3/pitfalls` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add iyuenan3/pitfalls`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iyuenan3/pitfalls/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: iyuenan3 (https://skillmd.com/u/iyuenan3)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iyuenan3/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` 对应域下追加一条，**统一用这个格式**（保证全库一致、可扫）：

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

写库条的红线：

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 铁律。