Tutorial: Setting up SpecLock with Cursor

[sgroy10]

Tutorial: Setting up SpecLock with Cursor

Same idea as the Claude Code setup but for Cursor users. Three commands, ~60 seconds.

Prerequisites

• Node.js 18+
• Cursor installed (cursor.com)
• A .cursorrules or CLAUDE.md file in your repo (SpecLock reads both)

Step 1: Protect the repo

npx speclock protect

SpecLock will auto-detect both CLAUDE.md and .cursorrules and merge rules from both sources into its lock registry.

Expected output:

SpecLock v5.5.7 — protecting repository
  Parsed CLAUDE.md: 12 rules detected
  Parsed .cursorrules: 6 rules detected
  Merged 18 rules (2 duplicates collapsed)
  Extracted 14 locks
  Installed pre-commit hook

Protected.

Step 2: Install the Cursor rules file

npx speclock mcp install cursor

What this does:

• Creates .cursor/rules/speclock.mdc — a Cursor-native rules file that Cursor's agent reads on every turn
• Registers the SpecLock MCP server in Cursor's MCP config (Cursor 0.42+)
• Configures Cursor to call speclock_session_briefing at session start

Expected output:

Installing SpecLock for Cursor...
  Created .cursor/rules/speclock.mdc
  Updated ~/.cursor/mcp.json
  51 MCP tools registered

Done. Restart Cursor to load the new rules.

Step 3: Verify

npx speclock doctor

Expected output (Cursor-specific lines shown):

  Integrations
    Cursor rules ................. .cursor/rules/speclock.mdc (active)
    Cursor MCP ................... registered
    Pre-commit hook .............. active

What .cursor/rules/speclock.mdc looks like

SpecLock generates an .mdc file that follows Cursor's rule format:

---
description: SpecLock enforcement rules for this repo
globs: ["**/*"]
alwaysApply: true
---

# SpecLock-enforced constraints

Before making changes, call speclock_check_conflict to verify
against the repo's lock registry.

Locked constraints (do not violate without explicit user override):

1. Never remove the rate limiter middleware from api/middleware/
2. Always use the repository pattern for DB access
3. Minimal diffs only — no speculative refactors
...

The rules listed in this file are auto-generated from your CLAUDE.md + .cursorrules. Don't edit it by hand — run npx speclock sync-rules after updating either source file and SpecLock will regenerate it.

Cursor-specific gotchas

Rules not loading — Cursor loads .mdc files only when alwaysApply: true is set OR the glob matches the current file. SpecLock sets alwaysApply: true by default.

MCP not registering — Requires Cursor 0.42 or later. Check Cursor > Settings > MCP and verify speclock shows as connected (green dot).

Rules conflict with your existing .cursorrules — Run npx speclock sync-rules --dry-run to see the merged output before writing.

Next steps

Once SpecLock is running in Cursor, try:

npx speclock audit --semantic

This runs a full semantic audit on your working tree and tells you if Cursor (or anyone) has drifted from the rules since the last checkpoint.

Questions? Drop them below.