← teach · 技能图谱

GLOSSARY-FORMAT

GLOSSARY.md 的格式规范

GLOSSARY.md is the canonical language for this teaching workspace. All explainers, exercises, and learning records should adhere to its terminology. Building it is itself part of learning: compressing a concept into a tight definition is evidence the user understands it.

GLOSSARY.md 是本教学工作区的规范用语。所有讲解、练习和学习记录都应遵循其中的术语。构建术语表本身就是学习的一部分：将一个概念压缩成一个简洁的定义，就是用户理解它的证据。

Rules

规则

  • Add a term only when the user understands it. The glossary is a record of compressed knowledge, not a dictionary the user reads to learn. If the user has just been introduced to a concept, wait until they can use it correctly before promoting it here.
  • Be opinionated. When several words exist for the same concept, pick the best one and list the rest as aliases to avoid. This is how language compresses.
  • Keep definitions tight. One or two sentences. Define what the term IS, not what it does or how to do it.
  • Use the glossary's own terms inside definitions. Once a term is in the glossary, prefer it everywhere — including inside other definitions. This is what makes complex terms easier to grasp later.
  • Group under subheadings when natural clusters emerge (e.g. ## Anatomy, ## Programming). A flat list is fine when terms cohere.
  • Flag ambiguities explicitly. If a term is used loosely in the wider field, note the resolution: "In this workspace, 'set' always means a working set — warm-ups are tracked separately."
  • Revise as understanding deepens. A definition the user wrote in week one may be wrong by week six. Update in place; do not leave stale entries.
  • 只在用户理解了一个术语时才添加。术语表是压缩知识的记录，而非用户用来学习的词典。如果用户刚接触一个概念，等到他们能正确使用后再将其收录到这里。
  • 要有主见。当同一个概念有多个词汇时，选最好的那个，其余列为应避免的别名。这就是语言压缩的方式。
  • 定义要简洁。一到两句话。定义术语是什么，而非它做什么或怎么做。
  • 在定义中使用术语表自身的术语。一旦一个术语进入术语表，就在所有地方优先使用它——包括在其他定义内部。这就是让复杂术语在日后更容易理解的原因。
  • 当出现自然聚类时按子标题分组（例如 ## Anatomy、## Programming）。当术语内聚时，平铺列表也可以。
  • 明确标记歧义。如果一个术语在更广泛的领域中使用得比较松散，注明本工作区的界定："在本工作区中，'set' 始终指正式组——热身组单独记录。"
  • 随着理解深入而修订。用户第一周写的定义到第六周可能就错了。就地更新；不要留下过时的条目。