--- url: https://docs.nemo12.com/reference/curriculum-pearl-standard.md description: >- Chuẩn canonical cho curriculum năng lực đăng ở pearl.nemo12.com/curriculum, kiểm tự động bằng script thay vì văn xuôi rải rác. --- # Chuẩn curriculum năng lực trên Pearl (SRC-448) Tài liệu này là **nguồn canonical** cho mọi curriculum đăng ở `pearl.nemo12.com/curriculum/`. Trước nó, các ràng buộc nằm rải trong văn xuôi của chính trang Pearl và trong yêu cầu miệng, nên không kiểm được tự động và mỗi phiên dựng một kiểu. Kiểm bằng `node scripts/check-curriculum-pearl.mjs`. ## Bảng số lượng, tra nhanh (SRC-493) Chủ dự án hỏi 2026-08-21 "tối thiểu mỗi Module có tối thiểu 5 unit đúng không". Không phải 5, và cũng không chỉ có cận dưới. Toàn bộ ngưỡng đang được cổng kiểm thi hành: | Tầng | Cây năng lực (Pearl) | Cây kiến thức (D1) | |---|---|---| | Package mỗi môn | **đúng 5** | không ràng buộc | | Module mỗi Package | **3 tới 6** | tối thiểu 6 | | Unit mỗi Module | **3 tới 6** | tối thiểu 6 | | Key concept mỗi Unit | **1 tới 2** | không áp dụng | | Lab mỗi Unit đang hiện | tối thiểu 1, và tối đa 1 lab `live` | như bên trái | Cận TRÊN quan trọng ngang cận dưới: một Module 10 unit thì learner không còn cảm giác đi hết được nó, và phụ huynh mất bức tranh tổng thể. Cận dưới thì bảo vệ chuyện khác: một tầng chỉ có 2 mục là tầng không chia gì cả, chỉ là một cái tên trung gian. Muốn xem hiện trạng từng môn thì chạy trình kiểm, nó in bảng số thật ở đầu ra. Con số không được chép vào đây, vì chép là để nó lệch. ## 0. Hai cây, hai luật, và vì sao chúng khác nhau Đây là chỗ dễ hiểu nhầm nhất, nên nói trước. Nemo12 có **hai cây curriculum song song**, và chúng chịu hai luật số lượng **ngược nhau**: | | Cây kiến thức (D1) | Cây năng lực (Pearl) | |---|---|---| | **Ở đâu** | bảng `skill_nodes` trong D1, learner luyện trên đó | `apps/pearl/content/curriculum/` | | **Trục** | theo chủ đề: Cơ học, Nhiệt học, Đại số… | theo năng lực: Observe, Explain, Reason… | | **Luật** | [6/6/6](curriculum-666.md), **tối thiểu** 6 mỗi tầng (SRC-185) | **3 tới 6** mỗi tầng (SRC-238) | | **Vì sao** | tối ưu cho **độ phủ**: thiếu node là learner mất bài | tối ưu cho **sức nhớ**: quá 6 thì phụ huynh mất bức tranh tổng thể | Hai luật này **không mâu thuẫn** vì chúng áp lên hai vật khác nhau. Nhầm lẫn xảy ra khi ai đó đọc 6/6/6 rồi áp vào Pearl, hoặc ngược lại. **Quy tắc quyết định:** file nằm trong `apps/pearl/content/curriculum/` thì theo tài liệu này. Dữ liệu nạp vào D1 thì theo [curriculum-666.md](curriculum-666.md). ## 1. S1 · Cấu trúc và số lượng ```text Môn học └── Learning Package 3-6 một năng lực learner phải chứng minh được └── Module 3-6 một mảnh của năng lực đó, đo riêng được └── Unit 3-6 cụm học được trong một lần ngồi └── Key concept 1-2 ``` * **Dưới 3**: tầng đó không chia gì cả, chỉ là một cái tên trung gian. * **Trên 6**: vượt sức nhớ của người đọc. * Số unit trong bảng ở trang package **phải khớp** số unit trên trang module tương ứng. ## 2. S2 · Đặt tên Tiếng Anh trước, tiếng Việt trong ngoặc đơn, ở **mọi tầng**: môn, package, module, unit, key concept. ```text # Module 3.1 · Forces and motion (Lực và chuyển động) ## Unit 2 · Why things stop (Vì sao vật dừng lại) ``` ## 3. S3 · Trang tổng quan môn Bắt buộc có, theo thứ tự: khối `pearl-bigidea` (một ý xuyên suốt cả môn) · khối `pearl-also` (vài ý bổ sung, **cố ý không đặt ngang hàng**) · lưới `pearl-grid` các package · bảng package kèm câu "Tôi sẽ làm được gì" · mục lớp theo chuẩn Việt Nam · bảng key concepts · bảng coverage chương trình · khối `::: warning Trạng thái` · mục Nguồn · một câu kết dạng trích dẫn. ## 4. S4 · Trang package Bắt buộc: khối `pearl-bigidea` · bảng meta có `Module`, `Unit`, `Mastery level`, và thông tin lớp · danh sách module · bảng **toàn bộ unit** có cột mastery level và lớp · mục "Chỗ hay bị bỏ qua" · link sang package kế tiếp. **Hai tiêu đề hợp lệ cho khối bigidea**, và thân bài phải khớp tiêu đề: | Tiêu đề | Thân bài nói gì | Dùng khi | |---|---|---| | `Tôi sẽ làm được gì` | câu năng lực ngôi thứ nhất | mặc định cho môn mới | | `Ý xuyên suốt package` | câu chủ đề về bản chất của package | khi package có một ý nền đáng nói hơn một câu năng lực | Không ép đổi qua lại: đổi tiêu đề mà không viết lại thân bài tạo ra trang tự mâu thuẫn. **Hai bố cục hợp lệ cho danh sách module**: bảng `| **1.1 · Tên** | mô tả | số unit |`, hoặc từng mục dạng "## Module 1.1 · Tên" có link kèm đoạn mô tả. Bố cục thứ hai giàu hơn và nên dùng khi mỗi module đáng được nói một đoạn. **Bất biến bắt buộc**: số module ghi ở meta = số module được liệt kê = số trang module tồn tại trong thư mục. Lệch nhau nghĩa là có trang mồ côi hoặc có module bị bỏ quên. Tên module phải là **link tới trang module** khi trang đó đã tồn tại. ## 5. S5 · Trang module, và sáu phần của một unit Trang module bắt buộc có khối `pearl-bigidea` "Tôi sẽ làm được gì", bảng meta, một mục **"Dạy module này theo kiểu ..."**, và link sang module kế tiếp. Khuôn sư phạm không bắt buộc phải là IB. Mười một môn dùng `theo kiểu IB`; môn Advanced Mathematics dùng `theo kiểu AoPS`, vì problem-first mới là sư phạm của môn đó. Điều bắt buộc là **có một mục chỉ ra cách dạy cụ thể**, không phải tên của khuôn. **Mỗi unit phải đủ sáu phần**, không phần nào bỏ được: ```markdown ## Unit 2 · Why things stop (Vì sao vật dừng lại) > **Tôi sẽ làm được** giải thích vì sao vật đang chuyển động lại chậm dần và dừng. **Mastery level 4-8 · Lớp 5-9 · Forces (Lực) · Interaction (Tương tác)** | Bậc | Learner làm được gì | | --- | --- | | **Đang hình thành** | … | | **Đạt** | … | | **Vững** | … | **Bằng chứng đạt.** … **Hiểu lầm thường gặp.** … **Knowledge node.** … ``` Vì sao đủ sáu phần mới dùng được: * **Thiếu "Bằng chứng đạt"** thì unit không đo được, và bảng ba bậc thành mô tả cảm tính. * **Thiếu "Hiểu lầm thường gặp"** thì mất đúng phần có giá trị dạy học cao nhất: chỗ learner đã có sẵn một mô hình sai cần phá, chứ không phải chỗ learner thiếu thông tin. * **Thiếu "Knowledge node"** thì unit không ánh xạ được sang cây kiến thức trong D1, tức là curriculum này không bao giờ chạy được trong hệ thống. **Khung câu bắt buộc dùng tiếng Việt**: `> **Tôi sẽ làm được** …` (SRC-253). Không dùng `> **I will be able to**`. ## 5b. S9 · Cấm nội dung vỏ mẫu Ba bậc trong bảng phải mô tả **hành vi quan sát được của chính unit đó**. Cấm dùng mô tả chung chung dùng lại được cho mọi unit: ```text SAI Đang hình thành | Làm được khi có người gợi từng bước Đạt | Tự làm được trên bài quen, nói ra được vì sao làm thế Vững | Dùng được sang bài chưa gặp, và chỉ ra được chỗ người khác làm sai ĐÚNG Đang hình thành | Đếm được tới 20 nhưng phải chỉ tay từng vật Đạt | Đếm tiếp từ số đã có thay vì đếm lại từ đầu Vững | Biết 7 gộp từ nhiều cặp khác nhau mà không cần đếm ``` Bảng vỏ mẫu tệ hơn không có bảng: nó **trông như đã đo được** trong khi chưa đo gì cả, nên không ai đi kiểm lại. Câu `> **Tôi sẽ làm được** …` phải là một **câu khẳng định về hành vi**, không phải câu hỏi. ## 6. S6 · Chữ và dấu Không dùng em dash trong **chữ người dùng đọc**: trang Pearl, nội dung câu hỏi, lab, popover, và mọi chuỗi hiện trên màn app. Thay bằng dấu phẩy, hai chấm, hoặc gạch nối thường. Cổng `scripts/check-no-emdash.mjs` quét 8 app, khuôn thư trong `workers/api/src/modules/email`, và file `.sql` (có trần), bỏ qua chú thích mã và biểu thức chính quy phải khớp em dash trong dữ liệu cũ (SRC-142, SRC-379, mở rộng SRC-748). Luật đầy đủ và luật ngày `DD.MM.YYYY`: [conventions §5.1](../conventions.md). **Phạm vi này hẹp hơn câu chữ cũ, và sửa lại là cố ý** (SRC-603). Bản trước ghi "không dùng trong bất kỳ tài liệu nào", trong khi chính `docs/` đang có gần 4.800 em dash và không cổng nào quét tới đó. Một luật bị chính kho tài liệu bác bỏ hàng nghìn lần thì nó không còn là luật: nó dạy người đọc rằng luật ở đây là để trang trí, và người đọc mang thái độ ấy sang những luật thật sự quan trọng. Muốn mở rộng sang `docs/` thì phải mở rộng cổng trước, rồi mới sửa câu chữ; không làm ngược lại. ## 7. S7 · Môn đã có cây kiến thức thì phải nói rõ Môn nào đã có cây nội dung theo chủ đề đang chạy trong D1 thì trang tổng quan **bắt buộc** có mục nêu quan hệ hai trục, kèm sơ đồ `Trục kiến thức` và `Trục năng lực`, và nói rõ cây năng lực **không thay thế** cây kia. Tính tới 2026-08-21: Vật lý, Hoá học (SRC-189); Tin học, IELTS, SAT, AP, GenAI (SRC-185). ## 8. S8 · Nối với khu vực demo IB Môn nào có trang ở `/ideas/inquiry-ib/` thì phải nối **hai chiều**: trang môn có mục trỏ sang demo, trang demo có bảng "ba bài này nằm ở đâu trong curriculum" trỏ xuống tới từng module. ## 8a. S11 · Số liệu viết trong văn xuôi phải khớp thực tế Mọi con số dạng `N module, M unit` viết trong thẻ ở trang khu vực hoặc trang môn **phải khớp** số trang module và số unit thật sự tồn tại. Đây là luật ra đời từ kinh nghiệm: trong đợt audit SRC-448, số liệu lệch được tìm thấy **ba lần liên tiếp** ở ba chỗ khác nhau, có chỗ lệch gấp ba lần (`van/comprehend` ghi 9 unit trong khi thực tế 26). Nguyên nhân luôn giống nhau: một phiên thêm hoặc tách module rồi quên cập nhật trang cha. Con số sai ở đây đặc biệt độc vì **nó trông đáng tin**: người đọc không có cách nào biết nó lệch, và nó là thứ phụ huynh dùng để hình dung quy mô môn học. Trang lẻ của một môn (ví dụ danh sách tác phẩm ở `curriculum/van/tac-pham.md`) **không tính là trang module**: trang module chỉ nằm ở `//.md`. ## 8b. S10 · Ngoại lệ phải được ghi nhận, không được im lặng Một môn có thể **cố ý chưa đạt một luật**, thường vì nó đang phản chiếu cây kiến thức trong D1 mà cây đó chưa đủ. Điều này chấp nhận được, với một điều kiện: **ngoại lệ phải được ghi ra**. Cách ghi: trong khối `::: warning Trạng thái` của trang tổng quan môn, nêu rõ tên luật bị vi phạm và lý do. ```markdown ::: warning Trạng thái Cây này phản chiếu đúng cây AP đang chạy trong D1 (mỗi package hiện có một module) nên chưa đạt luật 3-6 module mỗi package của **chuẩn S1**: giới hạn của cây đang chạy, không phải của thiết kế. ::: ``` Trình kiểm dò cụm `chuẩn S` trong khối đó và hạ các lỗi thuộc luật ấy xuống mức `info` cho riêng môn đó. Vì sao làm thế thay vì bỏ luật đi: một ngoại lệ được ghi ra thì **người đọc thấy được**, và nó tự nhắc rằng còn việc phải làm. Một ngoại lệ im lặng thì không phân biệt được với một lỗi bị bỏ quên. ## 9. Mức độ nghiêm trọng | Mức | Nghĩa | Xử lý | |---|---|---| | **error** | vi phạm ràng buộc cấu trúc hoặc thiếu phần bắt buộc | phải sửa trước khi coi môn là xong | | **warn** | lệch chuẩn nhưng trang vẫn dùng được | sửa khi đụng tới file đó | | **info** | trạng thái chưa hoàn thiện đã biết | không phải lỗi | ## Trace | Điều | Nguồn | |---|---| | 3-6 mỗi tầng, 1-2 key concept | SRC-238 | | Tiếng Anh trước, tiếng Việt trong ngoặc | SRC-246 | | Khung "Tôi sẽ làm được" bằng tiếng Việt | SRC-253 | | Mỗi unit có mastery level và lớp | SRC-245 | | Không dùng em dash | SRC-142 | | Quan hệ hai trục với cây 6/6/6 | SRC-185, SRC-189 |