CodeGuard: Files in documentation not working inside Cursor / not recognized as valid rule files

[Parveen-Birthaliya]

Hi @santosomar,

I’m integrating CodeGuard rules into Cursor and also exploring adding support in Antigravity.

I followed all instructions from the README and documentation, including copying the example rule files into my project. After testing them, I noticed an issue:

Issue Observed

The files shown in the documentation appear to be only documentation examples, not actual rule files that Cursor recognizes.
They don’t contain the required fields such as:

• rule_id
• globs
• trigger
• behavior

Because of that, Cursor treats them as non-functional docs, not executable rules.

[santosomar]

Hi @Parveen-Birthaliya

Have you read the documentation or followed this?

https://project-codeguard.org/getting-started/

[santosomar]

Hi @Parveen-Birthaliya ,

Specifically, the following:

Direct link here.

Installation

Option 1: Download Pre-built Rules (Recommended)

1. Download: Visit the Releases page and download the IDE-specific ZIP file:
   • ide-rules-all.zip - All IDE formats (recommended for teams using multiple tools)
   • ide-rules-cursor.zip - Cursor only
   • ide-rules-windsurf.zip - Windsurf only
   • ide-rules-copilot.zip - GitHub Copilot only
2. Extract: Unzip the downloaded file
3. Install: Copy the relevant IDE-specific rules to your project root:
   • For Cursor: Copy .cursor/ directory to your project
   • For Windsurf: Copy .windsurf/ directory to your project
   • For GitHub Copilot: Copy .github/ directory to your project

!!! tip "Repository Level Installation"
Installing at the repository level ensures all team members benefit from the security rules automatically when they clone the repository.

!!! note "Hidden Files on macOS/Linux"
On macOS/Linux, you may need to show hidden files:

- **macOS Finder**: Press ++cmd+shift+period++ to toggle visibility
- **Linux**: Use `ls -la` in terminal or enable "Show Hidden Files" in your file manager

Claude Code Plugin

Claude Code uses a plugin system instead of manual file installation:

# Add the Project CodeGuard marketplace
/plugin marketplace add project-codeguard/rules

# Install the security plugin
/plugin install codeguard-security@project-codeguard

The plugin will be automatically loaded and apply security rules to your code. See the Claude Code Plugin documentation for more details.

Option 2: Build from Source

If you want to customize or contribute to the rules:

# Clone the repository
git clone https://github.com/project-codeguard/rules.git
cd rules

# Install dependencies (requires Python 3.11+)
uv sync

# Validate rules
uv run python src/validate_unified_rules.py sources/

# Convert rules (default: core rules only)
uv run python src/convert_to_ide_formats.py

# Or include all rules (core + owasp supplementary)
uv run python src/convert_to_ide_formats.py --source core owasp

# Copy the generated rules to your project
cp -r dist/.cursor/ /path/to/your/project/
cp -r dist/.windsurf/ /path/to/your/project/
cp -r dist/.github/ /path/to/your/project/

Verify Installation

After installation, your project structure should include:

your-project/
├── .cursor/
│   └── rules/
├── .windsurf/
│   └── rules/
├── .github/
│   └── instructions/
└── ... (your project files)

[Parveen-Birthaliya]

I figured out where I went wrong.

When I asked ChatGPT about the rule, it said it wouldn’t work. Then I asked it to double-check and make sure you are 100% correct then chatgpt told that Cursor only uses .yml or .yaml. It still insisted the rule wouldn’t work.

After verifying with the original documentation, I realized that .mdc is supported, and the exact structure generated by CodeGuard is valid.

Thank you for pointing me in the right direction. And apologies — I should have checked the documentation first instead of relying only on ChatGPT.