# 踩坑库（PITFALLS）

> 记录项目开发中踩过的坑，把「血的教训」变成「可执行规则」。
> 与 [DECISIONS.md](DECISIONS.md)（为什么这样定）互补。

---

## 踩坑库哲学

1. **一个坑只踩一次** — 同一坑第二次出现，说明规则没写进文档
2. **不写「小心」——写「规则」** — 每条必须给出可执行的避免方案
3. **踩坑 ≠ 甩锅** — 对事不对人的知识资产
4. **同类问题出现第三次，必须写入 PITFALLS**

---

## 标准条目格式

```
### P-NNN：{踩坑名称}

| 项 | 内容 |
| -- | ---- |
| **现象** | 用户/开发者看到了什么异常？ |
| **后果** | 实际造成了什么损失/阻塞？ |
| **根因** | 为什么会发生？（技术/流程/认知层面） |
| **规则** | 以后怎么做来避免？必须是可执行的指令 |
| **关联** | 相关 DECISIONS / PITFALLS 编号（可选） |
```

---

## 通用踩坑（任何项目都可能遇到）

### P-001：API Key / 密钥进入版本库

| 项 | 内容 |
| -- | ---- |
| **现象** | `.env`、配置文件含明文密钥被 `git commit` |
| **后果** | 密钥泄露，需轮换所有凭证 |
| **规则** | `.env` 加入 `.gitignore`；仅 `.env.example` 留占位符；`git add` 前检查 |

### P-002：New Chat 范围漂移

| 项 | 内容 |
| -- | ---- |
| **现象** | 一次 AI 会话同时处理多个不相关任务（UI + 后端 + 部署 + 文档） |
| **后果** | 交付质量下降，上下文混乱，返工率高 |
| **规则** | 每次会话只做 STATUS「当前焦点」一件事；多任务时主动确认优先级 |

### P-003：收工只改代码不更新文档

| 项 | 内容 |
| -- | ---- |
| **现象** | 有 git 变更但未更新 `docs/STATUS.md` 或 `PITFALLS.md` |
| **后果** | 下一个 AI / 同事不知道进度，可能重复工作或踏进同一个坑 |
| **规则** | 功能模块完成后更新 STATUS；新踩坑立即记入 PITFALLS |

### P-004：AI 闷头猜需求导致返工

| 项 | 内容 |
| -- | ---- |
| **现象** | 用户说「加个搜索功能」，AI 直接写 200 行代码，用户说「我要的不是这个」 |
| **后果** | 双方浪费时间，AI 信任度下降 |
| **规则** | 模糊需求先确认范围、给出 2～3 个方案让用户选；确认后再动手 |

### P-005：AI 顺手重构无关代码

| 项 | 内容 |
| -- | ---- |
| **现象** | AI 在修一个 bug 时「顺便」重构了整个模块、改了变量名、调整了目录结构 |
| **后果** | 引入新 bug，PR 难以 review，与并行分支冲突 |
| **规则** | 最小改动原则：只改和本次任务直接相关的代码；重构需求单独提 |

### P-006：AI 编造数据 / 验收结论

| 项 | 内容 |
| -- | ---- |
| **现象** | AI 说「测试全部通过」「已部署成功」，但实际没有运行过 |
| **后果** | 用户基于虚假信息做决策，生产事故风险 |
| **规则** | 没见过的不说「已完成」；无数据写「数据待补充」；给出可验证的命令 |

### P-007：多 AI 工具规则冲突

| 项 | 内容 |
| -- | ---- |
| **现象** | 同时配置 Cursor `.mdc`、Copilot `instructions.md`、Claude `CLAUDE.md` 但内容不一致 |
| **后果** | 不同工具执行不同规则，输出不一致 |
| **规则** | `AGENTS.md` 为唯一真相源；工具专属规则从 AGENTS 自动生成，不手动维护多份 |

---

## 如何新增条目

每次踩坑后花 2 分钟按标准格式记录：

```
### P-XXX：{简短标题}

| 项 | 内容 |
| -- | ---- |
| **现象** | … |
| **后果** | … |
| **根因** | … |
| **规则** | … |
| **关联** | … |
```

> **提示**：在 AI 对话中说「这个坑记到 PITFALLS」即可让 AI 帮你按格式整理。