Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Decisions or learned rules?

DecisionLearned rule
Comes fromSomeone saying what code must do, recorded or extractedA mistake people kept fixing in agent code, mined from history
HoldsA sentence, a reason, a scope, optional checksAn ast-grep pattern, backtested on past corrections
CoversAnything: architecture, conventions, dependencies, scopeOnly code patterns a lint rule can match
EnforcedShown before edits in scope; with checks, a breaking edit is denied before it landsRuns after edits, in shadow → warn → block mode, promoted from its hit log
Changed withingrain decisions supersedeingrain rules mode, ingrain rules promote
Per-line overrideA comment naming the decision id (how)A comment naming the rule id (how)

Use a decision when you can say the rule up front, especially when it isn’t about code shape (“don’t add Redis”, “billing goes through the payments client”). Learned rules cover the rest: the mistakes nobody wrote down until they had fixed them a few times. Both are accepted by a person, can’t be edited by agents, and are checked together by ingrain check, the pre-commit hook and CI.