π§ Quick diagnosis and solutions for common issues
Run these commands to quickly troubleshoot:
# 1. Check if file exists
ls -la .cursorrules
# 2. Check file location (must be in project root)
pwd
# 3. Check file content (ensure it has actual content)
head -20 .cursorrules
# 4. Check file encoding (should be UTF-8)
file .cursorrules
# 5. Check file permissions
stat .cursorrulesSave the following as diagnose.sh:
#!/bin/bash
# Cursor Rules Diagnostic Tool
echo "=== Cursor Rules Diagnostic Tool ==="
echo ""
# Check file exists
if [ -f ".cursorrules" ]; then
echo "β
.cursorrules file exists"
else
echo "β .cursorrules file not found"
echo " Solution: cp rules/frontend/react/nextjs-typescript/.cursorrules ./"
exit 1
fi
# Check file location
if [ -d ".git" ]; then
echo "β
File is in Git project root"
else
echo "β οΈ May not be in Git project root"
echo " Tip: Ensure .cursorrules is in project root, not a subdirectory"
fi
# Check file encoding
ENCODING=$(file -b --mime-encoding .cursorrules)
if [ "$ENCODING" = "utf-8" ] || [ "$ENCODING" = "us-ascii" ]; then
echo "β
File encoding correct: $ENCODING"
else
echo "β οΈ File encoding issue: $ENCODING"
echo " Solution: iconv -f GBK -t UTF-8 .cursorrules > .cursorrules.fixed"
fi
# Check file size
LINES=$(wc -l < .cursorrules)
if [ "$LINES" -lt 5 ]; then
echo "β οΈ File content too short ($LINES lines), may be incomplete"
else
echo "β
File content normal ($LINES lines)"
fi
# Check file permissions
if [ -r ".cursorrules" ]; then
echo "β
File is readable"
else
echo "β File is not readable"
echo " Solution: chmod 644 .cursorrules"
fi
echo ""
echo "=== Diagnosis Complete ==="Usage:
chmod +x diagnose.sh
./diagnose.shSymptoms: AI suggestions don't follow .cursorrules content
Root Causes:
| Check Item | Normal State | Solution |
|---|---|---|
| File Location | Project root | Move to root directory |
| Setting Enabled | "Use .cursorrules" is ON | Enable in settings |
| Filename | .cursorrules (dot prefix) |
Check filename |
| File Encoding | UTF-8 | Convert encoding |
Solution Steps:
# Step 1: Confirm file location
ls -la .cursorrules
# Should be in project root, not a subdirectory
# Step 2: Restart Cursor
# Fully close Cursor, then reopen
# Step 3: Check Settings
# Cursor > Settings > Search "cursorrules" > Enable toggleSymptoms: Chinese content displays as garbled text
Diagnosis:
# Check encoding
file .cursorrules
# View hidden characters
cat -A .cursorrules | head -20Solutions:
# Convert encoding (GBK -> UTF-8)
iconv -f GBK -t UTF-8 .cursorrules > .cursorrules.utf8
mv .cursorrules.utf8 .cursorrules
# Fix line endings (Windows -> Unix)
dos2unix .cursorrules
# Or use sed
sed -i 's/\r$//' .cursorrulesSymptoms: Inconsistent AI suggestions after merging multiple rules
Diagnosis:
# Find duplicate definitions
grep -n "naming" .cursorrules
grep -n "encoding" .cursorrules
grep -n "error handling" .cursorrulesSolutions:
-
Test with Single Rule Set
cp rules/frontend/react/nextjs-typescript/.cursorrules ./
-
Merge Gradually
- Add one rule first
- Test it, then add the next
-
Resolve Conflicts Manually
- Edit
.cursorrulesfile - Remove conflicting rules
- Keep higher priority rules
- Edit
Symptoms: Cursor responds slowly
Diagnosis:
# Check file size
ls -lh .cursorrules
# Check line count
wc -l .cursorrulesRecommended Limits:
| Metric | Recommended | Over Limit Action |
|---|---|---|
| File Size | < 50 KB | Trim rule content |
| Line Count | < 500 lines | Remove redundant rules |
| Rule Items | < 50 items | Classify and layer management |
Optimization:
# 1. Remove unnecessary comments
# 2. Remove duplicate rules
# 3. Keep only core rules
# Optimization example: Convert detailed explanations to concise rules
# Before:
# Please ensure all components use TypeScript type definitions,
# including props, state, and function return values
# After:
# All components must use TypeScript type definitionsSymptoms: Technical terms are inconsistently translated
Resolution:
| Issue Type | Resolution |
|---|---|
| Inconsistent terms | Use standard translations, keep proper nouns in English |
| Code formatting issues | Check code block markers and indentation |
| Unclear expressions | Rephrase, split long sentences |
#!/bin/bash
# validate_cursorrules.sh
FILE=".cursorrules"
echo "π Validating .cursorrules file..."
echo ""
ERRORS=0
# Check file exists
if [ ! -f "$FILE" ]; then
echo "β Error: File not found"
exit 1
fi
# Check file not empty
if [ ! -s "$FILE" ]; then
echo "β Error: File is empty"
exit 1
fi
# Check encoding
ENCODING=$(file -b --mime-encoding "$FILE")
if [ "$ENCODING" != "utf-8" ] && [ "$ENCODING" != "us-ascii" ]; then
echo "β οΈ Warning: Possible encoding issue ($ENCODING)"
((ERRORS++))
else
echo "β
Encoding check passed: $ENCODING"
fi
# Check content
LINES=$(wc -l < "$FILE")
SIZE=$(wc -c < "$FILE")
echo "π File lines: $LINES"
echo "π¦ File size: $SIZE bytes"
if [ "$LINES" -lt 5 ]; then
echo "β οΈ Warning: Content too short"
((ERRORS++))
fi
if [ "$SIZE" -gt 51200 ]; then
echo "β οΈ Warning: File too large (recommended < 50KB)"
((ERRORS++))
fi
# Check for key content
if grep -q "coding standards\|code style\|naming" "$FILE"; then
echo "β
Found coding standards content"
else
echo "β οΈ No coding standards content found"
fi
echo ""
if [ $ERRORS -eq 0 ]; then
echo "β
Validation passed"
else
echo "β οΈ Found $ERRORS warning(s)"
fi#!/bin/bash
# check_environment.sh
echo "=== Environment Check ==="
echo ""
# Check Cursor
if command -v cursor &> /dev/null; then
echo "β
Cursor installed"
else
echo "β οΈ Cursor not found in PATH"
echo " Tip: Use alias or full path to launch"
fi
# Check Git
if command -v git &> /dev/null; then
echo "β
Git installed: $(git --version)"
else
echo "β Git not installed"
fi
# Check project structure
if [ -d ".git" ]; then
echo "β
Current directory is a Git repository"
else
echo "β οΈ Current directory is not a Git repository"
fi
# Check rules file
if [ -f ".cursorrules" ]; then
echo "β
.cursorrules file exists"
echo " Path: $(realpath .cursorrules)"
else
echo "β .cursorrules file not found"
fi
echo ""
echo "=== Check Complete ==="# Enable Cursor debug logging
export CURSOR_LOG_LEVEL=debug
# View logs
# macOS/Linux
tail -f ~/.cursor/logs/main.log
# Windows
Get-Content -Tail 50 $env:APPDATA\Cursor\logs\main.log# 1. Backup current configuration
cp .cursorrules .cursorrules.backup.$(date +%Y%m%d)
# 2. Delete current rules
rm .cursorrules
# 3. Copy fresh from rule set
cp rules/frontend/react/nextjs-typescript/.cursorrules ./
# 4. Restart Cursor# macOS
rm -rf ~/Library/Application\ Support/Cursor/cache
# Linux
rm -rf ~/.config/Cursor/cache
# Windows
Remove-Item -Recurse -Force $env:APPDATA\Cursor\cache| Resource | Link |
|---|---|
| π Quick Start | getting-started.md |
| π‘ Best Practices | best-practices.md |
| βοΈ Installation Guide | installation-guide.md |
| Channel | Purpose | Link |
|---|---|---|
| π Issues | Report Bugs | GitHub Issues |
| π¬ Discussions | Q&A, Experience Sharing | GitHub Discussions |
When submitting an issue, please include:
## Problem Description
[Briefly describe the issue]
## Environment Info
- Operating System: [e.g., Windows 11 / macOS 14 / Ubuntu 22.04]
- Cursor Version: [e.g., 0.45.0]
- Rule Set: [e.g., frontend/react/nextjs-typescript]
## Reproduction Steps
1. Step one
2. Step two
3. Step three
## Expected Behavior
[Describe expected result]
## Actual Behavior
[Describe what actually happened]
## Additional Info
- .cursorrules file content (or key parts)
- Error message screenshots
- Solutions already triedA: Yes. Cursor prioritizes rules in deeper directories. For example:
- Root
.cursorrulesβ General rules frontend/.cursorrulesβ Frontend-specific rules (higher priority)
A: Cursor itself only reads one .cursorrules file. You can:
- Merge multiple rules into one file
- Use directory-level rules for separate configuration
A: It's recommended to restart. In some cases, reopening the project is sufficient.
A: Rules primarily affect AI-generated new code. Existing code won't be automatically modified.
π‘ Tip: Most issues can be resolved with these three steps:
- Confirm
.cursorrulesis in project root- Restart the Cursor editor
- Check file encoding is UTF-8