Cursor rules

    Cursor rules are part of your agent harness.

    Cursor rules tell the editor how to behave around your repo. AgentLint audits those rules next to CLAUDE.md, AGENTS.md, CI, hooks, and 33 evidence-backed checks so the guidance stays specific, current, and enforceable.

    01 / What .cursor/rules files do

    Cursor uses rules as persistent context for the AI features inside the editor. A rule can describe project architecture, coding standards, forbidden paths, preferred commands, review expectations, or any other repo fact the model should see before it edits.

    Modern Cursor projects commonly store project rules as .cursor/rules/*.mdc files. That format keeps instructions close to the repository instead of relying only on a personal editor setting, and it lets teams split rules by topic or file pattern.

    Cursor also separates broad AI behavior from chat-local instructions. Rules for AI describe durable behavior the assistant should keep applying, while rules for the current chat are short-lived context for a specific task. AgentLint treats durable project rules as harness material because they can affect every future edit.

    The practical split is project versus global. Global Cursor rules are useful for personal preferences that apply everywhere. Project rules should carry repo facts, commands, safety boundaries, and the source-of-truth decisions a teammate should inherit after cloning the repo.

    02 / Common .cursor/rules failure modes

    Vague rules that Cursor cannot act on

    Rules like "write clean code" or "follow project conventions" give the model a preference, not a decision. Cursor rules work best when they name the file class, command, output, or stop condition.

    Stale paths and examples

    A .cursor/rules file can keep pointing to old package names, moved source folders, removed scripts, or examples copied from a previous architecture. The model still reads those paths as current project truth.

    Contradictions with CLAUDE.md or AGENTS.md

    Many repos now carry rules for multiple agents. When .cursor/rules says one test command and CLAUDE.md says another, the agent has to guess which harness layer is authoritative.

    Missing enforcement for critical instructions

    Security, release, data, and destructive-command rules should not live only in prose. If the repo depends on a Cursor rule, CI, hooks, permissions, or a required verification command should back it up.

    Rules loaded in the wrong scope

    A global Cursor preference can accidentally override a project rule, while a project-only rule may never reach a different repo that assumes the same behavior. Scope needs to be explicit.

    03 / How AgentLint catches them

    Referenced files must exist at the paths the harness names, so stale .cursor/rules examples are caught before Cursor repeats them.

    Duplicate rules need a named source of truth, which helps keep .cursor/rules aligned with CLAUDE.md, AGENTS.md, and Copilot instructions.

    Critical rules need CI, hooks, permissions, or required checks, so important Cursor instructions are paired with mechanical enforcement.

    Run AgentLint on your repo.

    Check .cursor/rules beside the rest of your agent harness before stale instructions become editor behavior.

    Run AgentLint on your repo