diff --git a/.claude/memory/class/AICODE03橙子周六1900/补课/20260613_AICODE03-15_钟嘉鑫.md b/.claude/memory/class/AICODE03橙子周六1900/补课/钟嘉鑫/feedback/20260613_AICODE03-15.md
similarity index 100%
rename from .claude/memory/class/AICODE03橙子周六1900/补课/20260613_AICODE03-15_钟嘉鑫.md
rename to .claude/memory/class/AICODE03橙子周六1900/补课/钟嘉鑫/feedback/20260613_AICODE03-15.md
diff --git a/.claude/memory/class/AICODE03橙子周六1900/补课/20260613_AICODE03-15_黄浩.md b/.claude/memory/class/AICODE03橙子周六1900/补课/黄浩/feedback/20260613_AICODE03-15.md
similarity index 100%
rename from .claude/memory/class/AICODE03橙子周六1900/补课/20260613_AICODE03-15_黄浩.md
rename to .claude/memory/class/AICODE03橙子周六1900/补课/黄浩/feedback/20260613_AICODE03-15.md
diff --git a/.claude/memory/class/CLAUDE.md b/.claude/memory/class/CLAUDE.md
index 8d81337..98d2471 100644
--- a/.claude/memory/class/CLAUDE.md
+++ b/.claude/memory/class/CLAUDE.md
@@ -202,4 +202,26 @@
 
 ---
 
+---
+
+## 🪤 踩坑日常
+
+> 记录课评工作中的坑点，避免重复犯错。
+
+### 1. 补课学生必须创建独立文件夹结构（2026-06-13）
+
+**问题**：补课学生的课评文件直接放在 `补课/` 根目录下，没有创建学生子文件夹和 `feedback` 目录。
+
+**正确结构**：
+```
+补课/
+├── 【学生姓名】/
+│   └── feedback/
+│       └── YYYYMMDD_课程编号-课次.md
+```
+
+**注意**：文件名只用 `时间_课程编号-课次.md`，**不带学生姓名**。
+
+---
+
 *班级课评核心规范 v1.0*
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
index 46dac5a..2bd9938 100644
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -136,7 +136,12 @@
       "Bash(mkdir -p \"E:/cc/4work_project/ClassFeedback/.claude/agents/家长-忙碌实用型\")",
       "Bash(mkdir -p \"E:/cc/4work_project/ClassFeedback/.claude/docs\")",
       "Bash(mv \"E:/cc/4work_project/ClassFeedback/课评质检系统/课评质量标准.md\" \"E:/cc/4work_project/ClassFeedback/.claude/docs/\")",
-      "Bash(mv \"E:/cc/4work_project/ClassFeedback/课评质检系统/实战案例-CSP05-14贪心算法.md\" \"E:/cc/4work_project/ClassFeedback/.claude/docs/\")"
+      "Bash(mv \"E:/cc/4work_project/ClassFeedback/课评质检系统/实战案例-CSP05-14贪心算法.md\" \"E:/cc/4work_project/ClassFeedback/.claude/docs/\")",
+      "Bash(mkdir -p \"钟嘉鑫/feedback\" \"黄浩/feedback\")",
+      "Bash(mv \"20260613_AICODE03-15_钟嘉鑫.md\" \"钟嘉鑫/feedback/\")",
+      "Bash(mv \"20260613_AICODE03-15_黄浩.md\" \"黄浩/feedback/\")",
+      "Bash(mv \"钟嘉鑫/feedback/20260613_AICODE03-15_钟嘉鑫.md\" \"钟嘉鑫/feedback/20260613_AICODE03-15.md\")",
+      "Bash(mv \"黄浩/feedback/20260613_AICODE03-15_黄浩.md\" \"黄浩/feedback/20260613_AICODE03-15.md\")"
     ]
   }
 }
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d5a4474
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# ClassFeedback — 课评生成与课堂反馈管理系统
+
+穹狼科创多课程体系的课评生成工具。支持 CSP 信奥、AICODE 创意编程、Kitten 图形化三大课程，通过 AI 自动生成个性化课评，集成 OJ 做题数据和出勤管理。
+
+## 项目信息
+
+- **项目编号**：02
+- **所属**：穹狼科创
+- **管理班级**：9个班，33名学生
+- **课程类型**：CSP / AICODE / K4 / 体验课
+
+## 文件结构
+
+```
+ClassFeedback/
+├── CLAUDE.md                    # Claude Code 工作指引（核心文档）
+├── .env                         # API 配置（校宝 + OJ，不要提交到 Git）
+├── scripts/                     # 自动化脚本（详见下方）
+├── config/
+│   └── hw_dict.json             # OJ 作业包 ID 映射表（CSP01-CSP07）
+├── data/                        # API 拉取的原始数据
+├── output/                      # 生成产物
+│   ├── 课评汇总/                # 按周归档的课评（HTML 格式）
+│   ├── CSP03课前小测/           # 课前测试题
+│   ├── AICODE03提示词/          # AI 课提示词手册
+│   ├── AI03网页/                # 学生作品演示页面
+│   ├── 家长沟通/                # 家长沟通记录
+│   └── *.md / *.html            # 其他生成文件
+├── docs/                        # 文档
+│   ├── README_OJ.md             # OJ 数据集成功能说明
+│   └── README_备份说明.md        # Git 备份方案说明
+└── input/                       # 输入文件（待整理）
+```
+
+## 脚本说明
+
+| 脚本 | 语言 | 用途 |
+|------|------|------|
+| `analyze_course_student.py` | Python | 通过校宝 API 分析指定课程/学生/课次数据 |
+| `split_feedback.py` | Python | 课评拆分 v1：从课评文本按班级拆分为独立条目 |
+| `split_feedback_v2.py` | Python | 课评拆分 v2：解析逻辑改进版 |
+| `update_feedback_with_oj.py` | Python | 登录 OJ 获取做题数据，追加到反馈文件 |
+| `write_lesson10.py` | Python | 第十课课评批量写入 |
+| `check-api-vs-local.js` | Node.js | API 出勤记录与本地课评交叉核对 |
+| `query-attendance.js` | Node.js | 查询指定时间段的整体出勤率 |
+| `backup.bat` | BAT | Git 本地备份脚本 |
+
+## 使用方式
+
+### 日常工作流（通过 Claude Code）
+
+```
+1. 确认上课信息（班级、课次）
+2. 读取学生档案和风格指南
+3. 提供课堂内容（出勤、作业、表现）
+4. AI 生成课评 → 用户确认 → 保存归档
+```
+
+### 查询 OJ 数据
+
+```bash
+# 直接对话：「帮我查一下杨林轩最近的做题情况」
+# 指定班级：「查 CSP03 本周 OJ 做题数据」
+# 详细用法见 OJ作业数据API使用说明.md
+```
+
+### 查询出勤率
+
+```bash
+node scripts/query-attendance.js
+```
+
+## 相关文档
+
+- [[CLAUDE.md]] — 完整工作流程和班级信息
+- [[OJ作业数据API使用说明.md]] — OJ API 使用手册
+- [[docs/README_OJ.md]] — OJ 数据集成说明
+- [[docs/README_备份说明.md]] — 备份方案
+
+---
+
+*维护者：橙子*
+*最后更新：2026-06-16*