Back to Details

principle-encode-lessons-in-structure

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Encode Lessons in Structure

将经验固化到结构中

Encode recurring fixes in mechanisms (tools, code, metadata, automation) instead of textual instructions. Every error, human correction, and unexpected outcome is a learning signal. Capture it, route it, and close the loop.
Why: Textual instructions are easy to miss. They require the reader to notice, remember, and comply. Structural mechanisms (lint rules, metadata flags, runtime checks, automation scripts) enforce the rule without cooperation.
Pattern: When you catch yourself writing the same instruction a second time:
  1. Ask: can this be a lint rule, a metadata flag, a runtime check, or a script?
  2. If yes, encode it. Delete the instruction
  3. If no (requires judgment), make the instruction more prominent and add an example of the failure mode
Pick the strongest mechanism. When more than one mechanism would work, choose the strongest the situation allows (an unrepresentable state that cannot compile, then a lint or banned API that fails CI, then a canonical helper, then a runtime check), because agents copy whatever the surrounding code already does and a weaker guard becomes the next template.
Corollary: If the fix is structural, only use the structural fix. The instruction is the symptom.
Feedback loop:
  • Capture every correction. When the human intervenes or tests fail, decide if it's a one-off or a pattern.
  • Route to the right layer. One-off -> brain note. Recurring fix -> skill or lint rule. Systemic issue -> principle.
  • Close the loop. Don't just record. Apply now or create a concrete todo.
Anti-patterns:
  • Acknowledging without recording ("I'll keep that in mind" does not persist)
  • Recording without routing (a brain note about a lint rule that should exist is wasted unless the lint rule gets implemented)
  • Fixing without generalizing (fixing one instance while leaving the recurring pattern intact)
通过机制（工具、代码、metadata、automation）而非文字指令来编码重复性修复。每一次错误、人工纠正和意外结果都是学习信号。捕获它、分流它，并完成闭环。
原因： 文字指令很容易被忽略。它们要求读者注意、记住并遵守。结构化机制（lint rule、metadata flag、runtime check、automation script）无需对方配合就能强制执行规则。
模式： 当你发现自己第二次写下同一条指令时：
  1. 问：这能否成为 lint rule、metadata flag、runtime check 或 script？
  2. 如果可以，就将其编码。删除该指令
  3. 如果不可以（需要判断），则让指令更加醒目，并添加一个失败模式示例
选择最强的机制。 当多种机制都可行时，在当前条件允许的情况下选择最强的一种（使非法状态无法表示、因而无法编译的机制，其次是在 CI 中失败的 lint rule 或 API 禁用规则，再其次是统一的 helper，最后是 runtime check），因为 Agent 会复制周围代码已有的做法，较弱的防护会成为下一个被复制的模板。
推论： 如果修复是结构化的，就只使用结构化修复。指令只是症状。
反馈循环：
  • 捕获每一次纠正。 当人工介入或测试失败时，判断它是一次性事件还是重复模式。
  • 分流到正确的层级。 一次性事件 -> brain note。重复性修复 -> skill 或 lint rule。系统性问题 -> 原则。
  • 完成闭环。 不要只是记录。现在应用，或者创建一个具体的 todo。
反模式：
  • 只表示接受却不记录（“我会记住”无法持久化）
  • 记录但不分流（对于本应存在的 lint rule，只写一条 brain note 毫无意义，除非真正实现该 lint rule）
  • 修复但未泛化（只修复单个实例，却让重复出现的模式原样保留）