encode-lesson
An instruction works only when the agent reads it, remembers it, and obeys it. A mechanism works without its cooperation. Agents also copy the code around them, so a mistake that already sits in three files lands in the fourth whatever the instructions say.
Name the lesson
One sentence: the wrong thing, the right thing. Then the two occurrences that make it a lesson: the PRs, the file:line, or the correction in this session. One occurrence is a one-off, not a lesson. Say so and stop.
Find the instruction that states the rule today, if one exists: CLAUDE.md, a skill, a doc, a comment.
Pick the strongest mechanism
In this order, the first one the situation allows:
- A type or structure that makes the wrong state fail to compile.
- A lint rule or a banned API that fails the repo's gate.
- One shared helper, with every duplicate migrated to it.
- A runtime check that fails loudly and names the problem.
The order matters because a weaker guard becomes the next template. Agents copy code without the guard as readily as code with it.