principle-encode-lessons-in-structure

Encode the recurring correction as a lint rule, metadata flag, runtime check, or script instead of writing the comment again. If the rule genuinely requires human judgment, make the instruction more prominent and include an example of the failure mode.

Convert a rule to a lint check when you catch yourself writing the same instruction a second time or notice a recurring correction. Structural mechanisms enforce the rule without requiring readers to notice, remember, and comply.

The strongest enforcement is an unrepresentable state that cannot compile, followed by a lint rule or banned API that fails CI, then a canonical helper, then a runtime check. Pick the strongest rung the situation allows.

Textual instructions require the reader to notice, remember, and comply, and agents copy whatever the surrounding code already does. A weaker guard becomes the next template, so structural mechanisms are more reliable than prose.

Common anti-patterns include acknowledging a correction without recording it, recording it without routing it to implementation, and fixing one instance without generalizing the recurring pattern. Each correction should be captured, routed, and closed with action.