Skill: teach-me
WHAT
Purpose và context
- Purpose: giải thích MỘT thứ theo khung cố định bảy bước, căn theo người nghe, với bước "Cơ chế hoạt động" chứng bằng runtime thật rồi dọn sạch instrument.
- Trigger (when to use):
- User muốn hiểu sâu MỘT thứ cụ thể: một file, một hàm, một tính năng, một hệ thống con, một khái niệm, một thông báo lỗi — "cái này chạy thế nào", "giải thích cho tôi".
- User muốn giải thích thứ đó cho MỘT NGƯỜI NGHE cụ thể — "ELI5", "nói với sếp thế nào", "giải thích cho designer", "cho bố mẹ tôi hiểu".
- Non-goals: KHÔNG dùng cho: hiểu cả một codebase lạ (đó là → wiki, hoặc → orient nhanh read-only). teach-me hẹp và sâu, không ghi wiki.
Mental model
người nghe → phạm vi + nguồn → quan sát runtime (đầu vào → state ở dòng nào) → Người nghe · TL;DR + so sánh → 7 phần → So what (độ sâu theo người nghe) → dọn instrument
.
Input và output contract
| Field | Required? | Ý nghĩa |
|---|
| In | thứ cần giải thích | có | không rõ → hỏi một câu kèm gợi ý |
| In | người nghe | không | mặc định engineer; "ELI5" không kèm ai → trẻ 5 tuổi |
| Out | câu trả lời theo Khung output | có | đủ mọi khối, đúng thứ tự |
| Out | sơ đồ | có | mặc định mermaid inline; HTML explainer chỉ khi user đồng ý |
| Out | code người dùng sạch instrument | có khi có chèn | xác nhận |
Rules và capabilities
- RULE-01 (MUST): Đủ khung, đúng thứ tự, không gộp tắt — Người nghe → TL;DR → bảy phần → So what. Thiếu một phần (kể cả khi "hiển nhiên" hay "không áp dụng") thì nói rõ vì sao thiếu, không lặng lẽ bỏ qua.
- RULE-02 (MUST): Người nghe đổi CÁCH NÓI, không đổi SỰ THẬT — được lược chi tiết, được đơn giản hoá mạnh cho người không kỹ thuật (truyền được 80% ý cốt lõi còn hơn 100% chính xác mà người nghe bỏ cuộc), nhưng KHÔNG nói sai; chỗ lược mạnh ghi "(đã đơn giản hoá)". Nén bằng chứng thành một câu cho người không kỹ thuật thì câu đó không được nói to hơn điều đã quan sát (thấy một ca → nói "một ca", không nói "luôn luôn"); con số (số lần sửa, số dòng, số file) đếm lại từ git/đĩa, không ước.
- RULE-03 (MUST): Không bao giờ nói giọng bề trên — giải thích cho trẻ 5 tuổi phải thấy thú vị chứ không phải bị "làm ngu đi"; giải thích cho manager phải thấy được trao quyền quyết, không bị coi là không hiểu.
- RULE-04 (MUST): Người nghe không kỹ thuật = không code, kể cả backtick — không code block, không định dạng cho tên file/thư mục (bài học eval eli5: bản có skill vẫn trượt vì backtick tên thư mục khi viết cho manager).
- RULE-05 (MUST): Chứng bằng runtime, không đoán: phần "Cơ chế hoạt động" ưu tiên DRIVE code thật. Chỉ khi không chạy được (thiếu môi trường, cần prod) mới giải thích tĩnh — và nói rõ "đây là giải thích tĩnh, chưa chứng bằng chạy". Khẳng định phụ thuộc runtime chưa quan sát → ghi nợ
[[150726-unknown-ledger]]
- RULE-06 (MUST): Instrument tạm → DỌN SẠCH: mọi /// chèn để quan sát phải gỡ hết; xác nhận trước khi kết thúc.
- RULE-07 (MUST): Phạm vi MỘT thứ: teach-me không phân tích cả dự án (đó là /) và không ghi wiki.
- RULE-08 (MUST): Không đẻ debugger mới — dùng công cụ có sẵn (pdb/debugpy · node --inspect · print/log · /run · /verify).
- RULE-09 (MUST): Trade-off và Giới hạn không được lẫn vào nhau — Trade-off là đánh đổi CÓ CHỦ ĐÍCH lúc thiết kế; Giới hạn là biên nó KHÔNG VƯỢT QUA ĐƯỢC dù muốn, thường lộ ra khi dùng thật.
- RULE-10 (MUST): Loạt bài nhiều thứ thì đếm theo bề mặt, không theo số bài — khi teach-me được gọi lặp để dựng một bộ bài học cho cả app (hoặc user hỏi "đã đủ chưa"), KHÔNG báo "N bài" như thể đã phủ hết: chạy skill ( + ) và báo kèm danh sách chưa có bài (GH#191).
- Capabilities: đọc code/tài liệu; chạy code cục bộ với debugger/log có sẵn; ghi tạm instrument (gỡ trước khi kết thúc); không ghi wiki.
Failure boundaries
- Không chạy được (thiếu môi trường, cần prod) → giải thích tĩnh, nói rõ chưa chứng bằng chạy; khẳng định chưa quan sát → ghi nợ unknown-ledger.
- Phạm vi mơ hồ → clarify một câu.
- Yêu cầu hiểu cả dự án → cancelled, chuyển /.
- Còn instrument trong → chưa xong.
HOW
Main workflow
| Step | Type | Inputs | Action | Outputs/exit | Failure/next |
|---|
| W01 | judgment | câu hỏi | Xác định người nghe | một nhóm + điều họ quan tâm | không nêu → engineer |
| W02 | judgment | thứ cần giải thích | Xác định phạm vi + đọc đúng loại nguồn | hiểu mục đích | không rõ → hỏi |
| W03 | effect | code/ca nhỏ | DRIVE runtime với đầu vào cụ thể + instrument tạm | ít nhất một quan sát runtime | không chạy được → B01 |
| W04 | judgment | quan sát + người nghe | Sinh output theo Khung output, độ sâu theo bảng | đủ mọi khối | — |
| W05 | deterministic | code đã chèn | Gỡ instrument, | diff sạch | còn → gỡ tiếp |
Chi tiết từng bước (nguồn chân lý cho W01–W05):
- Xác định NGƯỜI NGHE — đọc câu hỏi, xếp vào một nhóm ở bảng "Người nghe" dưới. Không nêu → mặc định người đang hỏi = engineer (teach-me là skill của dev); riêng từ khoá "ELI5"/"như cho trẻ 5 tuổi" không kèm ai khác → trẻ 5 tuổi. → Xong khi chốt được một nhóm + điều họ quan tâm.
- Xác định phạm vi + đọc nguồn — user chỉ đích danh thứ cần giải thích; không rõ → hỏi một câu kèm gợi ý từ context. Đọc đúng loại nguồn: code → đọc code, hiểu mục đích trước cú pháp; khái niệm → tách thành phần cốt lõi; thông báo lỗi → tìm nguyên nhân gốc, không dịch lại câu chữ bề mặt; tài liệu → rút các ý thật sự quan trọng với người nghe.
- DRIVE runtime (nếu chạy được) — chạy với một đầu vào cụ thể, thêm instrument/breakpoint tạm, quan sát state thật. Instrument chèn vào code người dùng thì làm trên bản copy hoặc gỡ ở bước 5. → Xong khi có ít nhất một quan sát runtime cụ thể (đầu vào → state ở dòng nào). Không chạy được → ghi "giải thích tĩnh" (mục Rules).
- Sinh output theo "Khung output" — dòng Người nghe → TL;DR + phép so sánh → bảy phần ĐÚNG THỨ TỰ → So what; độ sâu từng phần theo bảng "Độ sâu theo người nghe". → Xong khi đủ mọi khối, không phần nào bị bỏ trống hoặc gộp tắt vào phần khác.
- DỌN SẠCH instrument — gỡ mọi // tạm đã chèn; xác nhận code người dùng sạch như trước. → Xong khi diff không còn instrument tạm.
Branches
| ID | Kind | Guard | Hành vi | Skip / failure | Rejoin |
|---|
| B01 | recovery | không chạy được code (thiếu môi trường, cần prod) | giải thích tĩnh, ghi rõ "đây là giải thích tĩnh, chưa chứng bằng chạy" | khẳng định chưa quan sát → nợ unknown-ledger | W04 |
| B02 | user_optional | user muốn giữ/chia sẻ/cần hình đẹp | HTML explainer theo , sơ đồ gọi | không đồng ý → mermaid inline | W05 |
| B03 | conditional_required | người nghe không kỹ thuật | không code block, không backtick; bằng chứng nén một câu | — | W05 |
Validation và stopping
Kiểm được: đủ khối và đúng thứ tự, không code/backtick cho người nghe không kỹ thuật,
sạch instrument. Cần mắt: phép so sánh hợp người nghe, không giọng bề trên. Sửa skill thì đo lại bằng eval A/B (mục Reference — Eval).
Examples
- Positive: "giải thích cho tôi" → engineer; chạy với repo thật, exit code + danh sách file ⇐ → quan sát "exit 3, 2 trang cờ drift" → TL;DR + bảy phần có flowchart + sequence → gỡ , sạch.
- Boundary/failure: "nói với sếp vì sao trang báo cáo chậm" nhưng chỉ có log prod, không chạy được local → giải thích tĩnh có ghi rõ, không code block/backtick, ≈ 700 chữ, chốt bằng đề xuất; không khẳng định "luôn luôn" khi mới thấy một ca.
Reference — Bạn ĐƯỢC DÙNG công cụ để CHỨNG, không chỉ đọc
Câu "nó chạy thế nào" phải được chứng bằng runtime thật, không suy đoán từ đọc tĩnh. Công cụ trong môi trường Claude Code:
- Python: , hoặc tạm, hoặc . Rẻ hơn: chèn / ở điểm quan tâm rồi chạy.
- Node/JS: , , tạm, hoặc ở điểm quan tâm.
- Khái niệm/công cụ (git, HTTP, SQL…): dựng ca nhỏ nhất trong thư mục tạm rồi chạy thật (vd hai nhánh sửa cùng dòng → merge → thấy conflict thật).
- Bất kỳ: built-in (chạy app thật) và (drive flow, quan sát hành vi). Chạy với đầu vào cụ thể, quan sát state thật ở dòng cụ thể.
"Hàm này chắc trả về X" là phỏng đoán. "Tôi chạy với đầu vào Y, đặt breakpoint ở dòng Z, quan sát state là W" là dữ kiện. Luôn ưu tiên dữ kiện — với MỌI người nghe. Người nghe chỉ đổi cách TRÌNH BÀY bằng chứng, không đổi việc PHẢI có bằng chứng.
Reference — Người nghe — họ quan tâm gì, so sánh bằng gì, giọng nào
| Nhóm | Họ quan tâm | Phép so sánh lấy từ | Giọng |
|---|
| Engineer (mặc định) | chạy thế nào, kiến trúc, trade-off, bảo trì | thứ họ đã biết: "giống hash map nhưng…", pattern quen | chính xác, gọn, dùng đúng thuật ngữ (thiếu thuật ngữ họ thấy bị coi thường) |
| Đồng nghiệp khác mảng | ảnh hưởng tới việc của họ, cần biết gì để phối hợp | công việc chung, quy trình team | thực tế, "cái này đổi gì với bạn" |
| Manager | tác động, rủi ro, thời gian, chi phí, năng lực đội | kết quả kinh doanh, nhân sự, ngân sách | dẫn bằng tác động, định lượng khi được, chốt bằng quyết định cần đưa ra |
| Director | chiến lược, ROI, lợi thế cạnh tranh | bức tranh lớn, phân bổ nguồn lực | toàn cảnh, ngắn |
| Product Manager | giá trị cho người dùng, ưu tiên, phạm vi | user story, làm gì / bỏ gì | theo tính năng và người dùng |
| Designer | trải nghiệm, luồng tương tác, accessibility | màn hình, thao tác người dùng thấy | theo cái người dùng nhìn và bấm |
| Sinh viên / cao học | lý thuyết + ứng dụng; cao học: sắc thái, ca biên, hệ quả sâu | kiến thức nền môn học | học thuật; thuật ngữ kèm ngữ cảnh ngắn |
| Học sinh cấp 2–3 (≈12–17 tuổi) | nhân quả rõ, từng bước | điện thoại, mạng xã hội, game, trường lớp | hơi thân mật, không "làm màu trẻ trung" |
| Trẻ ≈10 tuổi / lớp 5 | nhân quả cơ bản | trường học, thể thao, bài tập nhóm, trò chơi điện tử | như cô giáo được yêu thích |
| Trẻ 5 tuổi (khi "ELI5") | một ý dễ nhớ | đồ chơi, con vật, kẹo, sân chơi, sách tranh | vui, hào hứng, câu rất ngắn |
| Bố mẹ / người lớn tuổi | hiểu mà không bị coi thường | công nghệ họ đang dùng, việc nhà | tôn trọng, rõ, kiên nhẫn |
| Vợ/chồng/bạn đời, bạn bè | câu chuyện dễ theo | việc thường ngày, trải nghiệm chung, văn hoá đại chúng | ấm, trò chuyện, có thể hài hước |
Reference — Khung output (cố định — ĐÚNG THỨ TỰ, không khối nào bị bỏ)
Người nghe: <nhóm> — <điều họ quan tâm>
TL;DR: <MỘT câu "nó là gì"> + <MỘT phép so sánh với thứ người nghe đã biết>
↓
1. Tên gọi → 2. Nguồn gốc → 3. Lý do tồn tại → 4. Cơ chế hoạt động
→ 5. Trade-off → 6. Giới hạn → 7. Vị trí trong toàn bộ hệ thống
↓
So what: <điều này có nghĩa gì với CHÍNH người nghe — quyết định, hành động, hay điều cần nhớ>
Bảy phần là mạch một câu chuyện: nó tên gì → từ đâu ra → vì sao phải có → nó chạy ra sao → đánh đổi gì để có nó → nó KHÔNG làm được gì → nó đứng ở đâu trong bức tranh lớn. TL;DR + so sánh mở cửa (người nghe biết ngay đang nói về cái gì); So what đóng cửa (người nghe biết mang về làm gì). Mục đích luôn đi trước cơ chế — không ai quan tâm cú pháp khi chưa biết nó tồn tại để làm gì.
Tên bảy tiêu đề giữ nguyên với mọi người nghe (để user tự kiểm khung); với người nghe không kỹ thuật được thêm phụ đề đời thường, vd "5. Trade-off — được gì, mất gì".
1. Tên gọi
Tên chính xác (đúng danh xưng dùng trong code/docs), tên/thuật ngữ đồng nghĩa hay gặp, và nếu tên gây hiểu lầm (đặt sai bản chất) thì nói rõ luôn ở đây.
2. Nguồn gốc
Nó xuất hiện từ đâu — commit/PR/quyết định nào đưa nó vào, mượn ý tưởng từ đâu (thư viện/paper/pattern có sẵn hay tự nghĩ ra), tình huống nào tạo ra nhu cầu này lần đầu. Có bằng chứng thật (git log, Origin của file, ADR) thì trích, không suy đoán.
3. Lý do tồn tại
Nó giải bài toán gì; không có nó thì sao — điều gì khó hơn/vỡ/phải làm tay. Phải trả lời được câu "bỏ cái này đi, ai đau đầu tiên".
4. Cơ chế hoạt động (+ sơ đồ hệ thống & sơ đồ code)
Nó CHẠY thế nào, ở hai cấp:
- Cấp HỆ THỐNG — thành phần lớn, ai gọi ai, dữ liệu đi đâu, ranh giới process/service/OS. Sơ đồ: hộp + mũi tên luồng.
- Cấp CODE — đường thực thi cụ thể: hàm nào gọi hàm nào, state đổi ở đâu, nhánh nào chạy với đầu vào đã thử. Sơ đồ: call flow / sequence.
Bước BẮT BUỘC chứng bằng runtime thật — neo vào quan sát cụ thể (dòng Z, state W), không mô tả chung chung như tài liệu.
5. Trade-off
Để có được cái này, đã đánh đổi gì — chọn nhánh này thì mất nhánh khác ra sao (hiệu năng đổi lấy đơn giản, linh hoạt đổi lấy an toàn kiểu…). Biết có phương án khác từng bị cân nhắc/bỏ qua thì nói rõ vì sao bỏ.
6. Giới hạn
Nó KHÔNG làm được gì, hoặc làm tệ ở đâu — trần quy mô, ca biên nó không phủ, điều kiện nó gãy. Khác Trade-off: Trade-off là "đánh đổi có chủ đích lúc thiết kế", Giới hạn là "biên nó dừng lại, dù muốn hay không".
7. Vị trí trong toàn bộ hệ thống (+ sơ đồ tóm tắt luồng)
Nó nối vào đâu trong bức tranh lớn — ai gọi nó (upstream), nó gọi/ảnh hưởng gì (downstream), nó đứng lớp nào. Chốt bằng MỘT sơ đồ tóm tắt luồng đầu-cuối: input → các chặng → output.
Reference — Độ sâu theo người nghe (bảy phần luôn đủ — chỉ đổi độ sâu)
| Người nghe | Bước 4 Cơ chế | Bước 5–6 nói bằng | Sơ đồ | Code / thuật ngữ | Độ dài |
|---|
| Engineer, đồng nghiệp, cao học | đủ hai cấp; trích dòng + state quan sát được | hiệu năng, bảo trì, ca biên | flowchart + sequence | trích code thật; thuật ngữ đúng | sâu, nhưng không lan man |
| Manager, Director, PM | chỉ cấp hệ thống; bằng chứng runtime nói thành một câu ("đã chạy thử: X → Y") | chi phí, rủi ro, thời gian, công sức đội | MỘT sơ đồ hộp-mũi tên | KHÔNG code block, KHÔNG backtick — tên file viết chữ thường | ngắn — đọc xong trong khoảng 2 phút (≈ 500 từ tiếng Anh ≈ 700 tiếng Việt phần chữ, không tính sơ đồ), chốt bằng đề xuất |
| Designer | luồng người dùng nhìn thấy | trải nghiệm, accessibility | luồng màn hình | không code; thuật ngữ UI thì được | vừa |
| Sinh viên, học sinh | từng bước nhân quả; cấp code rút gọn | "chọn A thì mất B" bằng ví dụ | một sơ đồ đơn giản | thuật ngữ nào dùng thì định nghĩa ngay lần đầu | vừa |
| Trẻ em, bố mẹ, bạn đời, bạn bè | kể như một câu chuyện có phép so sánh | "được gì, mất gì" đời thường | tuỳ chọn, rất đơn giản | KHÔNG thuật ngữ, không log thô; buộc phải dùng thì giải nghĩa liền | ngắn; trẻ em càng ngắn |
Hiệu chỉnh ngôn ngữ
- Người nghe đơn giản (trẻ em, không kỹ thuật, gia đình): không jargon — bằng không; một ý mỗi câu; cụ thể hơn trừu tượng ("máy chủ giống người bồi bàn" hơn "máy chủ xử lý giao tiếp client-server"); nói "bạn/con" cho gần.
- Người nghe kỹ thuật (engineer, cao học): dùng đúng thuật ngữ; dồn chữ vào phần đáng chú ý — trade-off, ca biên, quyết định thiết kế; so với thứ họ đã biết; gọn, tôn trọng cái họ đã biết.
- Người nghe kinh doanh (manager, director, PM): dẫn bằng tác động và kết quả; định lượng khi được; bỏ chi tiết cài đặt trừ khi được hỏi; đóng khung thành quyết định ("nghĩa là ta nên…").
Reference — Ví dụ — cùng một thứ, ba người nghe (chỉ mở đầu + So what)
Thứ cần giải thích: database index.
- Trẻ 5 tuổi — TL;DR: "Index là trang mục lục của cuốn sách to đùng, giúp máy tính tìm đúng trang thật nhanh, khỏi lật từng trang." · So what: "Nhờ có mục lục, trò chơi của con mở ra nhanh hơn đó!"
- Manager — TL;DR: "Index là cấu trúc giúp tra dữ liệu nhanh, giống mục lục sách; đổi lại mỗi lần ghi dữ liệu chậm đi một chút và tốn thêm dung lượng." · So what: "Trang báo cáo đang chậm vì thiếu index ở bảng đơn hàng; thêm index mất khoảng nửa ngày công, rủi ro thấp — đề xuất làm trong sprint này."
- Engineer — TL;DR: "B-tree index biến tra cứu O(n) quét cả bảng thành O(log n), giống hash map có thứ tự nhưng đổi lại mỗi INSERT/UPDATE phải cập nhật cây." · So what: "Kiểm truy vấn chậm: thấy trên cột lọc thì cân nhắc index, nhưng đo write amplification trước khi thêm."
Reference — Sơ đồ — hai đường
- Mặc định: mermaid inline — khối (flowchart cho cấu trúc, sequenceDiagram cho luồng theo thời gian). Nhanh, đọc-được-dạng-text.
- Opt-in: HTML explainer — user muốn GIỮ / chia sẻ / cần hình đẹp thật → render một trang theo (glass, toggle sáng/tối, in full-path, thang chữ compact 13″); sơ đồ gọi . Đứng trên nền , KHÔNG đẻ theme mới. Hỏi user trước khi ra file, đừng ép.
Reference — Eval — sửa skill thì phải đo lại (nếu repo có harness/scripts/wikieval.py
Học theo eli5: mỗi ca = một prompt + 4–5 khẳng định kiểm được, chạy bản skill cũ và mới trên CÙNG prompt rồi so tỉ lệ đạt.
- Goldens:
fdk/wiki/sources/evals/teach-me-*.md
- Chạy A/B: mỗi phiên bản skill do một agent độc lập trả lời từng prompt → gom thành
harness/evals/teach-me-ab-<ddmmyy>-<old|new>.json
python3 harness/scripts/wikieval.py --outputs <file>
Origin
- Distill từ yêu cầu user 2026-07-16 (teach-me: 2 cấp + bộ ba + tóm tắt, mỗi phần sơ đồ; skill biết dùng breakpoint/debugger). Grounded-runtime mượn triết lý built-in .
- Cập nhật 2026-08-01 (feedback Rhein qua ): đổi khung "bốn phần" sang khung bảy bước cố định — Tên gọi → Nguồn gốc → Lý do tồn tại → Cơ chế hoạt động → Trade-off → Giới hạn → Vị trí trong hệ thống. Nội dung runtime-driven + hai sơ đồ dồn vào bước 4; sơ đồ tóm tắt luồng dồn vào bước 7.
- Cập nhật 2026-09-11 (HÒA TAN từ dreambigou/eli5 @ , MIT): thêm bước xác định Người nghe (bảng 12 nhóm tuổi/học vấn/vai trò/quan hệ, gộp từ bốn bảng của eli5), khung mở-đóng TL;DR + phép so sánh → … → So what (từ "what → analogy → details → so what"), bảng độ sâu bảy phần theo người nghe, hiệu chỉnh ngôn ngữ ba nhóm, ví dụ cùng-một-thứ-ba-người-nghe, luật "không giọng bề trên / đơn giản hoá không nói sai / không backtick cho người không kỹ thuật", và vòng eval A/B (eli5 → tái dùng + goldens thay vì chép runner). Khác eli5: mặc định người nghe là engineer (không phải trẻ 5 tuổi), bảy bước giữ nguyên, bằng chứng runtime vẫn bắt buộc với mọi người nghe.
- A/B lần đầu (3 ca, mỗi bản do agent độc lập trả lời, outputs ở
harness/evals/teach-me-ab-110926-{old,new}.json
- Absorb qua → , task .
- Commit: (verify-before-commit điền)