A standards document only works if something reads it. Write your conventions once as a ruleset, attach them to your projects, and every AI assistant receives them on every task — with a view of exactly which rules were in effect.
Most teams already have the standards written down. The problem is delivery. A document an assistant was shown once, forty messages ago, is not a standard — it is a hope. And when a convention is missed, nobody can reconstruct what the agent was actually told.
The same conventions pasted into six repositories. One gets updated. Five do not, and nobody notices until review.
Each person prompts their assistant their own way, so the same codebase gets built to slightly different conventions.
When something ships wrong, there is no record of which instructions reached the agent, so you cannot tell whether the rule failed or was never delivered.
Not per repository. Attach the same ruleset to as many projects as you like, edit it in one place, and every project picks up the change.
A requirement stops the agent when it cannot comply. A preference lets it work around a genuine exception. Reach for preference more often than feels natural.
Put "never commit credentials" in the workspace baseline, where no project can opt out. Keep house style in ordinary rulesets, where a project reasonably can.
A consult rule links to your design system rather than inlining it. The pointer costs almost nothing and the document loads only when the work calls for it.
Mark a rule as checked only when a real lint rule, CI check, test or gate backs it. Everything else is guidance, and should read that way.
| A file in the repo | A ruleset | |
|---|---|---|
| Scope | One repository | Every project you attach it to |
| Updating | Edit each copy | Edit once, applies everywhere |
| Strength | All instructions read the same | Must, must not, prefer, consult |
| Prohibitions | Can be edited away locally | Baseline prohibitions cannot be overridden |
| History | Whatever git shows | Versioned, with who changed what |
| Visibility | Read the file and hope | See which rules were in effect, and why not |
Already using a repository file? See how the two compare.
Usually because the standards live somewhere the assistant never looks — a wiki page, an onboarding doc, or a long file handed over once at the start of a session. The fix is not a longer document; it is a short, structured set of rules delivered with every request.
No — and making them all hard is the most common mistake. If you can imagine a legitimate exception, it belongs as a preference. A workspace full of hard rules that keep stopping the agent trains people to ignore all of them.
Repository files work until you have more than one repository or more than one person. Then you get drift: copies edited separately, no history, and no way to make one standard non-negotiable everywhere.
Advisory means the agent is told. Enforced means a lint rule, CI check, test or workflow gate actually blocks the behaviour. Both are useful — but calling something enforced when nothing enforces it is worse than saying nothing.