ChildHood/docs/knowledge/README.md

经验知识库

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 的「主题文件」表里登记。