代码知识库

🏦 场景与客户

一家 SaaS 公司，主力产品代码量 80 万行，团队 30 人。新人入职第一周基本都是读代码：为什么这个模块这么设计、那个历史包袱为什么不能动，全靠问人。老员工被反复打断，新人两个月还不敢改核心模块。

客户要的是把「代码背后为什么这么做」沉淀下来——不是 API 文档，而是决策与约束。

📅 实施节奏

• 第 1–2 周：按模块梳理关键设计决策（为什么选这个存储、为什么不用消息队列）
• 第 3 周：整理历史踩坑与不可动的红线（哪些表不能直接改、哪些接口有隐性依赖）
• 第 4 周：接入开发流程，代码评审时强制关联相关知识条目
• 第 5 周起：把常见故障排查步骤做成对照表，值班时直接查

🗝️ 方案要点

• 写决策不写用法：调用方式 IDE 就能看，知识库要写的是「当时为什么这么选、什么条件下可以推翻」
• 红线清单单独维护：把「动之前必须知道」的约束列成短清单，新人第一周必读
• 与代码同仓管理：知识条目放在仓库里随代码走，改代码时要一起改，避免文档与实践脱节
• 错误信息可检索：把常见报错与处置办法做成索引，值班时搜报错原文就能出方案

⚖️ 选型与权衡

🚧 实施难点与排查

• 写成流水账：初版把 git log 抄了一遍，没用。改为只写「非显而易见的决策」
• 文档与代码脱节：改了实现没改文档，半年后误导人。把文档更新纳入评审检查项
• 红线没人看：新人没读就改，出过事故。改为入职必读 + 上线前抽查
• 历史无人补：老模块没文档，做法是「谁改谁补」，只补改动的部分，不追求一次性补齐

💵 成本与收益

• 成本：梳理约 2 人 × 4 周（可与日常开发并行）
• 收益：新人上手周期明显缩短；核心模块的误改事故减少
• 隐性收益：老员工被打断的次数下降，深度工作时间变多

🛡️ 风险与保障

• 保密：涉及核心算法的内容按权限隔离
• 准确性：文档随代码版本走，过期内容会被评审发现
• 边界：知识库不替代测试与代码评审，只是补充上下文

♾️ 可复用与演进

• 可复用到运维手册、发布流程、架构决策记录（ADR）
• 演进方向：把故障处置记录自动关联到对应代码模块，值班时一键直达
• 再进一步：新人任务从历史 issue 里挑，边做边补文档，形成正循环