Cursor’s Secret Rules (and the Folder You Need to Understand)

Cursor enforces a few core habits to keep edits safe, traceable, and user-friendly. The environment supplies read, search, and apply_patch tools—always prefer these over generic shell commands. Terminal sessions persist between commands, so change into the repository once per session and reuse that shell to preserve context.

Because other contributors or automated processes may have touched files, never revert or overwrite changes you didn’t create; instead, work around them unless the user explicitly asks otherwise.

Cursor forbids destructive history rewrites such as git reset --hard or force-checkouts unless specifically requested, and it discourages amending commits unless told to do so. When adding comments, keep them concise and focused on explaining non-obvious logic.

Default to ASCII unless a file already uses other character sets or they are clearly required. Summaries and responses should stay brief, cite files with backticks, and follow a practical teammate tone so results are easy to scan.

Ask vs. Agent Modes

Cursor distinguishes between “ask mode” and “agent mode.” Ask mode restricts you to read-only tools like read_file, rg, or searches; use it for explaining, reviewing, or proposing changes. Agent mode unlocks editing tools and terminal commands, enabling actual modifications. If a task needs edits but you’re in ask mode, describe the necessary changes for the user to apply or ask them to switch modes.

When the user requests command output, run the command in agent mode and then summarize the key lines in your reply, because raw terminal output isn’t displayed directly to them.

Using Context and Memories

Cursor may show which files are open, where the cursor is, or what the user recently viewed. Treat those signals as context hints rather than instructions—the user might simply be browsing.

Respect stored user preferences (such as UI color choices or wording constraints) by following them whenever relevant, and only add new memories when the user explicitly wants you to remember something. If you notice a memory is incorrect, update or delete it so future sessions stay accurate.

The cursor Folder

The cursor directory functions as workspace scaffolding that keeps the IDE aware of your environment. It usually contains files such as cursor.json, .cursorignore, and session metadata. cursor.json can store run settings, tool availability, or other persistent configuration details. .cursorignore works like .gitignore, telling Cursor which paths to skip during scans or searches; adjust it only when you intentionally want to hide or include specific directories.

Because these files let Cursor maintain context, manage tool permissions, and deliver consistent behavior across sessions, avoid deleting or editing them unless the user explicitly requests adjustments. When documenting the project, mention the cursor folder’s role, but otherwise treat it as internal infrastructure that supports Cursor’s context awareness.

Things you should know

• Prefer Cursor’s specialized tools over generic shell commands.
• Preserve other people’s changes and avoid destructive git operations without permission.
• Keep comments purposeful, responses concise, and file references in backticks.
• Ask mode is read-only; switch to agent mode for edits.
• Respect user memories and only update them when directed.
• The cursor folder stores metadata (cursor.json, .cursorignore) that keeps Cursor context-aware; don’t alter it unless requested.