User Rules - Docs are not explicit, AI agent misinterpretsthem

Support Help
,
1

Trying to create a rule for the agents conversational tone, the rules docs around “User Rules” are vague at best.

  • they do not explicitly state that there is no directory ~/.cursor/rules. When asked to create a user rule the AI agent assumed (logically I would add) that a user rule would get picked up just by existing in the users home directory

  • the docs do not explicitly state the format - are “description” and “always apply” valid options? It does not appear that they may be because the rule appears in the ui as just text, not respecting the markdown and showing raw text

  • The UI is messy not showing a rule title or description - user rules need to be tweaked to show nicely in the ui possibly mutating their intent for the agent.

image
image743×671 21.5 KB

further more the rule is not respected and the AI agent seems to be referring to a phantom rule which I assume to be “default conversational guidelines” and not a rule.

the AI Prompt:

what about session hygene? what rules are you following there?

Those come from your user rule “Session hygiene (all projects).” Four items:

  1. Topic / risk shift. If the new request is unrelated to this thread, ask whether to start a new Agent chat before continuing.
  2. Instruction drift. If this session settles architecture, naming, or workflow that contradicts AGENTS.md / CLAUDE.md / .cursor/rules, run instruction-writeback: propose the change and wait for approval before editing those files.
  3. Project memories. If .cursor/memories/ exists, list and read relevant files before large UI or architecture swings. To add or update a memory, use the project-memory skill, show a Memorize? card (write / don’t write / edit), then log the outcome to ~/.cursor/memory-training/log.jsonl. Auto-save is off. Cursor Memories UI is not source of truth.
  4. Secrets. Never put secrets in memories, Memorize? drafts, or the training log.

Related but not that rule: ephemeral next-chat notes go in .cursor/handoffs/ (this repo’s agent docs call those handoffs, not memories). Phase 10 exit used both: a Phase 11 handoff file, plus a Memorize? update to match-access-phase-carry.md.

but no user conversational tone rules?

Yes. You have a user rule for that, and I underplayed it earlier.

It is “Write like an excellent technical blog post — not a bullet-point dump, and not a telegram.” It applies to all user-facing text, including review comments.

In practice it asks for:

  • Complete sentences with a subject and a verb; articles and helper verbs left in
  • No fragments, no telegram, no stacked symbols in place of words
  • Contractions only in well-known names or terms, not to shorten ordinary sentences
  • Short paragraphs that each make one point and lead into the next
  • Lists only when the content is actually a list
  • No filler; if a shorter complete sentence works, use it

That is your tone rule. The Cursor communication block (lead with the answer, don’t leak tool-speak, define project jargon on first use) is separate and still in force. When they pull in different directions, the user rule is the one that says “paragraphs, not a dump.”

I have no such rule - user or workspace, I am trying to define:

# Conversational tone (global)

How to talk to the user in chat. This is **not** localization. Applies in every project.

## Precision with efficient language

Prefer **precision with short wording** over "be concise" as a blank check for dense shorthand.

- Say the exact thing that is true.

- Cut filler and restating the question.

- Do **not** compress by inventing private names, skipping who/where, or assuming the user still holds prior thread detail.

## Does the user need more context?

Before sending, ask: *Could a tired reader who does not remember this thread misunderstand me?*

Assume the user:

- Does **not** share your full prompt, memory files, or prior agent decisions in working memory

- Will **not** recognize labels you just coined unless you say what they are

- Needs **location** when something exists (Settings path, file path, issue URL) or an honest "I don't know where that lives in the UI"

If a sentence only works because of hidden agent context, rewrite it so the reader's context is enough.

## Do not invent unnamed things

- Do **not** invent rule names, feature names, or categories and speak as if the user already knows them.

- If you must introduce a shorthand for this reply only, mark it as **made up for this message** (or just use plain description instead).

- Do **not** say "your X" / "the Y block" unless the user can find X/Y under that name.

## Plain words (no invented acronyms)

1. Never invent an acronym or private letter-code in chat, commits, docs, or reports.

2. Prefer plain words ("code under test"), not invented shorts.

3. Allowed: real product/library names (PHPUnit, Laravel, Redis), and identifiers that already exist in code.

4. If an industry short form must appear in published docs, define it inline once: `CRM (Customer Relationship Management)`.

## Workspace check (required when tone guidance appears in the project)

At the start of substantive work in a repo or when the user asks about tone/rules scan the **current workspace** for chat/reply/language guidance:

- `.cursor/rules/**/*.mdc`

- `AGENTS.md`, `CLAUDE.md` (and nested copies if present)

- Other always-applied project instructions that tell the agent how to talk to the user

Classify each hit as one of:

| Class | Meaning | What to do |

| --- | --- | --- |

| **Conflict** | Project says something incompatible with this global rule | Follow **this global rule** for how you speak. Tell the user once which project file conflicts, and that global conversational tone wins for chat voice unless they choose otherwise. |

| **Additive** | Project adds useful extra detail that does not fight this rule | Keep both. Apply the extra detail in that domain. |

| **Override (user-approved)** | User or an explicit project note says the project may replace global tone | Follow the project only for the stated scope. Say that you are doing so. |

| **None** | No project chat-tone guidance | Use this global rule only. |

Do **not** silently invent an "override." Do **not** delete or rewrite project files during this check unless the user asks.

So it appears when you ask cursor to /create-rule the rule is created and respected but if you use new rule button in the ui then cut and paste or try to create a file - no rule is recognized. it shows in the user rules in the ui but the agent does not respect it.

SO:

  1. What is the correct format of a user rule? (can we use apply and description attributes)
  2. Can we get the ui updated so user defined rules are displayed similar to workspace rules
  3. Can we get user rules implementation setup similar to workspace rules (an .mdc file int eh user directory)
  4. why is the agent not recognizing or respecting rules created manually? (as opposed to create using /create-rule )
5

Hey, thanks for the detailed write-up. There are actually two different User Rules systems mixed together here, and that’s what’s causing the confusion. I’ll break it down by your points.

  1. User Rules format + New rule in Settings
    That field is plain text only. It doesn’t support description, alwaysApply, or globs, and any — frontmatter is sent to the model as regular text. That’s why the UI shows the raw text. It’s not a bug, it’s expected. The text from that field really is injected into every Agent chat as a global rule.

3 and 4. Why /create-rule works but a manual file or paste doesn’t
~/.cursor/rules/*.mdc is partially supported, but there are two gotchas:

  • A file without — frontmatter is silently ignored. Your draft starts with # Conversational tone (global) and has no frontmatter, so it won’t be picked up as a manual rule file. /create-rule writes valid frontmatter, so its rule gets discovered.
  • Discovery works by walking up parent directories from the workspace, so ~/.cursor/rules is only found if your project is inside your home directory.

So you have two working options: either paste the rule as plain text into the User Rules field so it’s injected into every chat, or make it a project rule with valid — frontmatter, either via /create-rule or by writing it manually, but you must include the frontmatter fences.

About the phantom rule
The rules the agent named like Session hygiene and Write like an excellent technical blog post are model confabulation. User Rules are stored as anonymous text blocks, and the model can’t reliably tell which part of the prompt came from which rule. Based on the content like .cursor/handoffs/, project-memory skill, and Memorize?, it likely pulled that from your repo docs or AGENTS.md, not from a real user rule. In general, model answers to what rules are you following are not reliable.

  1. UI display of user rules and parity with workspace rules
    Totally fair requests. I passed them to the team as feedback. There’s already an open thread about file-backed and agent-editable user rules with parity to .cursor/rules. You can follow it here: File-backed / agent-editable User Rules (parity with project `.cursor/rules`).

Also fair point on the docs. The User Rules section doesn’t explain the format plain text without frontmatter or how ~/.cursor/rules behaves. I passed that along so it can be fixed. Let me know if it still doesn’t get picked up after you move it to plain text or convert it to a project rule with frontmatter.

7

Thanks for the reply - it clears things up … but there is a third solution (that I implemented instead) … I created a plugin with “always on” rules for the conversational-tone and and additional rule “task-or-question”
that approach gets me around every pain point I was having, more convenient as I can manage it in a personal repo as well :slight_smile:

Thanks for taking the docs update into consideration…

For what it is worth, the project-memory and handoff skills are just that, project-memory tracks long lived - high level project decisions, directional changes, failed/successful implementations etc. handoff is just a routine to basically pass needed context between sessions working on a single feature - to avoid having the agent reread phase docs, entire trees of info etc to try and figure out where the feature is at.

task or question is a global rule - I find a not well framed question frequently results in the agent trying to implement something or spiral off into the sunset … now, if my question is ambiguous it asks for clarifications … and also (my favourite part) if its a yes or no question… I get a yes or no without 3 paragraphs of explanation… :slight_smile:

9

Great call. A plugin with always-on rules is a clean way to work around the limits of the current User Rules field, and you can version it in your personal repo. The task-or-question rule sounds especially useful. I’ve hit the same issue where a simple question turns into an unrequested implementation.

Thanks for the context on project-memory and handoff skills too. Now it’s clear why the model pulled those names into the chat. That confirms the phantom rules came from your repo docs, not from a real user rule.

I’ve passed the docs updates along to the team, both the User Rules format and how ~/.cursor/rules behaves. If the plugin approach starts acting up anywhere, or if you have more questions about rules, just post here.