目标用 zread 为老项目生成结构化 Wiki再让 Claude Code 基于 Wiki 查架构、找代码、排问题。中型项目实测约 90 分钟花费 ¥9.69生成 29 页 Wiki。接手一个陌生老项目先不要从源码目录开始硬翻。更稳的做法是先生成一份项目地图再围绕具体问题进入源码。这套流程适合下面几类场景新加入项目需要快速理解整体架构。README、设计文档过期代码才是真实依据。要排线上问题但不确定入口、链路和配置在哪里。要改一个模块先确认影响范围和相关文件。要让 Claude Code、Cursor、GPT 等工具更准确地理解仓库。整体流程只有三步zread 扫描本地代码库生成结构化 Wiki。Claude Code 阅读 Wiki建立项目上下文。围绕具体任务让 Claude Code 回到源码中核对和执行。1. 安装 zread先安装 CLInpminstall-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生成内容覆盖范围领域篇数典型内容项目概览与入门2Overview、Quick Start架构与前端导航2平台架构、前端视图与路由后端基础设施4FastAPI、配置、数据库、认证Skill / Agent 系统5Skill 契约、注册器、Agent Runner、OrchestratorLLM 路由与 Provider3Router、Registry、Key Vault测试与监控3Test Executor、Monitoring、Correlation知识库与管道协议4ChromaDB RAG、Pipeline、SSE 流式协议前端与报告4报告导出、Vue 组件、架构图编辑器、AI 聊天部署与运维2Docker Compose、Prometheus/Grafana7. 用 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. 完整流程清单直接复制下面这套流程即可安装 zreadnpminstall-gzread_cli配置模型zread config安装 Claude Code Skillinstall this skill https://github.com/ZreadAI/zread-skill进入项目目录cd/path/to/your/project生成 Wiki/zread 运行 zread generate 生成完整的 wiki 文档中断后恢复zread generate--draftresume-y打开 Wikizread browse让 Claude Code 基于 Wiki 执行具体任务请先阅读 .zread/wiki/current/ 中与目标模块相关的文档 再回到源码中定位实现、调用链和测试入口。 输出文件路径、关键函数、验证方式和修改建议。参考资源zread 官网zread-skill GitHubClaude Code 官方文档工具版本、模型价格和生成成本会变化实际使用时以官方最新信息和当前模型计费为准。