# 经验知识库

> ChildHood 项目的「经验知识库」——记录踩过的坑、根因、避坑做法、临时方案。
> 与 `docs/` 其他目录的区别：`design/`/`technical/`/`art/` 是**设计知识**（要做什么、怎么设计），本库是**经验知识**（踩过什么坑、怎么避开）。

## 这是什么

每次修 bug 或做复杂改动时，**问题分析和修复记录挂在 Gitea issue 上**（事务性，随 issue 归档）。但有些坑值得长期保留——关闭的 issue 不会再被翻，同类坑会反复踩。**本库就是这些长期经验的精选集**。

只有「会复发的、非显而易见的、值得未来的自己或别人避让的」才进本库。一次性事务不必沉淀。

## 目录结构

| 文件 | 用途 |
|------|------|
| `INDEX.md` | 总索引——所有条目一览，AI/人快速扫描的入口 |
| `临时方案登记.md` | 技术债看板——所有「临时方案」集中登记，每条带「何时转正」 |
| `坑-<主题>.md` | 按主题归集的坑（`坑-UE5引擎` / `坑-性能` / `坑-美术资产` / `坑-配置`…） |

## 何时写一条知识条目

修复一个问题后，问自己（`problem-solving` skill 会自动问）：

- 这个坑**会复发**吗？（换个人、换个系统会不会再踩）
- 根因**非显而易见**吗？（光看代码看不出来）
- 当前是**临时方案**吗？（需要标记未来转正）

**任一为是** → 提炼一条进对应主题文件 + 更新 `INDEX.md`。

## 怎么写（条目模板）

```
### [K-XXX] 标题
- 来源: Gitea issue #XX（或 偏差报告 / 审查记录）
- 症状: 现象是什么
- 根因: 为什么会这样
- 避坑做法: 应该怎么做（这是条目的核心价值）
- 状态: ✅正式方案 / ⚠️临时方案（预计转正时机：…）
- 关联: [[系统-技术方案]]、相关代码位置 file:line
```

- ID 用 `K-001`、`K-002` 递增（全库统一编号，不分主题）。
- **临时方案**条目同时登记到 `临时方案登记.md`。

## 怎么检索

- **人**：看 `INDEX.md` 一览，或直接翻主题文件。
- **AI**：动手改某系统前，先读 `INDEX.md` 判断有没有相关坑。`problem-solving` skill 会自动做这步。

## 新增主题文件

坑多了就开新主题文件（如 `坑-性能.md`），命名 `坑-<主题>.md`，并在 `INDEX.md` 的「主题文件」表里登记。