● 社区
zarazhangrui
⚡ 即开即用
Codebase to Course
作者 zarazhangrui · zarazhangrui/codebase-to-course
指向一个仓库，得到一个像教程一样解释它的单文件 HTML 「课程」——带注释代码、架构图和叙述——适合非工程师阅读或新员工入职。
codebase-to-course 是一个 Claude Code skill，它遍历整个仓库并生成一个单文件 HTML 课程，解释代码库实际是如何工作的。结构类似教程：高层架构 → 逐模块深入 → 「跟着请求走一遍系统」流程图——附带内嵌的注释代码片段。输出是单个 HTML 文件，无需构建步骤。
为什么要用
核心特性
- 单文件 HTML 输出——无需构建流程
- 从真实代码生成架构概览（而非 README）
- 每个模块「为什么存在 + 如何工作」的说明
- 跟踪真实入口点的请求流程图
- 带逐行解释的注释代码块
- 专为非工程师设计（PM、设计师、新员工）
使用场景
实战用法： Codebase to Course
何时使用： 周五 offer 已接受：你想要一份真正的入职材料，而不是「去读代码吧」。
步骤
-
扫描仓库
codebase-to-course：扫描 ./our-app，先输出课程结构提案——章节列表——再开始写作。✓ 已复制
→ 具体的目录：架构、模块、请求流程
-
生成课程
看起来不错，生成完整 HTML 到 /onboarding/course.html，目标受众：了解 React + Node 但不熟悉我们业务领域的全栈新员工。✓ 已复制
→ HTML 文件已生成；可在浏览器中打开
-
验证准确性
抽检：「认证流程」的描述是否与 src/auth/ 里的实现一致？引用真实代码。✓ 已复制
→ 描述引用了真实文件路径和当前代码
结果： 真正有用的入职材料，节省团队两周的解释时间。
注意事项
- 课程太长以至于没人读 — 限定章节数量；质量优于完整性
- 代码片段随时间过时 — 大型重构后重新生成；skill 速度快
何时使用： PM 不断问「为什么这需要 3 个 sprint」——你想给他一份具体的材料。
步骤
-
聚焦到功能模块
codebase-to-course：聚焦到 src/payments/，受众是没有工程背景的 PM，多用图表和类比，减少代码。✓ 已复制
→ 课程偏高层；代码块很少
结果： PM 建立起对这个功能的心智模型。
注意事项
- 类比过度简化 — 仔细检查；如果被追问，skill 倾向于准确性
何时使用： 你的 README 有功能介绍但没有架构说明。
步骤
-
生成文档页
codebase-to-course：扫描主分支，为文档站生成 ARCHITECTURE.html，目标受众：评估项目的资深开发者。✓ 已复制
→ 输出读起来像用心撰写的贡献者指南
结果： 评估者和贡献者有了更好的开发体验。
注意事项
- 课程风格太泛化（看起来不像你的项目） — 在 prompt 中传入项目名称和风格说明
组合
与其他 MCP 搭配，撬动十倍杠杆
读取本地仓库并写入课程
codebase-to-course：扫描 ./our-app，写入 /onboarding/course.html。✓ 已复制
无需 clone 即可为外部仓库生成课程
用 GitMCP 获取 owner/repo，然后在上面运行 codebase-to-course。✓ 已复制
成本与限制
运行它的成本
- API 配额
- 不适用
- 每次调用 Token 数
- 消耗较大——skill 会读取整个仓库（通常 10k–50k token）
- 费用
- 免费；模型 token 费用自理
- 提示
- 对 monorepo 使用 scope_to_subdir；不要一次性课程化整个仓库
安全
权限、密钥、影响范围
最小权限： filesystem-read filesystem-write
凭据存储： 无
数据出站： 无——纯本地读写
- 生成的课程可能包含代码片段；对外分享前，检查仓库中是否有 secret
故障排查
常见错误与修复
课程太泛化/没有引用真实代码
让 prompt 更具体；要求 file:line 级别的引用
仓库太大；context 溢出
使用 scope_to_subdir；生成按模块分割的课程并互相链接
HTML 格式异常
让 skill 验证输出；如需要则重新生成
替代方案
Codebase to Course 对比其他方案
| 替代方案 | 何时用它替代 | 权衡 |
|---|
| Repomix + 手动 prompt | 你想完全控制代码库如何输入给 Claude | 需要更多配置；没有约定的输出格式 |
| DocsGPT / Mintlify | 你想要托管文档 | 完全不同的产品；不是单文件 HTML |
| absolutely-skilled / autodoc | 你想要自动生成 API 文档 | API 参考 ≠ 教程 |