101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
|
# Cursor Rules
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
## What is Cursor?
|
||
|
|
|
||
|
|
[Cursor](https://cursor.sh) 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
|
||
|
|
|
||
|
|
## Understanding Cursor Rules
|
||
|
|
|
||
|
|
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:
|
||
|
|
```yaml
|
||
|
|
---
|
||
|
|
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
|
||
|
|
|
||
|
|
## Available Rules
|
||
|
|
|
||
|
|
Currently, the following rules are defined:
|
||
|
|
|
||
|
|
### `simple-language.mdc`
|
||
|
|
- **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
|
||
|
|
|
||
|
|
### `new-features-planning.mdc`
|
||
|
|
- **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](https://cursor.sh)" in PRs
|
||
|
|
|
||
|
|
### `followups.mdc`
|
||
|
|
- **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
|
||
|
|
|
||
|
|
### `documentation-sync.mdc`
|
||
|
|
- **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
|
||
|
|
|
||
|
|
## Creating New Rules
|
||
|
|
|
||
|
|
To create a new rule:
|
||
|
|
|
||
|
|
1. Create a `.mdc` file in `.cursor/rules/` using lowercase naming
|
||
|
|
2. Add YAML frontmatter with required metadata:
|
||
|
|
```yaml
|
||
|
|
---
|
||
|
|
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
|
||
|
|
|
||
|
|
## Best Practices
|
||
|
|
|
||
|
|
- 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
|