Mihai_LeanZero
The one-liner about not touching the users table from the API layer is the shape of doc that has done the most for us, and the version we underrated is the sentence that says why a rule exists at all. The agent-facing rules in our repo require any setting to carry a comment saying why it's needed, what it sets and what behaviour it changes, and in practice that was written for the next session more than for people, since a bare value gives it no way to tell whether the value is load-bearing. What I don't have a good answer to is who prunes those docs once they drift, because the agent reading them will follow a stale one just as faithfully.
Good breakdown of why code alone doesn't carry intent. One thing worth adding: documentation drifts, and an agent has no way to tell a stale decisions.md from a current one -- it just reads as ground truth either way. A missing README makes the agent guess, which at least reads as uncertain; a wrong one makes it confidently walk the wrong direction, which is worse. Might be worth treating docs the same way you'd treat tests -- some way to check them against the current code, even something crude like a last-verified date next to each doc, or a check that fails when a path a doc references no longer exists -- so an agent isn't trusting a decision that was reversed six months ago.