Cursor rules guide

Cursor rules instruct the IDE agent how to behave in your repository. Official guidance is on cursor.com/docs/rules. Cursor is a trademark of Anysphere, Inc.; we refer to it nominatively. This guide complements Claude Code vs Cursor when your team standardizes on the IDE path.

What rules are for

Rules encode repeatable habits: which package manager commands to run, which domains must never appear in copy, how git remotes should look, and where secrets must never be committed. They reduce the chance that an agent improvises a deploy script or edits the wrong tenant’s config.

Rules are not a product requirements document. A multi-day feature still needs a spec with acceptance tests—see spec-driven development.

Effective rule patterns

One concern per file. Mixing git policy, SEO canonicals, and payment integration in one giant rule causes conflicts. Split files so reviewers can approve safety policy without debating marketing tone.

Always-apply vs globs. Reserve always-on rules for irreversible risks: no force-push, no credential files in commits, no invented client metrics. Scope product rules to paths (apps/web/**) so a CMS task does not load ecommerce canon.

Actionable commands. Name the exact verify steps: pnpm --filter @scope/app test, pnpm validate, site build <id> --pull. Vague “run tests” invites the agent to skip.

Negative space. List features or domains you refuse to build—trademark-sensitive microsites, affiliate URL patterns, or retired brands. Agents otherwise hallucinate “helpful” expansions.

Precedence when rules disagree. Document which file wins (safety > product > style). In monorepos, note which rules apply only in worktrees or branch checkouts.

Rules in this repository

The KnowledgePunk / PunkSolid monorepos carry rules for canonical URL precedence, GitHub remote policy, and waiting-on-user secrets so agents do not commit partial production state. The ai-network package’s AGENTS.md summarizes verify commands; Cursor rules drill into paths agents must not touch without approval.

When we deliver website development or Claude Code development, we export a starter rules set aligned to your stack—not a generic template.

Rules vs specs vs AGENTS.md

Artifact	Audience	Typical content
Cursor rules	Cursor IDE agent	Scoped habits, globs, safety
AGENTS.md	Any coding agent	Install, verify commands, architecture map
Task spec	Humans + agents	Acceptance criteria for one change

AGENTS.md is documented at agents.md; it is not Cursor-specific. Pair AGENTS.md guide with rules when teammates split between IDE and terminal agents.

Skills and documentation links

Cursor may also load skills or indexed docs depending on your version. Treat vendor docs as authoritative for feature names; rules should reference stable internal conventions, not copy entire vendor manuals.

Link from rules to internal README sections instead of duplicating architecture treatises. Duplication rots when only one copy updates.

Reviewing rule changes

Rule edits are code changes. Review them in pull requests like application logic—especially when always-apply files broaden scope. A rule that forces affiliate patterns or wrong canonicals can damage SEO across the network.

On migrations, add rules that forbid URL or redirect edits without an approved inventory CSV. That pairs with the website migration SEO checklist.

Anti-patterns

• Pasting API keys or webhook secrets “so the agent can test”
• “Be careful with production” without naming forbidden directories
• Copying entire style guides instead of pointing at ESLint/Prettier
• Rules that contradict AGENTS.md verify steps

First-hand habits from PunkSolid deliveries

We keep rules short enough to read in a standup and tie them to commands we actually run on the client laptop and CI. After handoff, optional cursor coaching walks maintainers through rule updates when frameworks change.

When agents still wander, the fix is usually tighter globs or a written spec—not a longer rule file.

Commercial context

PunkSolid does not operate third-party “Cursor agency” directories. Independent directory sites are a separate network concern; hire pages describe our custom software development and review gates in methodology.

Next steps

Compare terminal workflows in Claude Code vs Cursor. Run a safe first session with the Claude Code tutorial. Need rules authored for your monorepo? Start on website development or contact with repository access policies.

Example rule topics (starter list)

Consider dedicated rule files for: package manager discipline (no mystery npm install in a pnpm repo); tenant or site ID requirements when builds read SITE_ID; content status rules forbidding reviewed without human reviewedBy; trademark and non-affiliation copy on vendor comparison pages; migration rules requiring CSV attachments before redirect edits; infra rules marking Terraform or k8s paths human-only.

Keep each file under a screen of text. Link to methodology for human gate expectations your agents cannot enforce.

Testing rule changes safely

Create a throwaway branch and run a bounded agent task after rule edits. If the agent suddenly refuses legitimate work, your globs are too broad. If it still edits forbidden paths, add explicit negatives (“never modify packages/site-config/src/live.ts without user message”).

Capture failing prompts in an internal doc—not in public rules—so you do not leak client names or URLs.

Rules during content and SEO work

Marketing repos benefit from rules that force absolute internal links, forbid affiliate query params, and require pnpm validate after Markdown changes. Those habits mirror the automated gate in this ai-network package.

When agents draft comparison pages, rules should ban star ratings and “we tested” claims unless the tool is in your approved first-hand list (Cursor, Claude Code, GA4, Search Console, named tracking stack).

Handoff to client teams

Export a rules README explaining which files are safe for juniors to edit versus which need staff engineer review. Pair export with code ownership so clients are not locked into PunkSolid for every prompt tweak.

Optional coaching sessions walk maintainers through updating globs when frameworks upgrade—Next major bumps, Astro content collections, or new test runners.

When rules are not enough

If quality still slips, the bottleneck is usually missing specs or weak CI—not rule length. Add acceptance tests, link scanners, or Lighthouse budgets before you add a tenth always-apply rule file.

Regulated launches still need human sign-off on public copy regardless of rule quality—that expectation is central to vibe code to production rescue framing when teams skipped gates early.