Claude Code + zread 快速上手老项目实操指南
目标：用 zread 为老项目生成结构化 Wiki，再让 Claude Code 基于 Wiki 查架构、找代码、排问题。中型项目实测：约 90 分钟，花费 ¥9.69，生成 29 页 Wiki。
接手一个陌生老项目，先不要从源码目录开始硬翻。更稳的做法是先生成一份项目地图，再围绕具体问题进入源码。
这套流程适合下面几类场景：
- 新加入项目，需要快速理解整体架构。
- README、设计文档过期，代码才是真实依据。
- 要排线上问题，但不确定入口、链路和配置在哪里。
- 要改一个模块，先确认影响范围和相关文件。
- 要让 Claude Code、Cursor、GPT 等工具更准确地理解仓库。
整体流程只有三步：
- zread 扫描本地代码库，生成结构化 Wiki。
- Claude Code 阅读 Wiki，建立项目上下文。
- 围绕具体任务，让 Claude Code 回到源码中核对和执行。
1. 安装 zread
先安装 CLI：
npminstall-gzread_cli安装完成后检查版本：
zread version能看到版本信息即可。示例输出：
$ zread version ████████╗██████╗ ███████╗ █████╗ ██████╗ ███╔╝ ██╔══██╗██╔════╝██╔══██╗██╔══██╗ ███╔╝ ██████╔╝█████╗ ███████║██║ ██║ ███╔╝ ██╔══██╗██╔══╝ ██╔══██║██║ ██║ ████████╗██║ ██║███████╗██║ ██║██████╔╝ ╚═══════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ 将本地代码库转化为可读文档 ────────────────────────────────────────────── 版本: 0.2.12 渠道: npm Go: go1.26.0 系统: windows 架构: amd642. 配置模型
执行配置命令：
zread config建议配置如下：
| 配置项 | 建议值 | 说明 |
|---|---|---|
| 文档生成语言 | English 或中文 | 给 AI 继续读取，优先 English；团队直接阅读，优先中文 |
| LLM 提供商 | custom | 按 OpenAI 兼容格式配置 |
| 模型 | deepseek-v4-pro | 首次生成建议使用质量较高的模型 |
| 最大并发数 | 1 | 先保证稳定，降低限流概率 |
配置文件位置：
~/.zread/config.yaml说明：
- Wiki 后续主要交给 Claude Code / GPT / Cursor 阅读时，英文文档通常更稳定。
- Wiki 主要作为团队交接材料时，中文文档更方便直接阅读。
- 首次生成不要过度压低模型质量，否则后续问答和定位代码都会受影响。
3. 安装 Claude Code 的 zread Skill
在 Claude Code 中输入：
install this skill https://github.com/ZreadAI/zread-skill安装完成后，Claude Code 可以识别/zread命令，并协助完成配置检查、生成启动、进度观察和失败恢复提示。
如果自动安装失败，可以手动安装：
gitclone https://github.com/ZreadAI/zread-skill.gitcp-Rzread-skill ~/.claude/skills/zread4. 在项目目录生成 Wiki
进入老项目根目录：
cd/path/to/your/project在 Claude Code 中执行：
/zread 运行 zread generate 生成完整的 wiki 文档生成过程中，Claude Code 会持续输出进度。中型项目可能需要 60-90 分钟。
示例进度：
● 当前进度 9/29 页： ┌─────┬───────────────────────────────┬──────────┐ │ # │ 页面 │ 大小 │ ├─────┼───────────────────────────────┼──────────┤ │ 1-5 │ 前5页 │ 15-32 KB │ ├─────┼───────────────────────────────┼──────────┤ │ 6 │ Configuration Management │ 27.6 KB │ ├─────┼───────────────────────────────┼──────────┤ │ 7 │ Database Layer │ 18.1 KB │ ├─────┼───────────────────────────────┼──────────┤ │ 8 │ JWT Authentication │ 16.6 KB │ ├─────┼───────────────────────────────┼──────────┤ │ 9 │ Skill Base Contract │ 22.5 KB │ └─────┴───────────────────────────────┴──────────┘ 速度有所提升，预计剩余约 30-40 分钟。5. 中断后恢复生成
生成过程中如果遇到网络中断、API 限流、模型服务异常，不要直接从头重跑。
先查看草稿目录：
ls./.zread/wiki/drafts/再从断点继续：
zread generate--draftresume-y已完成的页面不会重复生成，适合中大型项目。
6. 打开生成结果
生成完成后执行：
zread browse浏览器会打开本地 Wiki。
实测项目数据：
| 项目 | 结果 |
|---|---|
| 项目类型 | 7D 性能 Agent 系统 |
| 生成页数 | 29 页 Wiki |
| 文档大小 | 约 599 KB |
| 生成时间 | 约 90 分钟 |
| 实际花费 | ¥9.69 |
生成目录示例：
.zread/wiki/versions/2026-05-07-193851/ ├── 1-overview.md ├── 2-quick-start.md ├── 3-platform-architecture-four-layer-harness-model.md ├── 4-navigating-the-frontend-views-and-routes.md ├── ... ├── 28-docker-compose-multi-service-deployment-backend-frontend-prometheus-and-grafana.md ├── 29-monitoring-profile-prometheus-metrics-collection-and-grafana-dashboards.md └── wiki.json生成内容覆盖范围：
| 领域 | 篇数 | 典型内容 |
|---|---|---|
| 项目概览与入门 | 2 | Overview、Quick Start |
| 架构与前端导航 | 2 | 平台架构、前端视图与路由 |
| 后端基础设施 | 4 | FastAPI、配置、数据库、认证 |
| Skill / Agent 系统 | 5 | Skill 契约、注册器、Agent Runner、Orchestrator |
| LLM 路由与 Provider | 3 | Router、Registry、Key Vault |
| 测试与监控 | 3 | Test Executor、Monitoring、Correlation |
| 知识库与管道协议 | 4 | ChromaDB RAG、Pipeline、SSE 流式协议 |
| 前端与报告 | 4 | 报告导出、Vue 组件、架构图编辑器、AI 聊天 |
| 部署与运维 | 2 | Docker Compose、Prometheus/Grafana |
7. 用 Wiki 快速理解架构
生成 Wiki 之后，不建议逐篇从头读完。更高效的方式是先让 Claude Code 读关键文档，再输出结构化摘要。
推荐先读：
1-overview.md2-quick-start.md3-platform-architecture-*.md
可直接使用下面的提示词：
请先阅读 .zread/wiki/current/ 下的 overview、quick start 和 platform architecture 文档。 输出这个项目的整体分层、核心模块、主要数据流和启动入口。 要求：用中文，按模块列出关键文件线索。输出结果通常可以作为第一份项目速览。
8. 用 Wiki 定位具体代码
定位具体逻辑时，不要只让 Claude Code 全仓库搜索关键字。先让它参考 Wiki 中对应模块，再回到源码核对。
示例：查 JWT 认证和 token 刷新逻辑。
请参考 .zread/wiki/current/ 中 JWT Authentication 相关文档， 再回到源码中定位 JWT 认证、token 刷新、权限校验相关代码。 输出： 1. 相关文件路径 2. 关键类和函数 3. 请求进入后的调用链 4. 需要重点检查的配置项这种方式比直接搜索jwt更稳定，因为 Wiki 已经整理了模块边界和上下游关系。
9. 用 Wiki 分析复杂链路
复杂模块不要只问“这个模块是什么”。要让 Claude Code 按链路解释，并要求它回到源码验证。
示例：分析 Agent Runner 流式执行。
根据 .zread/wiki/current/ 中 Agent Runner 相关文档， 结合源码解释流式执行链路。 输出： 1. 入口函数 2. 事件如何生成 3. 事件如何持久化 4. 事件如何发送到前端 5. 关键异常处理逻辑链路类问题的重点不是单个函数，而是入口、状态流转、持久化、对外输出和异常处理。
10. 用 Wiki 辅助排查问题
排查问题时，可以先让 Claude Code 根据 Wiki 给出排查路径，再逐步执行验证。
示例：项目启动时报数据库连接错误。
项目启动时报数据库连接错误。 请先阅读 .zread/wiki/current/ 中 Database Layer 和 Configuration Management 相关文档， 然后回到源码中分析可能原因。 输出： 1. 数据库配置从哪里读取 2. 初始化流程从哪里开始 3. 连接创建和迁移逻辑在哪里 4. 排查顺序 5. 需要执行的验证命令这样能避免在不熟悉项目的情况下随机翻文件。
11. 用 Wiki 做代码审查、重构和测试设计
Wiki 也可以作为后续维护的上下文。
代码审查：
请根据 .zread/wiki/current/ 中 Skill 系统设计， 审查当前变更是否符合现有架构约束。 输出潜在问题、涉及文件和修改建议。重构：
请根据 .zread/wiki/current/ 中 LLM Router 相关设计， 分析当前 provider 选择逻辑的职责边界， 给出最小重构方案，并说明需要补充哪些测试。测试设计：
请根据 .zread/wiki/current/ 中 Test Executor 架构， 为目标模块设计测试方案。 要求覆盖正常流程、异常流程、配置缺失和边界输入。12. 配置.zreadignore
生成前建议先添加.zreadignore，避免无关文件影响成本和质量。
示例：
node_modules/ *.min.js dist/ build/ coverage/测试文件是否忽略取决于目的：
- 只想理解业务主流程：可以忽略测试文件。
- 想了解项目质量和测试体系：保留测试文件。
- 想让 Claude Code 后续补测试：建议保留现有测试文件。
13. 什么时候需要重新生成
不是每次改代码都需要重新生成 Wiki。
建议重新生成的情况：
- 架构分层发生变化。
- 认证、数据库、消息流、Agent 编排等核心链路发生变化。
- 目录结构大调整。
- 新成员入组，需要一份新的交接材料。
- 旧 Wiki 与当前源码已经明显不一致。
清理旧版本并重新生成：
rm-rf./.zread/wiki/versions/old-version zread generate如果需要保留历史对比，不要删除旧版本。
14. 注意事项
Wiki 是项目索引，不是最终事实。任何结论在真正修改代码前，都应该回到源码验证。
推荐在关键问题后追加一句：
以上结论请回到源码验证，列出相关文件、函数和证据。尤其注意几类老项目常见情况：
- 文档路径和线上实际路径不一致。
- 存在废弃代码，但仍然被 Wiki 摘要引用。
- 配置开关决定了实际执行分支。
- 同名模块有新旧两套实现。
- 测试代码反映的是旧行为，不一定代表当前线上行为。
15. 完整流程清单
直接复制下面这套流程即可：
- 安装 zread：
npminstall-gzread_cli- 配置模型：
zread config- 安装 Claude Code Skill：
install this skill https://github.com/ZreadAI/zread-skill- 进入项目目录：
cd/path/to/your/project- 生成 Wiki：
/zread 运行 zread generate 生成完整的 wiki 文档- 中断后恢复：
zread generate--draftresume-y- 打开 Wiki：
zread browse- 让 Claude Code 基于 Wiki 执行具体任务：
请先阅读 .zread/wiki/current/ 中与目标模块相关的文档， 再回到源码中定位实现、调用链和测试入口。 输出文件路径、关键函数、验证方式和修改建议。参考资源
- zread 官网
- zread-skill GitHub
- Claude Code 官方文档
工具版本、模型价格和生成成本会变化，实际使用时以官方最新信息和当前模型计费为准。