将开发过程中的踩坑经验、解决方案、学习笔记系统化记录和检索，避免重复犯错，加速问题解决，构建个人/团队的知识资产。
- 解决了一个耗时较长的 Bug 后
- 学到了新的技术方案/工具用法
- 做了一个重要的技术决策后
- 遇到第三方服务的坑后
- 定期回顾和整理知识时
必须记录：
- 花了 > 1 小时才解决的问题
- 非显而易见的解决方案
- 第三方服务的坑/限制
- 环境相关的特殊配置
- 性能优化的具体方法和数据
- 架构决策及其理由
不需要记录：
- 搜索一下就能找到的基础信息
- 一次性的简单操作
- 已在官方文档中清晰说明的内容
踩坑记录：
# [问题标题]
## 症状
[看到了什么错误/现象]
## 环境
[OS/语言版本/框架版本/相关依赖版本]
## 根因
[最终发现的原因]
## 解决方案
[具体怎么修的，含代码片段]
## 教训
[下次如何避免/更快定位]
## 参考
[相关链接/文档]
日期：YYYY-MM-DD
标签：#数据库 #PostgreSQL #连接池技术方案记录：
# [方案标题]
## 场景
[什么情况下需要这个方案]
## 方案
[具体实现方式]
## 优缺点
- 优点：...
- 缺点：...
- 替代方案：...
## 示例代码
[关键代码片段]
日期：YYYY-MM-DD
标签：#缓存 #Redis目录结构：
knowledge/
├── bugs/ # 踩坑记录
│ ├── 2024-03-docker-network.md
│ └── 2024-04-jwt-expiry.md
├── solutions/ # 解决方案
│ ├── file-upload-s3.md
│ └── rate-limiting.md
├── decisions/ # 技术决策（ADR）
├── learnings/ # 学习笔记
└── index.md # 索引/标签汇总
标签系统：
- 按技术：#PostgreSQL #Docker #React #Nginx
- 按类型：#bug #方案 #决策 #性能
- 按模块：#认证 #支付 #部署
查找顺序：
- 先搜自己的知识库（可能之前遇到过）
- 再搜项目文档/ADR
- 然后搜外部资源（Google/StackOverflow/文档）
搜索技巧：
- 用错误信息关键词搜索
- 用标签过滤
- 按时间排序（最新的方案可能更适用）
每月（30 分钟）：
- 回顾本月新增的知识卡片
- 补充不完整的记录
- 标记已过时的内容
- 更新索引/标签
每季度：
- 清理过时内容
- 合并重复条目
- 提炼高频问题为 FAQ
- 将有价值的经验转化为团队规范
知识不只是记录，还要转化为行动：
- 反复出现的问题 → 写入代码审查清单
- 通用解决方案 → 抽取为工具函数/模板
- 重要教训 → 更新工作流/规范文档
- 频繁踩的坑 → 添加自动化检查
- 知识库目录结构已建立
- 知识卡片格式已确定
- 解决耗时问题后有记录习惯
- 标签/索引系统可用
- 每月回顾一次知识库
- 过时内容已标记/清理
- 高频经验已转化为规范/工具
| 输出物 | 格式 | 存放位置 |
|---|---|---|
| 知识卡片 | Markdown | knowledge/ 目录 |
| 索引/标签 | Markdown | knowledge/index.md |
| FAQ | Markdown | 官网 FAQ（website/app/faq/）或按需创建 docs/faq.md |
| 误区 | 正确做法 |
|---|---|
| 解决了就忘了 | 花 5 分钟记录，节省未来几小时 |
| 记录太简略 | 包含环境/根因/方案/教训 |
| 只记不回顾 | 定期回顾才能内化 |
| 知识散落各处 | 统一位置、统一格式 |
| 不标记过时内容 | 技术更新快，过时内容要标注 |