使用 Claude Code 快速拆解开源知识库项目架构与二次开发指南¶

本指南旨在帮助你利用 Claude Code 强大的本地代码库感知与 Agent 能力，通过渐进式交互（Iterative Prompting）快速熟悉陌生开源项目、厘清核心功能逻辑，并为后续的二次开发打下坚实基础。

📌 操作流程与实战命令¶

建议进入项目根目录启动 Claude Code 后，按照以下四个阶段循序渐进地向 AI 发送指令。

阶段一：宏观认知（技术栈与目录拓扑）¶

目的： 构建项目的全局地图，避免盲目阅读源码。

👉 发送给 Claude 的命令：

Text Only
请帮我扫描当前项目的目录结构，分析该项目的整体技术栈、核心依赖项，并给出一个高层级的模块划分概述。请用清晰的层级结构（如 Markdown 列表或表格）告诉我每个核心文件夹的作用，帮我建立对项目的宏观认知。

阶段二：核心功能逻辑追踪（以知识库 RAG 为核心）¶

目的： 打通“知识库”的核心生命周期，理清数据流向。

👉 发送给 Claude 的命令：

Text Only
我想深入理解这个知识库核心功能的实现逻辑。请帮我追踪【用户上传文档到最终发起 RAG 检索问答】的完整数据流向。从最外层的 API 接口/控制器（Controller）开始，指出它调用了哪些服务层（Service）、利用了什么解析库、以及如何存储到数据库或向量数据库（Vector Store）中。请列出涉及的关键文件路径和核心函数名。

阶段三：评估二次开发扩展点¶

目的： 明确代码的解耦程度，为你的定制化开发铺路。

👉 发送给 Claude 的命令：

Text Only
我的最终目的是基于当前功能进行二次开发（例如：计划添加一个新的定制检索算法，或支持一种新的特殊文档格式）。请根据你对目前代码解耦程度的理解，告诉我如果我要做这两项改动，分别应该在哪些目录下添加或修改代码？当前项目是否有定义好的接口（Interface）或基类（Base Class）供我继承扩展？

阶段四：沉淀持久化文档（自动生成说明书）¶

目的： 打造项目的“AI 导航大脑”，将分析结果固化为项目资产。

👉 发送给 Claude 的命令：

Text Only
请结合刚才我们所有的分析与你的推导结果，在项目根目录下为我生成一份详尽的 ARCHITECTURE.md 架构说明书文档。同时，请根据 Claude Code 的官方最佳实践，在根目录下直接创建或完善一个 CLAUDE.md 文件，其中必须包含：
1. 项目简介与技术栈；
2. 核心模块与文件拓扑；
3. 常用开发、构建、测试与运行命令；
4. 项目的代码风格约束与二次开发扩展规范。
请直接使用你的文件写入工具生成这两个文件。

💡 进阶使用技巧¶

让 CLAUDE.md 成为你的 AI 编码约束 步骤四中生成的 CLAUDE.md 是 Claude Code 官方支持的特殊本地配置文件。后续当你直接让 Claude Code 帮你编写具体的二次开发代码（例如：claude "帮我实现一个支持 Markdown 深度解析的 Extension"）时，它在行动前会自动读取该文件，并严格遵守里面记录的代码风格和目录规范，确保生成的代码能够完美融入原项目。
善用 Agent 的本地权限 Claude Code 拥有执行本地命令和文件检索的权限。如果你在阅读某些复杂的异步队列或多线程处理逻辑时感到困惑，可以直接在终端对它说：

"请帮我用 grep 找出所有引用了 XXXX 类的文件，并解释它们之间的通信机制。" 这比在网页端手动复制粘贴代码进行询问要高效得多。