← teach · 技能图谱

LEARNING-RECORD-FORMAT

学习记录的格式规范

Learning records live in ./learning-records/ and use sequential numbering: 0001-slug.md, 0002-slug.md, etc. Create the directory lazily — only when the first record is written.

学习记录存放在 ./learning-records/ 中，使用顺序编号：0001-slug.md、0002-slug.md 等。按需创建目录——仅在写入第一条记录时才创建。

They are the teaching equivalent of ADRs: they capture non-obvious lessons, key insights, and stated prior knowledge that will steer future sessions. They are used to calculate the zone of proximal development. They are titled 0001-<dash-case-name>.md, where the number increments each time.

它们是教学中 ADR 的等价物：记录不那么显而易见的经验教训、关键洞察和已声明的先验知识，这些将指导未来的会话。它们用于计算最近发展区。文件命名为 0001-<dash-case-name>.md，编号依次递增。

That is the whole format. A learning record can be a single paragraph. The value is recording that this is now known and why it changes what to teach next — not in filling out sections.

这就是完整的格式。学习记录可以只是一个段落。其价值在于记录这件事现在已被掌握，以及为什么它会改变接下来要教的内容——而不在于填写各种章节。

Optional sections

可选章节

Only include these when they add genuine value. Most records won't need them.

仅在这些章节确实能增加价值时才包含。大多数记录不需要它们。

  • Status frontmatter (active | superseded by LR-NNNN) — useful when an earlier understanding turns out to be wrong and is replaced.
  • Evidence — how the user demonstrated the understanding (a question answered, an exercise completed, prior experience cited). Useful when the claim might be revisited.
  • Implications — what this unlocks or rules out for future sessions. Worth recording when non-obvious.
  • 状态前置信息（active | superseded by LR-NNNN）——当早期理解被证明是错误并被替代时有用。
  • 证据——用户如何展示了该理解（回答了一个问题、完成了一个练习、引用了以往经验）。当该结论可能被重新审视时有用。
  • 影响——这为未来会话解锁或排除了什么。当结果不明显时值得记录。

Numbering

编号

Scan ./learning-records/ for the highest existing number and increment by one.

扫描 ./learning-records/ 找到现有的最高编号，然后加一。

When to write a learning record

何时写学习记录

Write one when any of these is true:

当以下任一情况成立时写一条：

  1. The user demonstrated genuine understanding of something non-trivial — not just exposure, but evidence they can use the concept correctly. This sets a new floor for what to teach next.
  2. The user disclosed prior knowledge — "I already know X." Record it so future sessions don't re-teach it. Also record the depth claimed.
  3. A misconception was corrected — the user previously believed something wrong and now sees why. These are high-value: they predict future stumbling blocks for related topics.
  4. The mission shifted in response to learning — the user discovered they cared about something different than they thought. Cross-link to MISSION.md and update it.
  1. 用户展示了对某个非平凡内容的真正理解——不仅仅是接触过，而是有证据表明他们能正确使用该概念。这为接下来教什么设定了新的底线。
  2. 用户透露了先验知识——"我已经知道 X。"记录下来，以免未来会话重复教授。同时记录所声称的深度。
  3. 一个误解被纠正了——用户之前相信了错误的东西，现在明白了原因。这些是高价值的：它们能预测相关主题未来的绊脚石。
  4. 使命因学习而转变——用户发现他们关心的东西与之前的想法不同。交叉链接到 MISSION.md 并更新它。

What does not qualify

什么情况不算

  • Material that was merely covered. Coverage is not learning. Wait for evidence.
  • Anything already captured tersely in GLOSSARY.md as a term definition. Don't duplicate.
  • Session-by-session activity logs. Learning records are not a journal — they are decision-grade insights.
  • 仅仅是被覆盖过的材料。覆盖不等于学习。等待证据。
  • 已在 GLOSSARY.md 中作为术语定义简洁记录的内容。不要重复。
  • 逐会话的活动日志。学习记录不是日记——它们是决策级的洞察。

Supersession

替代

When a later record contradicts an earlier one (the user's understanding deepened or corrected), mark the old record Status: superseded by LR-NNNN rather than deleting it. The history of how understanding evolved is itself useful signal.

当后来的记录与早期记录矛盾时（用户的理解深化或纠正了），将旧记录标记为 Status: superseded by LR-NNNN，而非删除。理解如何演变的历程本身就是有用的信号。