Cursor rules are configuration files that help guide AI-assisted development in the Cursor IDE. They provide structured instructions for how the AI should behave in specific contexts or when working with certain types of files.

Cursor is an AI-powered IDE that helps developers write, understand, and maintain code more efficiently. It integrates AI capabilities directly into the development workflow, providing features like:

• AI-assisted code completion
• Natural language code generation
• Intelligent code explanations
• Automated refactoring suggestions

Cursor rules are defined in .mdc files within the .cursor/rules directory. Each rule file follows a specific naming convention: lowercase names with the .mdc extension (e.g., simple-language.mdc).

Each rule file contains:

1. Metadata Header: YAML frontmatter that defines:

   ---
   description: when to apply this rule
   globs: file patterns to match (e.g., "*.py", "*.md", or "*" for all files)
   alwaysApply: true/false  # whether to apply automatically
   ---

2. Rule Content: Markdown-formatted instructions that guide the AI's behavior

Currently, the following rules are defined:

• Purpose: Ensures documentation is written at a grade 10 reading level
• Applies to: Markdown files (*.md)
• Auto Apply: No
• Key Requirements:
  • Write at grade 10 reading level
  • Ensure code blocks are self-contained with complete imports

• Purpose: Guides feature implementation workflow
• Applies to: Python files (*.py)
• Auto Apply: Yes
• Key Requirements:
  • Create new branch from main
  • Make incremental commits
  • Create todo.md for large features
  • Start pull requests using GitHub CLI (gh)
  • Include "This PR was written by Cursor" in PRs

• Purpose: Ensures thoughtful follow-up suggestions
• Applies to: All files
• Auto Apply: Yes
• Key Requirements:
  • Generate actionable hotkey suggestions using:
    • [J]: First follow-up action
    • [K]: Second follow-up action
    • [L]: Third follow-up action
  • Focus on small, contextual code changes
  • Suggestions should be thoughtful and actionable

• Purpose: Maintains documentation consistency with code changes
• Applies to: Python and Markdown files (*.py, *.md)
• Auto Apply: Yes
• Key Requirements:
  • Update docs when code changes
  • Add new markdown files to mkdocs.yml
  • Keep API documentation current
  • Maintain documentation quality standards

To create a new rule:

1. Create a .mdc file in .cursor/rules/ using lowercase naming
2. Add YAML frontmatter with required metadata:

   ---
   description: when to apply this rule
   globs: file patterns to match
   alwaysApply: true/false
   ---

3. Write clear, specific instructions in Markdown
4. Test the rule with relevant file types

• Keep rules focused and specific
• Use clear, actionable language
• Test rules thoroughly before committing
• Document any special requirements or dependencies
• Update rules as project needs evolve
• Use consistent file naming (lowercase with .mdc extension)
• Ensure globs patterns are explicit and documented