AI 项目学习工作流：用 Claude 系统性地学习一个项目的源码

为什么需要这套工作流

学习一个新项目的源码，最常见的问题是：

1. 没有方向感——打开项目一堆文件，不知道从哪看起
2. 看了就忘——读了半天代码，关上编辑器什么也没沉淀下来
3. 深浅失衡——要么浮在表面看个 README 就结束，要么一头扎进细节出不来
4. 跨会话断裂——和 Claude 聊了几轮分析得很透彻，新开一个对话全部从零开始

这套工作流把「学习一个项目」拆解为 5 个递进的 Phase，每个 Phase 有明确的输入、执行步骤和产出文件。所有产出都落到 Obsidian 文件系统中，天然支持跨会话恢复。

---

工作流全貌

Phase 1          Phase 2         Phase 3            Phase 4          Phase 5
项目概览与定位 → 架构分析 →   代码精读与实践验证 → 知识提炼与对比 → 输出与沉淀
  ↓                ↓                ↓                  ↓               ↓
项目信息卡片     模块结构图       精读笔记            架构决策提炼     学习总结
学习目标清单     设计模式清单     实践验证记录        可复用模式       博客草稿
学习价值评估     数据流分析       踩坑汇总            横向对比分析     后续行动项

不必每次都走完全程——工作流支持 4 种学习模式：

模式	路径	适用场景
完整模式	1 → 2 → 3 → 4 → 5	深度学习、系统掌握
速览模式	1 → 2 → 5	快速了解项目全貌
精读模式	1 → 3 → 4	带着具体问题学习
对比模式	1 → 2 → 4	技术选型评估

---

如何激活工作流

每次新对话开始时，将以下内容粘贴给 Claude：

请读取以下工作流文档后进入项目学习模式：
- 学习内容维护规则：<学习内容维护规则文件路径>

项目学习文件夹：<当前学习项目的绝对路径>
项目类型：<业务项目 / 架构工具项目 / 开源项目>（不填则 Claude 自动判断）
学习模式：<完整 / 速览 / 精读 / 对比>（不填默认完整模式）
当前 Phase：<Phase 名称>（不填则 Claude 自动扫描 MOC 判断）

Claude 启动后会自动扫描 Root MOC 中各 Phase 的 taskStatus，定位到当前进度，按需加载对应的 Phase 文档和项目类型差异化指引，然后输出状态摘要等待确认。

关键设计：按需加载——Claude 不会一次性读取全部工作流文档（约 3 万字），而是只加载「维护规则 + 当前 Phase 文档 + 对应类型指引」，把上下文窗口留给真正重要的项目代码分析。

---

一、文件夹结构

以学习 Spring Gateway 为例：

x.x.x.1/                                    # 项目学习根目录
├── 学习-Spring Gateway.md                    # Root MOC（唯一入口）
├── x.x.x.1.0/                              # 外部素材/原始资料
│   ├── Spring-Gateway-README.md
│   ├── Spring-Gateway-官方文档摘要.md
│   └── Spring-Gateway-相关文章.md
├── x.x.x.1.1/                              # Phase 1 产出
│   └── Spring-Gateway-项目概览.md
├── x.x.x.1.2/                              # Phase 2 产出
│   ├── Spring-Gateway-架构分析.md
│   ├── x.x.x.1.2.1/
│   │   └── Spring-Gateway-Filter链分析.md    # 按模块拆分子文件
│   └── x.x.x.1.2.2/
│       └── Spring-Gateway-路由机制分析.md
├── x.x.x.1.3/                              # Phase 3 产出
│   ├── Spring-Gateway-代码精读.md
│   └── Spring-Gateway-实践验证.md
├── x.x.x.1.4/                              # Phase 4 产出
│   ├── Spring-Gateway-知识提炼.md
│   └── Spring-Gateway-对比分析.md
└── x.x.x.1.5/                              # Phase 5 产出
    ├── Spring-Gateway-学习总结.md
    └── Spring-Gateway-博客草稿.md

Root MOC 是整个学习项目的控制中心，包含项目信息、学习进度表和当前进度快照。

---

二、五个 Phase 详解

Phase 1：项目概览与定位

目标：快速建立整体认知，明确学习方向，判断是否值得深入。

核心步骤：

1. 收集项目基本信息——名称、技术栈、规模、活跃度、文档质量，形成项目信息卡片
2. 判定项目类型——业务项目(A)、架构工具项目(B)、开源项目(C)，不同类型后续各 Phase 的侧重点不同
3. 设定学习目标——回答三个问题：为什么学？学什么？学到什么程度？输出 3-5 条可衡量的目标
4. 学习价值评估——从相关性、难度匹配、可迁移性、时效性、独特性五个维度打分（总分 < 10 建议重新考虑）

产出：<项目名>-项目概览.md

这一步的价值在于先想清楚再动手。很多人拿到项目就开始翻代码，花了三天发现这个项目不适合自己学，或者学的方向和真正需要的不一致。

---

Phase 2：架构分析

目标：系统性地理解项目架构——模块划分、设计模式、依赖关系、数据流。

核心步骤：

1. 项目结构扫描——输出带职责标注的模块结构图，区分核心模块和辅助模块
2. 核心设计模式识别——检查创建型、结构型、行为型、架构型、并发型五类模式，记录位置和用途
3. 依赖关系分析——外部依赖清单、内部模块调用关系、依赖注入方式、是否遵循分层规则
4. 数据流与控制流分析（架构级）——选 2-3 个关键场景，追踪组件→组件的流向，不深入方法级别
5. 部署架构分析——分为基础（构建流程+配置管理，必做）和进阶（部署拓扑+可观测性+发布策略，视信息可获取性决定）
6. 架构决策识别——整理为 ADR 格式：为什么选这种方案？trade-off 是什么？

产出：<项目名>-架构分析.md，可按模块拆分为子文件

Phase 2 的数据流分析聚焦架构级（组件→组件），代码级的方法调用链跟踪留到 Phase 3。这个边界划分是为了让 Phase 2 保持「高空视角」，不至于陷入细节。

---

Phase 3：代码精读与实践验证

目标：深入阅读核心代码，理解关键实现细节，通过动手验证加深理解。

这个 Phase 分为两个部分：

Part A：代码精读

1. 确定精读范围——根据学习目标和 Phase 2 的分析，选定 3-5 个精读入口点（启动流程 > 核心链路 > 核心抽象 > 关键算法 > 扩展点）
2. 逐模块精读——每个模块记录：文件路径、职责、关键方法表、设计亮点、疑问（标记待验证）
3. 关键流程跟踪（代码级）——从入口方法逐步跟入，记录调用链、数据变换、分支逻辑、异常处理
4. 代码质量观察——顺带观察命名、抽象层次、异常处理、日志、测试、注释

Part B：实践验证

5. 环境搭建与运行——记录过程中的所有坑
6. 调试关键流程——在关键节点设断点，验证阅读时的理解是否正确
7. 构建部署与运维观察（可选）——如果 Phase 2 已分析过部署架构，这里侧重动手验证
8. 小规模修改实验——设计 1-3 个实验：行为验证、功能扩展、边界测试、故障注入

产出：<项目名>-代码精读.md + <项目名>-实践验证.md

实践验证是这套工作流和纯「看代码」最大的区别。”以为理解了”和”真的理解了”之间往往隔着一次断点调试。

---

Phase 4：知识提炼与对比

目标：从项目中提炼可迁移的知识，与同类方案横向对比，形成自己的技术判断力。

核心步骤：

1. 回顾前序产出——整理 Phase 2 的架构决策、Phase 3 的设计亮点和疑问、实践验证结论
2. 架构决策 Trade-off 提炼——每个决策分析：上下文、选择、收益、代价、替代方案，以及「如果在我的项目中遇到类似问题，我会怎么选」
3. 可复用模式提取——满足至少 2 条标准才提炼：多处使用、解决常见问题、实现优雅、可直接迁移。每个模式记录问题场景、核心思路、关键代码和迁移指南
4. 反模式/技术债识别——客观识别过度设计、设计不足、历史包袱等，标注可能的原因
5. 横向对比分析（可选）——如果涉及技术选型，从设计理念、架构风格、扩展机制、性能特征等维度对比

产出：<项目名>-知识提炼.md + <项目名>-对比分析.md（如适用）

---

Phase 5：输出与沉淀

目标：将学习成果转化为可分享、可检索的知识产出。

核心步骤：

1. 学习成果盘点——对照 Phase 1 设定的目标逐条检查达成情况
2. 生成学习总结——整合为一篇结构化笔记：项目定位 → 架构亮点 → 核心实现精华 → 设计 Trade-off → 可迁移收获 → 待深入方向
3. 博客草稿撰写（可选）——可选源码分析、架构解析、技术对比、实践总结、学习笔记五种类型
4. 后续行动项——拆为短期（1-2 周）、中期（1-3 个月）、长期三个时间维度

产出：<项目名>-学习总结.md + <项目名>-博客草稿.md（如适用）

---

三、项目类型差异化

不同类型的项目，每个 Phase 的关注点不同。工作流将差异化指引独立成一份文档，Claude 根据项目类型只加载对应章节：

Phase	业务项目 (A)	架构工具项目 (B)	开源项目 (C)
Phase 1	业务域、核心场景、业务指标、领域模型预判	技术定位、竞品对比、设计理念、扩展机制预判	社区健康度、治理模式、生态系统、贡献门槛
Phase 2	领域模型、业务流程编排、数据模型、集成点	分层架构、扩展机制(SPI/Plugin)、性能设计、API设计	模块化设计、公共API表面、向后兼容、构建发布
Phase 3	业务规则实现、状态管理、事务处理	核心机制、插件系统、性能关键路径	代码质量标杆、测试策略、贡献流程体验
Phase 4	业务模式提取、领域知识沉淀	设计模式蒸馏、架构决策记录	开源最佳实践、代码工程实践
Phase 5	业务域知识总结、团队内部分享	设计模式和技巧、技术博客	社区博客、贡献代码回馈

一个项目可能同时具备多种类型特征（如开源的架构工具项目），选择最主要的学习目标对应的类型即可。

---

四、跨会话连续性

项目学习不是一次对话能完成的事情。工作流通过以下机制保证进度不丢失：

进度保存

当用户说「先到这」「保存进度」时，Claude 将当前状态写入 Root MOC 的「当前进度」区域：

## 当前进度

> 最后更新：2026-05-02 15:30

- **当前 Phase**：Phase 2 - 架构分析
- **当前 Step**：Step 3 - 依赖关系分析
- **已完成**：模块结构图、核心设计模式识别
- **进行中**：正在分析 gateway-core 和 gateway-filter 的依赖关系
- **待解决**：RoutePredicateFactory 的自动装配机制还不清楚
- **下次继续**：完成依赖分析后开始 Step 4 数据流分析

进度恢复

下次对话 Claude 读取「当前进度」区域，直接从中断点继续，无需重复分析。

taskStatus 状态机

每个 Phase 通过 frontmatter 的 taskStatus 字段管理状态：

taskStatus	含义
0	未开始
1	待投入
2	进行中
3	冻结（暂停）
4	已归档

---

五、触发词速查

触发词	动作
开始学习 <项目名>	创建项目学习文件夹，进入 Phase 1
继续学习	扫描 MOC，恢复进行中的 Phase
开始架构分析	进入 Phase 2
开始读代码 / 开始精读	进入 Phase 3
开始提炼 / 开始对比	进入 Phase 4
开始输出 / 写总结	进入 Phase 5
跳过当前 Phase	标记当前 Phase 为已归档，进入下一个
暂停学习 / 恢复学习	冻结/恢复当前 Phase
先到这 / 保存进度	保存当前进度到 Root MOC
切换项目类型 <类型>	更新项目类型，调整差异化指引

---

六、工作流文档组成

整套工作流由以下文档组成：

文档	职责
学习内容维护规则	总控文档：启动流程、项目类型定义、taskStatus 映射、触发词、跨会话连续性、返工处理
Phase 1-5 文档	各 Phase 的具体执行步骤和产出模板
项目类型差异化指引	按 A/B/C 三种类型 × 5 个 Phase 组织的差异化关注点
文件夹维护规则	frontmatter 模板、文件夹结构模板、MOC 内容模板、文件创建规则

Claude 运行时只加载「维护规则 + 当前 Phase + 对应类型指引」三份文档，其余按需加载。

---

小结

这套工作流的核心思路很简单：把学习当成一个项目来管理。

• Phase 1 解决「学什么、为什么学」
• Phase 2 解决「全局是什么样的」
• Phase 3 解决「细节是怎么实现的」
• Phase 4 解决「有什么能带走的」
• Phase 5 解决「怎么让别人也知道」

每个 Phase 的产出都是 Markdown 文件，沉淀在 Obsidian 中，随时可以检索、关联、补充。不管是下周回来继续学，还是半年后回顾当时的分析，都能无缝衔接。