8.1 KiB

Raw Blame History

Cursor Integration

This guide explains how to integrate Agent Guardrails with Cursor using markdown-based rules.

Overview

Cursor supports:

Rules - Markdown files with YAML frontmatter that define AI behavior and constraints
Global Rules - .cursorrules file in project root for universal settings

The setup script installs these configurations for you.

Setup

1. Install All Rules

python scripts/setup_agents.py --install --platform cursor

This creates:

.cursor/
├── rules/
│   ├── guardrails-enforcer.md
│   ├── commit-validator.md
│   ├── env-separator.md
│   ├── scope-validator.md
│   ├── production-first.md
│   ├── three-strikes.md
│   └── error-recovery.md
└── .cursorrules (optional root config)

2. Install a Single Skill

To install just one skill by name:

python scripts/setup_agents.py --install-skill guardrails-enforcer --platform cursor

Use --list-skills to see all available skill names:

python scripts/setup_agents.py --list-skills

3. Verify Installation

Check that rules are loaded:

ls -la .cursor/rules/

Check that .cursorrules exists (if using global config):

cat .cursorrules

Rule File Format

Rules are markdown files in .cursor/rules/ with YAML frontmatter:

---
description: Enforces the Four Laws of Agent Safety on all code generation
globs: "**/*"
alwaysApply: true
---

# Guardrails Enforcement

You are the Guardrails Enforcement Agent. Enforce these rules on EVERY operation.

## The Four Laws of Agent Safety

1. **Read Before Editing** - Never modify code without reading it first
2. **Stay in Scope** - Only touch files explicitly authorized
3. **Verify Before Committing** - Test and check all changes
4. **Halt When Uncertain** - Ask for clarification instead of guessing
...

Frontmatter Fields

Field	Type	Description
`description`	string	Summary shown in the Cursor rules list
`globs`	string	File patterns this rule applies to (e.g., `"*/"`, `"src/*/.ts"`)
`alwaysApply`	boolean	Whether to apply this rule to every session automatically

Example: guardrails-enforcer.md (Actual File)

---
description: Enforces the Four Laws of Agent Safety on all code generation
globs: "**/*"
alwaysApply: true
---

# Guardrails Enforcement

You are the Guardrails Enforcement Agent. Enforce these rules on EVERY operation.

## The Four Laws of Agent Safety

1. **Read Before Editing** - Never modify code without reading it first
2. **Stay in Scope** - Only touch files explicitly authorized
3. **Verify Before Committing** - Test and check all changes
4. **Halt When Uncertain** - Ask for clarification instead of guessing

## Pre-Operation Checklist

Before ANY file modification:
- [ ] Read the target file(s) completely
- [ ] Verify the operation is within authorized scope
- [ ] Identify the rollback procedure
- [ ] Check for test/production separation requirements

## Forbidden Actions

1. Modifying code without reading it first
2. Mixing test and production environments
3. Force pushing to main/master
4. Committing secrets, credentials, or .env files
5. Running untested code in production
6. Modifying unread code
7. Working outside authorized scope

## Halt Conditions

STOP and escalate when:
- Attempting to modify code you haven't read
- No rollback procedure exists or is unclear
- Production impact is uncertain
- User authorization is ambiguous
- Test and production environments may mix
- You are uncertain about ANY aspect of the task
- An operation has failed 3 times

Global Rules (.cursorrules)

The .cursorrules file in the project root applies to all Cursor sessions:

# Project Rules

## Always

- Follow the Four Laws of Agent Safety
- Read files before editing
- Validate commits before creating

## When

- Editing code: Check scope boundaries
- Running commands: Verify environment separation

Use .cursorrules for simple, universal rules. Use .cursor/rules/*.md for structured, per-skill rules with frontmatter.

Rule Reference

guardrails-enforcer

Applies to all files. Enforces the Four Laws, pre-operation checklist, forbidden actions, and halt conditions.

commit-validator

Validates git commits. Checks AI attribution, single focus, no secrets, tests pass.

env-separator

Enforces test/production separation. Detects shared instances, production DB in tests.

scope-validator

Enforces scope boundaries. Only explicitly authorized files may be modified.

production-first

Requires production code before tests. Order: implementation, validation, tests, infrastructure.

three-strikes

Failure recovery. After three consecutive failures, halts and escalates to user.

error-recovery

Error handling procedures. Provides structured guidance when operations fail.

Shared Prompts Reference

All rule markdown files incorporate rules from the shared prompts directory:

Shared Prompt	Used By Rules
`skills/shared-prompts/four-laws.md`	guardrails-enforcer
`skills/shared-prompts/halt-conditions.md`	guardrails-enforcer
`skills/shared-prompts/three-strikes.md`	three-strikes
`skills/shared-prompts/production-first.md`	production-first
`skills/shared-prompts/clean-architecture.md`	guardrails-enforcer
`skills/shared-prompts/cqrs.md`	guardrails-enforcer
`skills/shared-prompts/scope-validation.md`	scope-validator
`skills/shared-prompts/error-recovery.md`	error-recovery

When shared prompts are updated, re-run the setup script:

python scripts/setup_agents.py --install --platform cursor

Customization

Adding a Custom Rule

Create a new markdown file in .cursor/rules/:

---
description: Custom TypeScript strict mode enforcement
globs: "src/**/*.ts"
alwaysApply: false
---

## Always

- Use strict mode for all TypeScript files
- No `any` types allowed
- All functions must have return type annotations

Cursor automatically loads rules from this directory.

Rule Priority

Rules are applied in order:

.cursorrules (global) - Applied first
.cursor/rules/*.md - Applied in alphabetical order

Later rules can override earlier ones for the same context.

Conditional Rules with Globs

Use globs to target specific file patterns (e.g., "**/*.py", "src/**/*.ts"). Set alwaysApply: true for safety rules that must always be active.

Disabling a Rule

Move it out of the rules directory:

mkdir -p .cursor/rules/disabled
mv .cursor/rules/commit-validator.md .cursor/rules/disabled/

Cursor will stop loading it immediately.

Installation Modes

Mode	Command	Behavior
Copy	`--mode copy` (default)	Writes standalone copies to the project
Symlink	`--mode symlink`	Creates symlinks back to this repo

Troubleshooting

Rules Not Loading

Check frontmatter: --- delimiters with valid YAML
Files in .cursor/rules/ with .md extension
Restart Cursor to reload rules

.cursorrules Not Applied

File is in project root (not .cursor/)
File is named exactly .cursorrules (no extension)
Restart Cursor to re-index

Rules Being Ignored

Save all rule files
Restart Cursor to reload
Check for conflicting rules (later rules override earlier ones)
Verify globs pattern matches the files being edited

Best Practices

One rule = one responsibility - Keep rules focused and composable
Always include frontmatter - description, globs, alwaysApply are required
Use alwaysApply: true for guardrails - Safety rules should not be optional
Regenerate after shared prompt updates - Re-run setup to sync rules
Commit .cursor/ and .cursorrules - Team shares the same guardrails

References

AGENTS_AND_SKILLS_SETUP.md - Unified setup guide
AGENT_GUARDRAILS.md - Core safety protocols
skills/shared-prompts/ - Canonical prompt definitions

8.1 KiB Raw Blame History