teach-me

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: teach-me

WHAT

WHAT（是什么）

Purpose và context

目的与上下文（Purpose & 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à
```
/onboard-codebase
```
→ wiki, hoặc
```
/join-project
```
→ orient nhanh read-only). teach-me hẹp và sâu, không ghi wiki.

目的（Purpose）： 按固定的七步框架解释单个事物，针对听众调整表达，并通过真实 runtime 证明“工作机制”，然后清理 instrument。
触发条件（Trigger, when to use）：
- User 想深入理解某个具体事物：一个文件、一个函数、一个功能、一个子系统、一个概念、一条错误消息——“这个是怎么运行的”“给我解释一下”。
- User 想把该事物解释给某个特定听众——“ELI5”“怎么跟老板说”“解释给 designer 听”“让我父母看懂”。
非目标（Non-goals）： 不适用于：理解整个陌生 codebase（应使用
```
/onboard-codebase
```
→ wiki，或
```
/join-project
```
→ 快速、只读地熟悉项目）。teach-me 范围窄且深入，不写入 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

听众 → 范围 + 来源 → runtime 观察（输入 → 某一行的 state）→ 听众 · TL;DR + 类比 → 7 个部分 → So what（根据听众调整深度）→ 清理 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	`git diff` xác nhận

	字段	是否必填	含义
In	需要解释的事物	是	不明确 → 提出一个带提示的问题
In	听众	否	默认 engineer；“ELI5”未指定其他人 → 5 岁儿童
Out	按“输出框架”组织的答案	是	包含所有模块，且顺序正确
Out	图示	是	默认使用 inline mermaid；仅在 user 同意时使用 HTML explainer
Out	已清除 instrument 的 user 代码	有插入时必填	使用 `git diff` 确认

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
```
inline code
```
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]]
```
, đừng khẳng định bừa.
RULE-06 (MUST): Instrument tạm → DỌN SẠCH: mọi
```
print
```
/
```
breakpoint
```
/
```
debugger
```
/
```
console.log
```
chèn để quan sát phải gỡ hết;
```
git diff
```
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à
```
/onboard-codebase
```
/
```
/join-project
```
) 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
```
surface-coverage
```
(
```
surface-coverage.py scan
```
+
```
check
```
) và báo
```
N/M mục bề mặt được phủ
```
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.

RULE-01（必须）：框架完整、顺序正确、不得合并省略——听众 → TL;DR → 七个部分 → So what。缺少任何部分（即使它“显而易见”或“不适用”）时，都必须明确说明原因，不得静默跳过。
RULE-02（必须）：听众只会改变表达方式，不会改变事实——可以省略细节，也可以为非技术听众大幅简化（传递 80% 的核心含义，好过 100% 准确却让听众放弃理解），但绝不能讲错；大幅简化之处要标注“（已简化）”。为非技术听众将证据压缩成一句话时，该句话不能比实际观察结果更强（只看到一个案例，就不能说“总是如此”）；数字（修复次数、行数、文件数）必须从 git/磁盘重新统计，不得估算。
RULE-03（必须）：绝不使用居高临下的语气——给 5 岁儿童解释时必须有趣，而不是把他们当傻子；向 manager 解释时必须让其感到有决策权，而不是被当作不懂技术的人。
RULE-04（必须）：非技术听众不展示代码，包括 backtick——不使用 code block，也不对文件名/目录名使用
```
inline code
```
（eli5 评估教训：某个版本仍给 manager 使用了带 backtick 的目录名，因此不合格）。
RULE-05（必须）：以 runtime 证据为准，不靠猜测：“工作机制”部分优先 DRIVE 真实代码。只有无法运行时（缺少环境、需要生产环境）才进行静态解释，并且必须明确说明“这是静态解释，尚未通过运行验证”。如果断言依赖尚未观察到的 runtime，则记录到
```
[[150726-unknown-ledger]]
```
，不得随意断言。
RULE-06（必须）：**临时 instrument → 全部清理：**所有为了观察而插入的
```
print
```
/
```
breakpoint
```
/
```
debugger
```
/
```
console.log
```
都必须移除；结束前使用
```
git diff
```
确认。
RULE-07（必须）：**范围仅限一个事物：**teach-me 不分析整个项目（应使用
```
/onboard-codebase
```
/
```
/join-project
```
），也不写入 wiki。
RULE-08（必须）：不另造 debugger——使用现有工具（pdb/debugpy · node --inspect · print/log · /run · /verify）。
RULE-09（必须）：Trade-off 与限制不得混淆——Trade-off 是设计时有意作出的取舍；限制是即使愿意也无法逾越的边界，通常会在实际使用时暴露。
RULE-10（必须）：多主题系列按覆盖面计数，不按文章数量计数——当 teach-me 被反复调用来为整个 app 构建课程（或 user 询问“是否已经足够”）时，不得报告“N 篇”并暗示已经全部覆盖：应运行
```
surface-coverage
```
skill（
```
surface-coverage.py scan
```
+
```
check
```
），然后报告
```
N/M 个表面区域已覆盖
```
及尚未有文章覆盖的列表（GH#191）。
能力（Capabilities）：读取代码/文档；使用现有 debugger/log 在本地运行代码；临时插入 instrument（结束前移除）；不写入 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
```
/onboard-codebase
```
/
```
/join-project
```
.
Còn instrument trong
```
git diff
```
→ chưa xong.

无法运行（缺少环境、需要生产环境）→ 进行静态解释，明确说明尚未通过运行验证；对未观察到的情况作出断言 → 记录到 unknown-ledger。
范围不明确 → clarify 一个问题。
要求理解整个项目 → cancelled，转交
```
/onboard-codebase
```
/
```
/join-project
```
。
```
git diff
```
中仍有 instrument → 尚未完成。

HOW

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, `git diff`	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
```
print
```
/
```
breakpoint
```
/
```
debugger
```
tạm đã chèn;
```
git diff
```
xác nhận code người dùng sạch như trước. → Xong khi diff không còn instrument tạm.

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	判断	user 问题	确定听众	一个群体 + 他们关心的事项	未说明 → engineer
W02	判断	需要解释的事物	确定范围 + 阅读正确类型的来源	理解目的	不明确 → 提问
W03	执行	代码/小型案例	使用具体输入和临时 instrument DRIVE runtime	至少一个 runtime 观察结果	无法运行 → B01
W04	判断	观察结果 + 听众	按输出框架生成内容，深度依据表格调整	包含所有模块	—
W05	确定性操作	已插入的代码	移除 instrument，执行 `git diff`	diff 干净	仍有残留 → 继续移除

以下步骤是 W01–W05 的真实来源：

确定听众——阅读 user 的问题，并归入下方“听众”表中的一个群体。如果未说明，默认提问者本人 = engineer（teach-me 是面向开发者的 skill）；单独的“ELI5”或“像给 5 岁孩子解释”且未指定其他人 → 5 岁儿童。→ 确定一个群体及其关心事项后完成。
确定范围 + 阅读来源——user 应明确指定要解释的事物；如果不明确 → 结合上下文提出一个带提示的问题。阅读正确类型的来源：代码 → 阅读代码，先理解目的再看语法；概念 → 拆解核心组成部分；错误消息 → 查找根本原因，而不是翻译表面文字；文档 → 提取对听众真正重要的内容。
DRIVE runtime（如果可以运行）——使用一个具体输入运行，加入临时 instrument/breakpoint，观察真实 state。如果 instrument 被插入 user 代码，应在副本上操作，或在第 5 步移除。→ 至少获得一个具体 runtime 观察结果（输入 → 某一行的 state）后完成。无法运行 → 按 Rules 标注“静态解释”。
按“输出框架”生成内容——听众 → TL;DR + 类比 → 按正确顺序呈现七个部分 → So what；每一部分的深度依据“根据听众调整深度”表。→ 所有模块均已包含，没有任何部分留空或并入其他部分后完成。
清理 instrument——移除所有临时插入的
```
print
```
/
```
breakpoint
```
/
```
debugger
```
；使用
```
git diff
```
确认 user 代码与操作前一致。→ diff 中不再存在临时 instrument 后完成。

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 `/docs-site-macos` , sơ đồ gọi `/diagram`	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

ID	类型	条件	行为	跳过/失败	汇合点
B01	恢复	无法运行代码（缺少环境、需要生产环境）	进行静态解释，并明确说明“这是静态解释，尚未通过运行验证”	对未观察到的情况作出断言 → unknown-ledger	W04
B02	用户可选	user 希望保留、分享或需要美观效果	按 `/docs-site-macos` 生成 HTML explainer，图示调用 `/diagram`	未同意 → inline mermaid	W05
B03	条件必需	听众为非技术人士	不使用 code block 或 backtick；将证据压缩为一句话	—	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,

git diff

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

可以自动验证：模块完整且顺序正确、非技术听众版本不含 code/backtick、

git diff

中没有 instrument。需要人工判断：类比是否符合听众背景、语气是否居高临下。修改 skill 时，应使用 eval A/B 重新测量（参见“参考——Eval”）。

Examples

示例

Positive: "giải thích
```
wiki-sync.py --check
```
cho tôi" → engineer; chạy với repo thật,
```
print
```
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ỡ
```
print
```
,
```
git diff
```
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.

正向示例：“给我解释
```
wiki-sync.py --check
```
”→ engineer；使用真实 repo 运行，通过
```
print
```
输出 exit code + 文件列表 ⇐ → 观察到“exit 3，2 页被标记为 drift”→ 输出包含 TL;DR + 七个部分 + flowchart + sequence；移除
```
print
```
后，
```
git diff
```
干净。
边界/失败示例：“跟老板解释为什么报告页面这么慢”，但只有生产环境日志，无法在本地运行 → 使用明确标注的静态解释，不含 code block/backtick，约 700 词，以建议收尾；只观察到一个案例时，不得声称“总是如此”。

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:
```
python3 -m pdb <file>
```
, hoặc
```
breakpoint()
```
tạm, hoặc
```
debugpy
```
. Rẻ hơn: chèn
```
print(...)
```
/
```
logging
```
ở điểm quan tâm rồi chạy.

Node/JS:

node --inspect

console.trace()

debugger;

tạm, hoặc

console.log

ở đ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
```
git init
```
hai nhánh sửa cùng dòng → merge → thấy conflict thật).
Bất kỳ: built-in
```
/run
```
(chạy app thật) và
```
/verify
```
(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.

“它是怎么运行的”必须通过真实 runtime证明，不能只根据静态阅读进行推测。Claude Code 环境中的工具：

Python：
```
python3 -m pdb <file>
```
，或临时使用
```
breakpoint()
```
，或使用
```
debugpy
```
。成本更低的方式：在关注点插入
```
print(...)
```
/
```
logging
```
后运行。

Node/JS：

node --inspect

、

console.trace()

、临时

debugger;

，或在关注点使用

console.log

。

**概念/工具（git、HTTP、SQL 等）：**在临时目录中构建最小案例并真实运行（例如
```
git init
```
，创建两个分支并修改同一行 → merge → 观察真实 conflict）。
任意内容：使用内置
/run
（运行真实 app）和
/verify
（drive flow、观察行为）。使用具体输入运行，并观察具体行上的真实 state。

“这个函数肯定会返回 X”只是猜测。“我使用输入 Y 运行，在第 Z 行设置 breakpoint，观察到 state 为 W”才是数据。始终优先采用数据——无论面向什么听众。听众只会改变证据的呈现方式，不会改变必须提供证据这一要求。

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

群体	他们关心什么	采用何种类比	语气
Engineer（默认）	运行方式、架构、Trade-off、维护性	已知事物：“类似 hash map，但……”、熟悉的 pattern	精确、简洁，正确使用术语（省略他们熟悉的术语会被视为轻视）
其他领域的同事	对自己工作的影响、需要了解什么才能协作	共同工作、团队流程	务实，“这东西会如何影响你”
Manager	影响、风险、时间、成本、团队能力	业务结果、人员、预算	以影响为主，在有依据时量化，最后给出需要作出的决策
Director	战略、ROI、竞争优势	宏观视角、资源分配	全局、简短
Product Manager	用户价值、优先级、范围	user story、做什么/不做什么	按功能和用户展开
Designer	体验、交互流程、accessibility	屏幕、用户可见的操作	按用户看到和点击的内容展开
学生/研究生	理论 + 应用；研究生还需理解细微差别、边界情况和深远影响	课程基础知识	学术性；术语首次出现时附简短语境
初二–初三学生（≈12–17 岁）	清晰的因果关系、每一步	手机、社交网络、游戏、学校	略亲切，不“假装孩子气”
≈10 岁儿童/五年级学生	基本因果关系	学校、运动、小组作业、电子游戏	像一位受欢迎的教师
5 岁儿童（“ELI5”）	一个容易记住的要点	玩具、动物、糖果、游乐场、图画书	有趣、热情，句子很短
父母/年长者	理解内容，同时不感到被轻视	正在使用的技术、家务	尊重、清晰、耐心
配偶/伴侣、朋友	容易跟随的叙事	日常生活、共同经历、大众文化	温暖、对话式，也可以幽默

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ì".

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

七个部分构成一个连贯的故事：它叫什么 → 从何而来 → 为什么必须存在 → 如何运行 → 为此付出了什么取舍 → 它做不到什么 → 它在整体图景中处于什么位置。TL;DR + 类比负责开门（让听众立即知道在讨论什么）；So what 负责关门（让听众知道接下来该做什么）。目的始终先于机制——在知道事物为何存在之前，没有人会关心语法。

七个标题对所有听众保持不变（方便 user 检查框架）；对非技术听众，可以添加日常化副标题，例如“5. Trade-off——得到什么、失去什么”。

1. Tên gọi

1. 名称

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

2. 来源

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.

它从何而来——哪个 commit/PR/决策引入了它，借鉴了哪个想法（已有库/paper/pattern，还是原创），以及最初是什么情况产生了这一需求。如果存在真实证据（git log、文件 Origin、ADR），则引用，不得猜测。

3. Lý do tồn tại

3. 存在原因

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)

4. 工作机制（+ 系统图与代码图）

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.

它是如何运行的，分成两个层级：

系统层级——大型组件、谁调用谁、数据流向何处、process/service/OS 边界。图示：方框 + 箭头表示流向。
代码层级——具体执行路径：哪个函数调用哪个函数、state 在哪里变化、使用已测试输入时会执行哪个分支。图示：call flow / sequence。

该步骤必须通过真实 runtime 证明——锚定具体观察结果（第 Z 行、state W），不能像文档一样泛泛描述。

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

6. 限制

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

它做不到什么，或者在哪里表现不佳——规模上限、未覆盖的边界情况、失效条件。与 Trade-off 不同：Trade-off 是“设计时有意作出的取舍”，限制则是“它停下的边界，即使愿意也无法越过”。

7. Vị trí trong toàn bộ hệ thống (+ sơ đồ tóm tắt luồng)

7. 在整个系统中的位置（+ 流程摘要图）

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.

它如何连接进整体图景——谁调用它（upstream）、它调用或影响什么（downstream）、它位于哪一层。最后用一个端到端流程摘要图收尾：input → 各阶段 → 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

听众	第 4 步工作机制	第 5–6 步的表达方式	图示	Code/术语	长度
Engineer、其他领域的同事、研究生	包含两个层级；引用行号 + 可观察的 state	性能、维护性、边界情况	flowchart + sequence	引用真实代码；正确使用术语	深入但不漫无边际
Manager、Director、PM	仅系统层级；runtime 证据压缩成一句话（“已试运行：X → Y”）	成本、风险、时间、团队投入	一个方框箭头图	不使用 code block，不使用 backtick——文件名使用普通文本	简短——约 2 分钟读完（≈500 个英文词 ≈700 个越南语词，不含图示），最后给出建议
Designer	用户可见的流程	体验、accessibility	屏幕流程	不展示代码；可以使用 UI 术语	适中
学生、中学生	逐步说明因果关系；简化代码层级	用例子表达“选择 A 就会失去 B”	一个简单图示	首次使用任何术语时立即定义	适中
儿童、父母、伴侣、朋友	像讲故事一样，并使用类比	用日常语言表达“得到什么、失去什么”	可选，必须非常简单	不使用术语和原始日志；如必须使用，应立即解释	简短；儿童应更短

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…").

简单听众（儿童、非技术人士、家庭成员）：完全不使用行话——一句只表达一个意思；使用具体概念而不是抽象概念（“服务器像负责端盘子的服务员”，好过“服务器处理 client-server 通信”）；用“你/咱们”等亲近表达。
技术听众（engineer、研究生）：正确使用术语；把文字集中在值得关注的内容上——Trade-off、边界情况、设计决策；与听众已知事物比较；简洁表达，并尊重他们已经掌握的知识。
商业听众（manager、director、PM）：以影响和结果为主；在有依据时量化；除非用户主动询问，否则省略实现细节；最终以决策形式收尾（“这意味着我们应该……”）。

Reference — Ví dụ — cùng một thứ, ba người nghe (chỉ mở đầu + So what)

参考——示例——同一事物，三类听众（仅展示开头 + 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
```
EXPLAIN
```
truy vấn chậm: thấy
```
Seq Scan
```
trên cột lọc thì cân nhắc index, nhưng đo write amplification trước khi thêm."

需要解释的事物：database index。

5 岁儿童——TL;DR：“Index 就是巨型书里的目录，能帮助计算机快速找到正确的书页，不用一页页翻。”· So what：“有了目录，你的游戏就能更快打开啦！”
Manager——TL;DR：“Index 是一种帮助快速查找数据的结构，就像书的目录；代价是每次写入会稍微变慢，并占用更多空间。”· So what：“报告页面变慢，是因为订单表缺少 index；添加 index 大约需要半天工程投入，风险较低——建议在本 sprint 内完成。”
Engineer——TL;DR：“B-tree index 将 O(n) 的全表扫描查找变成 O(log n)，类似有序的 hash map，但代价是每次 INSERT/UPDATE 都必须更新树。”· So what：“用
```
EXPLAIN
```
检查慢查询：如果在过滤列上看到
```
Seq Scan
```
，可以考虑 index，但应先衡量 write amplification。”

Reference — Sơ đồ — hai đường

参考——图示——两条路径

Mặc định: mermaid inline — khối
```
mermaid
```
(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
```
/docs-site-macos
```
(glass, toggle sáng/tối, in full-path, thang chữ compact 13″); sơ đồ gọi
```
/diagram
```
. Đứng trên nền
```
[[design-foundation]]
```
, KHÔNG đẻ theme mới. Hỏi user trước khi ra file, đừng ép.

默认：inline mermaid——使用
```
mermaid
```
区块（结构使用 flowchart，时序使用 sequenceDiagram）。快速、便于以文本阅读。
Opt-in：HTML explainer——如果 user 希望保留、分享或需要真正美观的页面 → 按
```
/docs-site-macos
```
渲染页面（glass 效果、明暗切换、打印时显示完整路径、适合 13 英寸屏幕的紧凑字号）；图示调用
```
/diagram
```
。基于
```
[[design-foundation]]
```
，不要另造主题。输出文件前先询问 user，不要强制执行。

Reference — Eval — sửa skill thì phải đo lại (nếu repo có

harness/scripts/wikieval.py

)

参考——Eval——修改 skill 后必须重新测量（如果 repo 中存在

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
```
— ba ca phủ ba kiểu người nghe (engineer · manager · trẻ 5 tuổi); assert tất định (thứ tự bảy phần, không code cho manager, có phép so sánh cho trẻ em…) +
```
rubric
```
cho giám khảo.
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
```
(map golden-id → câu trả lời) →
```
python3 harness/scripts/wikieval.py --outputs <file>
```
. Bản mới không được có tỉ lệ đạt thấp hơn bản cũ.

借鉴 eli5：每个案例 = 一个 prompt + 4–5 个可检查断言，在相同 prompt 上分别运行旧版和新版 skill，然后比较通过率。

Goldens：
```
fdk/wiki/sources/evals/teach-me-*.md
```
——三个案例覆盖三类听众（engineer · manager · 5 岁儿童）；确定性断言（七个部分的顺序、manager 版本不含代码、儿童版本包含类比……）+ 供评审使用的
```
rubric
```
。
运行 A/B：每个 skill 版本由一个独立 agent 回答每个 prompt → 汇总为
```
harness/evals/teach-me-ab-<ddmmyy>-<old|new>.json
```
（映射 golden-id → 回答）→
```
python3 harness/scripts/wikieval.py --outputs <file>
```
。新版本的通过率不得低于旧版本。

Origin

起源（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
```
/verify
```
.
Cập nhật 2026-08-01 (feedback Rhein qua
/fdk
): đổ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 @
a766623
, 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
```
run-evals.py --a/--b
```
→ tái dùng
```
wikieval.py
```
+ 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
```
  ): khẳng định tất định cũ 8/13 → mới 13/13; giám khảo mù 4 tiêu chí cũ 6/12 → mới 9/12. Ca manager bản mới vẫn trượt vì dài (~718 tiếng) và một câu bằng chứng nói quá điều đã quan sát → thêm ngưỡng độ dài tính theo tiếng Việt + luật nén bằng chứng (chưa đo lại sau hai luật này).

Absorb qua

/propose

→

160726-teach-me-skill

, task

T-260716-01

Commit: (verify-before-commit điền)

提炼自 user 于 2026-07-16 提出的需求（teach-me：两个层级 + 三件套 + 摘要，每个部分配图；skill 知道使用 breakpoint/debugger）。Grounded-runtime 借鉴了内置
```
/verify
```
的理念。
更新于 2026-08-01（通过
/fdk
收到 Rhein 的反馈）：将“四部分”框架改为固定的七步——名称 → 来源 → 存在原因 → 工作机制 → Trade-off → 限制 → 在系统中的位置。runtime 驱动内容 + 两张图合并到第 4 步；流程摘要图移至第 7 步。
更新于 2026-09-11（融合 dreambigou/eli5 @
a766623
，MIT）：新增听众识别步骤（一张覆盖 12 个年龄、学历、角色和关系群体的表，合并自 eli5 的四张表）、“TL;DR + 类比 → … → So what”的开闭框架、根据听众调整七部分深度的表、三组语言校准、同一事物面对三类听众的示例、“不居高临下/简化但不错误/非技术听众不使用 backtick”规则，以及 A/B eval 循环（eli5
```
run-evals.py --a/--b
```
→ 复用
```
wikieval.py
```
+ goldens，而非复制 runner）。与 eli5 不同：默认听众是 engineer（不是 5 岁儿童），七步保持不变，所有听众都必须提供 runtime 证据。
- 首次 A/B（3 个案例，每个版本由独立 agent 回答，输出位于
```
harness/evals/teach-me-ab-110926-{old,new}.json
```
  ）：确定性断言从旧版 8/13 提升至新版 13/13；盲评四项标准从旧版 6/12 提升至新版 9/12。新版 manager 案例仍失败，因为内容过长（约 718 词），且一句证据的表述超过了实际观察结果；因此新增按越南语计算的长度阈值和证据压缩规则（新增这两条规则后尚未重新测量）。

通过

/propose

吸收 →

160726-teach-me-skill

，task

T-260716-01

。

Commit：（verify-before-commit 时填写）

teach-me

Original

Translation

Skill: teach-me

Skill: teach-me

WHAT

WHAT（是什么）

Purpose và context

目的与上下文（Purpose & context）

Mental model

心智模型

Input và output contract

输入与输出约定

Rules và capabilities

规则与能力

Failure boundaries

失败边界

HOW

HOW（如何）

Main workflow

主工作流

Branches

分支

Validation và stopping

验证与停止条件

Examples

示例

Reference — Bạn ĐƯỢC DÙNG công cụ để CHỨNG, không chỉ đọc

参考——你应当使用工具来证明，而不只是阅读

Reference — Người nghe — họ quan tâm gì, so sánh bằng gì, giọng nào

参考——听众——他们关心什么、采用什么类比、使用什么语气

Reference — Khung output (cố định — ĐÚNG THỨ TỰ, không khối nào bị bỏ)

参考——输出框架（固定——顺序正确，不跳过任何模块）

1. Tên gọi

1. 名称

2. Nguồn gốc

2. 来源

3. Lý do tồn tại

3. 存在原因

4. Cơ chế hoạt động (+ sơ đồ hệ thống & sơ đồ code)

4. 工作机制（+ 系统图与代码图）

5. Trade-off

5. Trade-off

6. Giới hạn

6. 限制

7. Vị trí trong toàn bộ hệ thống (+ sơ đồ tóm tắt luồng)

7. 在整个系统中的位置（+ 流程摘要图）

Reference — Độ sâu theo người nghe (bảy phần luôn đủ — chỉ đổi độ sâu)

参考——根据听众调整深度（七个部分始终完整——只调整深度）

Hiệu chỉnh ngôn ngữ

参考——语言校准

Reference — Ví dụ — cùng một thứ, ba người nghe (chỉ mở đầu + So what)

参考——示例——同一事物，三类听众（仅展示开头 + So what）

Reference — Sơ đồ — hai đường

参考——图示——两条路径

Reference — Eval — sửa skill thì phải đo lại (nếu repo có harness/scripts/wikieval.py)

参考——Eval——修改 skill 后必须重新测量（如果 repo 中存在 harness/scripts/wikieval.py）

Origin

起源（Origin）

Reference — Eval — sửa skill thì phải đo lại (nếu repo có
`harness/scripts/wikieval.py`
)

参考——Eval——修改 skill 后必须重新测量（如果 repo 中存在
`harness/scripts/wikieval.py`
）