A repository's Cursor rules are read as Cursor reads them, an always rule in every prompt, a glob rule from the turn after a file it matches is worked on, a description-only rule listed by its description, and each says why¶
Decision 809 · accepted · 2026-10-07 · issue #123
Superseded in part
In part by 828.
- Where.
.cursor/rules/*.mdcin the repository root, and in each directory on the way to where the session works (798's directories: the workspace and the directory of every file the conversation worked on), as nestedAGENTS.mdfiles are, and as Cursor reads nested rules, which attach once files in their directory are referenced. Only the*.mdcdirectly in the directory, in name order. The legacy.cursorrulesat the root only, before them, as an always rule with no front matter. Not in<config>: Cursor keeps a person's own rules in its settings, not in files. A rule comes after its directory's instruction file and that file's imports, in that directory's scope, so it is nearer than its directory'sAGENTS.mdin the prompt's order. In the budget each rule is a scope of its own, and the nearest is kept whole first (706). - When a rule joins. By Cursor's four kinds.
alwaysApply: true(Always) puts the rule in every prompt, whatever else the front matter says.globs(Auto Attached) put it in from the turn after the session first read, edited or wrote a file one of them matches, for as long as the conversation holds that call. That is 798's focus, taken from the conversation: a restarted agent sees the same, and a compaction that folds the call away takes the rule with it, as it takes a nestedAGENTS.md. Read as a turn begins and held for the turn (798, 792), so a rule that becomes active mid-turn joins at the next turn and the system prompt in front of the cached conversation does not change within one. Not chosen: attaching the rule to the tool result that read the file, which takes effect within the turn but leaves it where the budget, the event andcontext.getcannot see it (798's reasons). - Description only (Agent Requested). Cursor shows its agent the description and the
agent fetches the rule when it judges the rule relevant. Here such a rule is listed in the
prompt by its path and description (
Rule <path> (<scope>), to read when it applies: <description>), with statuslisted, and the agent reads the file withread_filewhen the description fits; its body is not joined. The line counts against the budget, whole or not at all. Not chosen: naming it incontext.getalone, which leaves the agent no way to know the rule exists, the silent rule #123 warns about; joining it whole, which makes it an always rule under another name. A rule with none of the three (Manual, which Cursor joins when someone@-mentions it) is not joined and is listed asinactive: Troupe has no@rulemention, and a person can still ask the agent to read the file. - The front matter. Read a line per key, as Cursor writes it and YAML would not always
read it (
globs: *.tsis an alias to YAML):globsa comma-separated string (commas inside{}kept), a[...]list or a list of-lines, quotes taken off;descriptionfolded across indented lines;alwaysApplytrue when it saystrue. A file without front matter, or with one that is never closed, has none of the three. - Globs. Taken from the directory that holds
.cursor: the repository root for the root's rules, as Cursor has it, and a nested rule's own directory for its rules, which is how a package'ssrc/**reads.**crosses directories,*and?do not,{a,b}is either. A glob without a/matches a file's name in any directory, as.gitignorereads it and as rules written*.tsxexpect; one ending in/matches everything under it; one that does not compile matches nothing. Matched against the paths as the calls named them, from that directory, without case on Windows. - Why, in words. Every rule says why it applies or why not. A rule in the prompt has
applies(always applied;applied: src/a.ts matches src/**/*.ts, or... under web/for a nested one). A rule not in it hasreason:applies when a file matching src/**/*.ts is read or edited,requested by description only: listed in the prompt, not joined,not joined: no alwaysApply, globs or description, or the budget's or the edge's, as any file has. 806 stands:reasonis null for a file whose contents reached the prompt, and a listed rule's contents did not, so it has one./contextprintsappliesafter the characters (.cursor/rules/ts.mdc (root) 7, applied: src/a.ts matches src/**/*.ts) andreasonas it prints any (TUI Decision 148).rulecarries the front matter as read (apply:always,globs,requestedormanual;globs,description, andmatched, the file a glob matched), null for every other file, for a program,troupe instructions checkamong them, to read. - The edge. A rule is confined as every other file is (798): one that is really
outside the repository, through a link, is
outsideand not read. A.cursor/rulesdirectory that is really outside is listed once asoutsideand not looked into, so not even the names of the files there reach the log. A rule's@is not followed as an import: Cursor takes it as a file to attach, not an instruction file, and following it from.cursor/rules/would resolve it in the wrong place. - What is left of the budget is what the files nearer in did not take. The allotment subtracted the length of each file's text, which until now was always what the file took or more than was left; a listed rule left out whole would have spent the budget of the files farther out, and now leaves it to them.
- Additive. New keys
ruleandapplieson every file, newstatusvaluesinactiveandlisted, new entries infiles; neither the result ofcontext.getnor the event'sfilesitems are in the committed schema.load/3,to_prompt/1,provenance/1,3andfocus/1keep their shape.
Governs: apps/troupe_core/lib/troupe/instructions.ex, clients/tui/lib/troupe/client/instructions.ex