zarazhangrui · fogdragon · Jun 21, 2026 · Jun 21, 2026
diff --git a/README.md b/README.md
@@ -1,14 +1,18 @@
 # Codebase to Course
 
-A Claude Code skill that turns any codebase into a beautiful, interactive single-page HTML course.
+**[中文文档](README.zh-CN.md)**
 
-Point it at a repo. Get back a stunning, self-contained course that teaches how the code works — with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations.
+A Claude Code skill that turns any codebase into a beautiful, interactive single-page HTML course. Two modes for two very different audiences.
 
-## Who is this for?
+Point it at a repo. Get back a stunning, self-contained course — with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations. Or, if you're a professional engineer evaluating a project for adoption, get a technical due diligence report with architecture decision analysis, critical path traces, risk assessments, and competitive comparisons.
 
-**"Vibe coders"** — people who build software by instructing AI coding tools in natural language, without a traditional CS education.
+## Two modes
 
-You've built something (or found something cool on GitHub). It works. But you don't really understand *how* it works under the hood. This skill generates a course that teaches you — not by lecturing, but by tracing what happens when you actually use the app.
+### Beginner Mode — for vibe coders
+
+**Audience:** People who build software by instructing AI coding tools in natural language, without a traditional CS education.
+
+You've built something (or found something cool on GitHub). It works. But you don't really understand *how* it works under the hood. This mode generates a course that teaches you — not by lecturing, but by tracing what happens when you actually use the app.
 
 **Your goals are practical, not academic:**
 - Steer AI coding tools better (make smarter architectural decisions)
@@ -18,41 +22,64 @@ You've built something (or found something cool on GitHub). It works. But you do
 
 You're not trying to become a software engineer. You want coding as a superpower.
 
+### Engineer Mode — for technical due diligence
+
+**Audience:** Professional software engineers evaluating whether to adopt an open-source project into their production stack.
+
+You don't need metaphors. You need to know: *Are the design decisions sound? What are the critical paths? Will it work in my scenario? Can it integrate with my stack? How does it compare to alternatives?*
+
+Engineer Mode produces a fundamentally different output — a technical due diligence report with:
+
+- **ADR Cards** — Architecture Decision Records analyzing each key design choice (problem, selected approach, rejected alternatives, trade-off table)
+- **Critical Path Traces** — Step-by-step walkthroughs of the most important code execution paths, with engineering commentary referencing exact file names and line numbers
+- **Trade-off Matrices** — Color-coded comparison tables evaluating different approaches across multiple dimensions
+- **Scenario Judge** — Interactive cards that assess whether the project is a good fit for specific use cases
+- **Integration Blueprint** — Complete, copy-pasteable bridge code showing how to integrate with real-world tech stacks
+- **Source File Map** — Annotated directory tree classifying each key file as "framework" (skeleton/architectural) or "functional" (concrete implementation), with a recommended 3-5 file reading order
+- **Risk Indicators** — Categorized risk items with severity levels (high/medium/low)
+- **Verdict Callout** — Each module ends with a clear engineering verdict
+
 ## What the course looks like
 
 The output is a **single HTML file** — no dependencies, no setup, works offline. It includes:
 
 - **Scroll-based modules** with progress tracking and keyboard navigation
-- **Code ↔ Plain English translations** — real code on the left, what it means on the right
+- **Code ↔ Plain English translations** (Beginner) or **Code ↔ Engineering Commentary** (Engineer) — real code on one side, what it means or why it matters on the other
+
 <img width="720" alt="Code translation block" src="https://github.com/user-attachments/assets/fb9e7fac-05c1-4f98-b80c-46543ef81afc" />
 
-- **Animated visualizations** — data flow animations, group chat between components, architecture diagrams
+- **Animated visualizations** — data flow animations, group chat between components, architecture diagrams (Beginner Mode)
 <img width="720" alt="Animated data flow" src="https://github.com/user-attachments/assets/20fb403e-7dfd-4a47-989b-bbae86ca8041" />
 
 - **Interactive quizzes** that test *application* not memorization ("You want to add favorites — which files change?")
 <img width="720" alt="Interactive quiz" src="https://github.com/user-attachments/assets/57706496-9fa8-457a-8450-3da22789951c" />
 
-- **Glossary tooltips** — hover any technical term for a plain-English definition
+- **Glossary tooltips** — hover any technical term for a plain-English definition (Beginner Mode)
 <img width="720" alt="Glossary tooltip" src="https://github.com/user-attachments/assets/ac2f160a-d73f-4779-97b2-a06fdb5f3227" />
 
-
-- **Warm, distinctive design** — not the typical purple-gradient AI look
+- **Warm, distinctive design** — not the typical purple-gradient AI look. Five accent palettes available (vermillion, coral, teal, amber, forest).
 
 ## How to use
 
 ### As a Claude Code skill
 
 1. Copy the `codebase-to-course` folder into `~/.claude/skills/`
 2. Open any project in Claude Code
-3. Say: *"Turn this codebase into an interactive course"*
+3. Say one of:
+
+**For Beginner Mode:**
+- *"Turn this codebase into an interactive course"*
+- *"Explain this codebase interactively"*
+- *"Make a course from this project"*
+- *"Teach me how this code works"*
 
-### Trigger phrases
+**For Engineer Mode:**
+- *"Turn this codebase into an engineer mode report"*
+- *"Analyze this codebase for technical due diligence"*
+- *"I need an engineering assessment of this project"*
+- *"Should we adopt this library? Generate a report"*
 
-- "Turn this into a course"
-- "Explain this codebase interactively"
-- "Make a course from this project"
-- "Teach me how this code works"
-- "Interactive tutorial from this code"
+The mode is auto-detected from your prompt, or you can specify explicitly.
 
 ## Design philosophy
 
@@ -80,13 +107,38 @@ Code snippets are exact copies from the real codebase — never modified or simp
 
 ```
 codebase-to-course/
-├── SKILL.md                          # Main skill instructions
+├── SKILL.md                          # Main skill instructions (both modes)
 └── references/
+    ├── _base.html                    # HTML template shell
+    ├── _footer.html                  # Shared footer with navigation logic
+    ├── styles.css                    # All styles (both modes + engineer elements)
+    ├── main.js                       # Interactive logic (quizzes, file map, etc.)
+    ├── build.sh                      # Shell script to assemble single HTML file
     ├── design-system.md              # CSS tokens, typography, colors, layout
-    └── interactive-elements.md       # Quiz, animation, and visualization patterns
+    ├── interactive-elements.md       # All 25 interactive element patterns
+    ├── content-philosophy.md         # Content writing philosophy per mode
+    ├── gotchas.md                    # Common mistakes and how to avoid them
+    └── module-brief-template.md      # Template for Phase 2.5 planning checkpoint
 ```
 
+## Changelog
+
+### v2.0.0 — Engineer Mode (2025)
+
+- Added **Engineer Mode**: a completely separate product targeting professional engineers doing technical due diligence
+- 8 new interactive element types: ADR Cards, Critical Path Traces, Trade-off Matrix, Scenario Judge, Integration Blueprint, Source File Map, Risk Indicators, Verdict Callout
+- **Source File Map**: annotated directory tree classifying 30-50 key files as "framework" (骨架/框架性) vs "functional" (功能/功能性), with recommended reading order
+- Code block style shifted from "Code ↔ Plain English" to "Code ↔ Engineering Commentary" for engineer mode
+- Added `content-philosophy.md` and `gotchas.md` as separate reference files
+- Added Phase 2.5 planning checkpoint for complex codebases
+- Forked Phase 3 into sequential (simple) and parallel (complex) build paths
+- Updated skill structure to include HTML template, CSS, JS, and build script
+
+### v1.0.0 — Initial release
+
+- Beginner Mode with scroll-based navigation, animated visualizations, interactive quizzes, and glossary tooltips
+- Single-file HTML output with no dependencies
 
 ---
 
-Built by [Zara](https://x.com/zarazhangrui) with Claude Code.
+Built by [Zara](https://x.com/zarazhangrui) with Claude Code. Engineer Mode and Chinese documentation added by [fogdragon](https://github.com/fogdragon) by Qwen3.7-Max.
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -0,0 +1,147 @@
+# Codebase to Course
+
+**[English](README.md)**
+
+一个 Claude Code 技能，可以将任意代码库转化为精美的、交互式单页 HTML 课程。提供两种模式，面向两类截然不同的受众。
+
+指向一个仓库，得到一个精美的、自包含的课程——支持滚动导航、动画可视化、嵌入式测验，以及代码与自然语言的逐段对照翻译。或者，如果你是一位正在评估是否引入某个开源项目的专业工程师，你会得到一份技术尽调报告——包含架构决策分析、关键路径追踪、风险评估和竞品对比。
+
+## 两种模式
+
+### 入门模式（Beginner Mode）——面向 Vibe Coder
+
+**受众：** 通过自然语言指挥 AI 编码工具构建软件、但没有传统计算机科班背景的人。
+
+你已经做出了一个东西（或在 GitHub 上发现了一个很酷的项目）。它能跑。但你并不真正理解它*底层*是怎么工作的。这个模式会生成一个课程来教你——不是通过说教，而是通过追踪你实际使用这个应用时发生的事情。
+
+**你的目标是实用性的，不是学术性的：**
+- 更好地驾驭 AI 编码工具（做出更明智的架构决策）
+- 发现 AI 什么时候在胡说（捕捉幻觉、识别坏模式）
+- 在 AI 卡住时能 debug（打破 bug 循环）
+- 和工程师交流时不会一头雾水
+
+你不是想成为软件工程师。你想把编码变成你的超能力。
+
+### 工程师模式（Engineer Mode）——面向技术尽调
+
+**受众：** 正在评估是否将某个开源项目引入生产环境的专业软件工程师。
+
+你不需要隐喻。你需要知道：*设计决策合理吗？关键路径是怎么实现的？在我的场景下能工作吗？能和我的技术栈集成吗？和竞品比怎么样？*
+
+工程师模式产出的是一个完全不同的产品——一份技术尽调报告，包含：
+
+- **ADR 卡片（架构决策记录）** ——分析每个关键设计决策的完整上下文（问题背景、选定方案、被放弃的备选方案、权衡分析表格）
+- **关键路径追踪** ——逐步展示最重要的代码执行路径，附带工程分析注释，精确到文件名和行号
+- **权衡矩阵** ——颜色编码的比较表格，在多个维度上评估不同方案的优劣
+- **场景判断器** ——交互式卡片，评估项目是否适合特定的使用场景
+- **集成蓝图** ——完整的、可直接复制的桥接代码，展示如何与真实技术栈集成
+- **源文件地图** ——带注释的目录树，将 30-50 个关键文件分类为"框架性"（骨架/架构）或"功能性"（具体实现），并推荐 3-5 个文件的首读顺序
+- **风险指标** ——按严重程度（高/中/低）分类的风险项
+- **裁决标注** ——每个模块以一个清晰的工程判断结尾
+
+## 课程长什么样
+
+输出是一个**单一 HTML 文件**——无依赖、无需配置、离线可用。包含：
+
+- **滚动式模块导航**，带进度追踪和键盘快捷键
+- **代码 ↔ 自然语言翻译**（入门模式）或 **代码 ↔ 工程分析**（工程师模式）——一侧是真实代码，另一侧是含义解读或工程意义分析
+
+<img width="720" alt="代码翻译块" src="https://github.com/user-attachments/assets/fb9e7fac-05c1-4f98-b80c-46543ef81afc" />
+
+- **动画可视化** ——数据流动画、组件间群聊对话、架构图（入门模式）
+
+<img width="720" alt="数据流动画" src="https://github.com/user-attachments/assets/20fb403e-7dfd-4a47-989b-bbae86ca8041" />
+
+- **交互式测验**——测试的是*应用能力*而非记忆（"你要添加收藏功能——哪些文件需要改？"）
+
+<img width="720" alt="交互式测验" src="https://github.com/user-attachments/assets/57706496-9fa8-457a-8450-3da22789951c" />
+
+- **术语提示** ——鼠标悬停在任何技术术语上即可获得通俗解释（入门模式）
+
+<img width="720" alt="术语提示" src="https://github.com/user-attachments/assets/ac2f160a-d73f-4779-97b2-a06fdb5f3227" />
+
+- **温暖、独特的设计** ——不是那种典型的紫色渐变 AI 风格。提供五种主题色（朱红、珊瑚、青绿、琥珀、森林绿）。
+
+## 如何使用
+
+### 作为 Claude Code 技能
+
+1. 将 `codebase-to-course` 文件夹复制到 `~/.claude/skills/`
+2. 在 Claude Code 中打开任意项目
+3. 说出以下触发语之一：
+
+**入门模式：**
+- *"把这个代码库变成一个交互式课程"*
+- *"交互式地解释这个代码库"*
+- *"用这个项目做一个课程"*
+- *"教我这段代码是怎么工作的"*
+
+**工程师模式：**
+- *"用工程师模式分析这个代码库"*
+- *"对这个项目做技术尽调"*
+- *"生成一份工程评估报告"*
+- *"我们该不该引入这个库？生成分析报告"*
+
+模式会从你的提示语中自动检测，也可以显式指定。
+
+## 设计理念
+
+### 先做，后理解
+
+这颠覆了传统计算机教育。老方法：背概念好几年 → 终于做点东西 → 最后才明白为什么（大多数人在第三步之前就放弃了）。新方法：**先做出来 → 体验它能工作 → 现在理解它是怎么工作的。**
+
+### 展示，而非告知
+
+每个页面至少 50% 是视觉内容。每个文字块最多 2-3 句话。如果某个东西可以做成图表、动画或交互元素——它就不应该是一个段落。
+
+### 测验考的是做，而非知道
+
+不是考 "API 的全称是什么？"，而是："用户反馈切换页面后数据是旧的。你会先看哪里？"测验考的是你能不能*用*学到的东西解决新问题。
+
+### 不复用隐喻
+
+每个概念都有一个适合*那个特定想法*的隐喻。数据库是一个带卡片目录的图书馆。认证是一个检查身份证的门卫。API 限流是一个有容量限制的夜店。同一个隐喻不会用两次。
+
+### 只用原始代码
+
+代码片段是从真实代码库中原样复制的——从不修改或简化。学习者应该能打开实际文件，看到和他们学习时一样的代码。
+
+## 技能结构
+
+```
+codebase-to-course/
+├── SKILL.md                          # 主技能指令（两种模式）
+└── references/
+    ├── _base.html                    # HTML 模板外壳
+    ├── _footer.html                  # 共享页脚和导航逻辑
+    ├── styles.css                    # 所有样式（两种模式 + 工程师元素）
+    ├── main.js                       # 交互逻辑（测验、文件地图等）
+    ├── build.sh                      # 组装单一 HTML 文件的 Shell 脚本
+    ├── design-system.md              # CSS 令牌、字体、颜色、布局
+    ├── interactive-elements.md       # 全部 25 种交互元素模式
+    ├── content-philosophy.md         # 各模式的内容写作哲学
+    ├── gotchas.md                    # 常见错误及避免方法
+    └── module-brief-template.md      # Phase 2.5 规划检查点模板
+```
+
+## 更新日志
+
+### v2.0.0 — 工程师模式（2025）
+
+- 新增**工程师模式**：一个完全不同的产品，面向做技术尽调的专业工程师
+- 8 种新交互元素：ADR 卡片、关键路径追踪、权衡矩阵、场景判断器、集成蓝图、源文件地图、风险指标、裁决标注
+- **源文件地图**：带注释的目录树，将 30-50 个关键文件分为"框架性"（骨架/架构）和"功能性"（具体实现），并推荐首读顺序
+- 工程师模式的代码块风格从"代码 ↔ 自然语言"改为"代码 ↔ 工程分析"
+- 新增 `content-philosophy.md` 和 `gotchas.md` 作为独立参考文件
+- 新增 Phase 2.5 规划检查点，用于复杂代码库
+- Phase 3 拆分为顺序构建（简单项目）和并行构建（复杂项目）两条路径
+- 技能结构更新，包含 HTML 模板、CSS、JS 和构建脚本
+
+### v1.0.0 — 初始版本
+
+- 入门模式，支持滚动导航、动画可视化、交互式测验和术语提示
+- 单一 HTML 文件输出，无依赖
+
+---
+
+原版由 [Zara](https://x.com/zarazhangrui) 使用 Claude Code 构建。工程师模式和中文文档由 [fogdragon](https://github.com/fogdragon) by Qwen3.7-Max 添加。