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, 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.

1. S1 · Cấu trúc và số lượng

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.

# 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:

## 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:

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.

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 ở <môn>/<package>/<module>.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.

::: 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<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