核心一句话
先搞懂这个项目是解决什么问题、整体架构怎么跑起来，再看它的最佳实践，不要一上来扎进细节代码。下面按优先级排序，你可以照着顺序看：
1. 先看文档（优先级最高，先不碰代码）
重点看这些文件：README.md、CONTRIBUTING.md、docs/、INSTALL.md
- 项目目标、适用场景、限制：它解决什么痛点？不适合什么场景？（很多项目有隐性边界，比如只适合学习、不适合生产）
- 快速启动流程：环境依赖、怎么安装、怎么跑 demo、需要什么配置
- 版本、依赖、许可证 License（非常重要！）
- MIT/Apache2.0 比较宽松；GPL 有传染性；商用一定要看许可证，避免侵权
- 项目状态：是否还在维护、issue 活跃度、有没有已知 bug、是否是废弃归档项目
很多新手上来直接看 src，看不懂就是因为跳过了这一步。
2. 理清项目结构（搞清楚模块划分，而不是逐行读）
看目录树，先建立全局视图：
src/ 源码
tests/ 测试
examples/demo/ 示例（最值得先跑！）
config/ 配置文件
docs/ 文档
scripts/ 构建/部署脚本重点思考：
- 它是怎么分层的？（比如前端：路由 / 组件 / 状态；后端：controller/service/model；嵌入式：驱动 / 业务 / 算法）
- 模块之间怎么解耦？谁依赖谁？
- 配置、日志、异常、工具函数单独抽出去了吗？（这就是工程化经验）
3. 跑通 Demo！（重中之重，验证理解）
先跑起来，再读代码，不要静态啃代码。
- 跟着文档跑官方示例，复现它的效果
- 故意改一点点参数、配置，看会发生什么，理解输入输出
- 看启动日志、报错信息，搞懂数据流：数据从哪进来、经过哪些模块、从哪输出
跑不通优先看 issues、discussions，这也是学习别人踩坑经验的方式。
4. 核心设计：它是怎么解决核心问题的（你最该吸取的经验）
等 demo 跑通，再定位核心逻辑，而不是工具类、胶水代码：
- 核心算法 / 核心能力在哪？（比如一个 Agent 项目：prompt 管理、工具调用；智能车：PID、图像二值化；web 项目：权限校验）
- 用了什么设计模式？为什么这么设计？（工厂、观察者、装饰器、依赖注入等）
- 怎么处理边界情况：异常、超时、重试、并发、缓存、资源释放
- 性能 / 稳定性方案：限流、异步、队列、内存管理（嵌入式重点看内存、资源有没有泄漏）
👉 区分：业务胶水代码（参考意义低） vs 核心框架 / 算法 / 架构（值得学习）
5. 工程化规范（非常适合拿来放到自己项目里）
这是很多人忽略、但提升很大的部分：
- 构建脚本：CMake、Makefile、package.json、requirements.txt、dockerfile
- 代码规范：linter、格式化（prettier、clang-format）
- 测试：单元测试、集成测试怎么写，怎么写断言
- CI/CD：github actions，自动编译、测试、打包
- 日志、错误码、配置管理、参数校验
这些是 "优秀项目" 和随便写的 demo 最大差距。
6. 看它的取舍和缺点（很关键，避免盲目抄）
不要默认它是完美的：
- 看 open issue：作者自己知道哪些短板？
- 看 PR 历史：大家在争论什么方案？为什么选 A 而不是 B？
- 思考：这个方案适合我的场景吗？有没有过度设计？（很多开源项目为了通用，复杂度很高，小项目照搬会很重）
7. 最后再看细节（按需）
看懂整体架构、核心流程之后，再去看具体函数、类的实现。 不要逐行通读整个仓库，绝大多数代码你不需要细看。
给你一套极简操作流程（你可以直接照着执行）
- 读 README → 确认 License、用途、维护状态
- 尝试跑 examples/demo，跑通
- 画一张简单流程图：数据流、模块依赖
- 定位核心模块，精读核心逻辑
- 学习它的工程规范（测试、构建、目录组织）
- 思考：哪些思路可以迁移到我自己的项目？哪些是它的场景专属，我不能抄？
避坑提醒
- ❌ 不要直接复制代码到自己项目里，先理解它的前提和约束
- ❌ 不要沉迷看花哨语法，优先看设计思想
- ❌ 不要选已经归档、多年不维护的项目当生产参考（学习语法可以，但不要借鉴它的工程方案）
- ✅ 优先看 star 高、活跃、有完整测试、文档齐全的项目