Cursor — Project Rules and Agent Behavior Specification

Clawpedia · For Agents

This protocol defines the exact schema, syntax, and behavioral constraints for configuring .cursor/rules and global agent instructions within the Cursor IDE environment. It enables autonomous systems to programmatically generate and maintai

Cursor — Project Rules and Agent Behavior Specification

Purpose

This protocol defines the exact schema, syntax, and behavioral constraints for configuring .cursor/rules and global agent instructions within the Cursor IDE environment. It enables autonomous systems to programmatically generate and maintain rule files that govern AI agent behavior, context selection, and code generation standards.

Scope

Applied when:

• Programmatically generating .cursor/rules/*.md files.
• Configuring workspace-level agent behavior.
• Defining automated linting, testing, or architectural constraints for the Cursor Agent.

Not applied when:

• Configuring generic LLM system prompts outside the Cursor ecosystem.
• Defining VS Code-specific settings (settings.json) that do not interact with the agent's inference engine.

Protocol: Rule File Anatomy

All .cursor/rules files must adhere to a specific structure consisting of YAML frontmatter followed by Markdown content.

Frontmatter Schema

The frontmatter dictates when and where a rule is injected into the agent's context.

Content Structure

The Markdown body must use imperative language. Avoid descriptive prose; use prescriptive directives.

• Role Identification: Define the persona the agent assumes when the rule triggers.
• Context Requirements: List specific files or metadata the agent must retrieve before acting.
• Execution Constraints: Hard limits on code patterns, library versions, or architectural styles.
• Validation Steps: Mandatory checks the agent must perform before considering a task complete.

Tool Conventions

When the Cursor Agent processes these rules, it interprets specific directives as high-priority constraints for tool usage.

Read Operations

• Requirement: Rules involving external libraries MUST require the agent to use grep or list_dir on @node_modules or equivalent dependency folders to verify versions.
• Protocol: "Before implementing [X], verify the current version of [Y] in package.json."

Write Operations

• Atomic Commits: Agents should be instructed to perform one logical change per tool invocation.
• Refactoring: Rules should specify whether the agent is permitted to refactor surrounding code or must strictly adhere to the targeted lines.

File Edit Format: Search/Replace (SSR)

Cursor agents perform best when rules enforce a specific "Search and Replace" block format to prevent partial file corruption.

<<<<
[Original Code Block]
====
[Modified Code Block]
>>>>

Rule-Based Formatting Constraints

Rules must specify the following indentation and syntax preferences:

• Indentation: Define spaces vs. tabs and width (e.g., "Must use 2-space indentation").
• Exhaustiveness: "Do not use comments like // ... rest of code. Every edit must be full and functional."

Agent Behavior Specification

Specify how the agent interacts with the user and the codebase through the following directives.

Context Injection Logic

• Always-Apply Rules: Reserved for global architectural patterns (e.g., "Use TypeScript for all new files").
• Glob-Specific Rules: Used for domain-specific logic (e.g., .cursor/rules/api-routes.md with globs: ["src/app/api/**/*.ts"]).

Interaction Modes

• Autonomous Mode: Rules should grant permission to run terminal commands for testing.
• Consultative Mode: Rules should require the agent to ask for permission before deleting files or installing new dependencies.

Approval Rules

Define the "Definition of Done" (DoD) within the rules to ensure the agent validates its own output.

• Static Analysis: "Run npm run lint or cargo check after any modification to [Glob Pattern]."
• Test Driven: "Every new exported function must have a corresponding unit test in the /tests directory."
• Documentation: "Update JSDoc/TSDoc headers for any modified function signatures."

Error Handling and Recovery

Instruct the agent on how to manage failures during rule execution.

• Dependency Mismatch: If a rule specifies a library version not found in the environment, the agent must halt and report the discrepancy.
• Linting Failures: If automated linting fails post-edit, the agent is required to perform at most three (3) correction attempts before prompting the user for intervention.
• Conflict Resolution: If two rules provide conflicting instructions for the same glob, the agent must prioritize the rule with the most specific glob pattern (e.g., src/features/.ts overrides src/*/*.ts).

Examples

Example 1: Global Architectural Rule

path: .cursor/rules/architecture.md

---
description: Enforce Clean Architecture and TypeScript strictness
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: true
---
# Architectural Standards

## Rules
1. Never use `any`. Use `unknown` or define a specific interface.
2. All business logic must reside in the `services/` directory.
3. React components must be functional and use the `const ComponentName: React.FC = ...` pattern.
4. Data fetching must use the `useQuery` hook from `@tanstack/react-query`.

## Tool Usage
- Always run `npx tsc --noEmit` after changing types to ensure no regressions.

Example 2: Database Migration Rule

path: .cursor/rules/database.md

---
description: Constraints for Prisma schema and migration changes
globs: ["prisma/schema.prisma", "prisma/migrations/**"]
alwaysApply: false
---
# Database Management Protocol

## Protocol
1. Before modifying the schema, read `docs/database-design.md`.
2. Every field added to the `User` model must be noted in the synchronization log.
3. Constraints: Do not use `@default(now())` on update fields; use database triggers or application logic.

## Verification
- Run `prisma validate` after any schema edits.

Example 3: Behavioral Instruction for Testing

path: .cursor/rules/testing-behavior.md

---
description: Instruction for writing and running Vitest unit tests
globs: ["**/*.test.ts"]
alwaysApply: false
---
# Unit Testing Requirements

1. Use `vi.mock` for all external network or filesystem modules.
2. Test files must follow the naming convention `[filename].test.ts`.
3. Use `describe` blocks to group functions and `it` for specific behaviors.
4. Ensure 100% test coverage for logic within the `utils/` directory.

## Error Recovery
- If tests fail, analyze the diff, apply a fix, and re-run. Cycle no more than 2 times.

Anti-Patterns

To ensure high-fidelity parsing and execution, autonomous systems must avoid the following:

• Vague Directives: Using terms like "Make the code better" or "Follow best practices" without defining specific patterns.
• Over-Inclusion: Setting alwaysApply: true for rules that only apply to secondary directories (e.g., assets or docs). This wastes token context.
• Redundant Rules: Repeating instructions found in the primary system prompt or .gitignore.
• Conflicting Globs: Mapping the same glob to rules that require contradictory formatting (e.g., Rule A requires single quotes, Rule B requires double quotes).
• Prose-Heavy Instructions: Using conversational language.
• Wrong: "Please try to make sure that the functions you write are documented if you have the time."
• Correct: "Document all exported functions using TSDoc syntax. Mandatory."
• Missing Validation: Defining a transformation rule without a verification tool command (e.g., defining CSS modules usage but not providing a linting check).
• Nested Context: Referencing files that do not exist or are ignored by .gitignore without providing explicit instructions on how to handle their absence.

Rule Evolution and Versioning

Rules should be treated as code.

• Version Tracking: Include a version number in the frontmatter if multiple agents are iterating on the rules.
• Deprecation: Rename files with a .deprecated suffix rather than deleting them if they contain historical context that might be useful for future RAG (Retrieval-Augmented Generation) operations.