1 min lesson
Project Rules vs AGENTS.md - when to use which
Answer "Which is the better design for a convention like 'all HTTP handlers must validate input with our schema lib'?" Then point to the lesson detail behind your choice.
Step 1 of 2
Project Rules vs AGENTS.md - when to use which
The one-page test for AGENTS.md is whether you'd hand it to a new engineer on day one - "you're in a payments monorepo, services live in /services, we use X for Y". The moment a convention only applies to some files (error handling, logging, test structure, naming) it's a Project Rule instead.
"Take 'every HTTP handler validates input with our schema lib.' Not AGENTS.md - it isn't true of the whole repo, and a rule that fires on every prompt is one people learn to talk over. Not a command either, because nobody should have to invoke it; it should just be true. So it's a Project Rule scoped to **/handlers/*.ts. It attaches when someone opens a handler and stays invisible everywhere else. Proximity picked the layer for me."
Worth saying in an interview: rules don't replace judgment, they encode defaults. The model still needs a good prompt. It now starts from your team's baseline instead of the internet's average, so fifty drifting styles collapse into one house style.