<p align="center"> <img src="https://img.shields.io/github/stars/girijashankarj/cursor-handbook?style=social" alt="GitHub stars" /> <img src="https://img.shields.io/github/forks/girijashankarj/cursor-handbook?style=social" alt="GitHub forks" /> <img src="https://img.shields.io/github/last-commit/girijashankarj/cursor-handbook" alt="GitHub last commit" /> <img src="https://img.shields.io/github/issues/girijashankarj/cursor-handbook" alt="GitHub issues" /> <img src="https://img.shields.io/badge/license-MIT-green" alt="License MIT" /> <img src="https://img.shields.io/badge/version-1.4.0-blue" alt="Version" /> <img src="https://img.shields.io/badge/Components-110-green" alt="110 Components" /> <img src="https://img.shields.io/badge/Token%20Savings-30%25%2B-green?style=for-the-badge" alt="30%+ Savings" /> </p>

cursor-handbook

The open-source rules engine for Cursor IDE — 110 rules, agents, and skills that turn your AI into a senior engineer who follows your standards, knows your codebase, and never wastes a token.

Stop teaching your AI the same things every session. cursor-handbook gives Cursor permanent memory of your standards, security policies, and workflows — across every project, every team member, every prompt.

<p align="center"> <strong>If cursor-handbook helps you, consider giving it a ⭐ — it helps others discover it.</strong> </p> <p align="center"> <img src="docs/snaps/readme-hero-banner.png" alt="cursor-handbook — Rules engine for Cursor IDE" width="800" /> </p>

---

Table of Contents

• Ways to use
• The Problem
• Before vs After
• Who is this for?
• How It Works
• Quick Start
• Documentation

---

Ways to use cursor-handbook

Pick the option that fits your workflow:

| Option | Best for | |--------|----------| | 1. Clone & copy | Use the full rules engine in your repo. Clone this repo, copy the .cursor folder into your project, then edit project.json and tailor rules/agents/skills to your stack. | | 2. Add from GitHub (Cursor UI) | Use rules, skills, or agents without cloning. In Cursor IDE go to Settings → Rules / Skills / Agents, click Add new → Add from GitHub, and paste this repo’s clone URL. Add only what you need. |

| 3. Fork & customize | Maintain your own version. Fork this repo, adapt the .cursor files for your team or product, then use that fork across your projects or share it internally. | | 4. Pick and choose | Use individual components. Download only the production-ready, generic rules, skills, agents, commands, or hooks you need from this repo and drop them into your existing .cursor setup. |

Improvements welcome. If you want to add or improve rules, skills, hooks, agents, or commands, see CONTRIBUTING.md and open an issue or PR.

Forking? Replace girijashankarj with your GitHub org/username in badges, clone URLs, scripts/setup-cursor.sh, .github/CODEOWNERS, and docs before pushing.

---

The Problem

Every time you open Cursor IDE, your AI assistant starts from zero. It doesn't know your:

• Code conventions and architecture patterns
• Security policies (and happily hardcodes your API keys)
• Testing thresholds (and runs the full 100K-token test suite when you just wanted a type check)
• Handler patterns, naming conventions, or folder structure

You end up repeating yourself, burning tokens, and fixing the same mistakes. cursor-handbook fixes this permanently.

---

Before vs After

| Before cursor-handbook | After cursor-handbook | |------------------------|------------------------| | AI hardcodes API keys | Security rules block it | | AI runs full test suite (~100K tokens) | Uses type-check (~10K) or single-file tests | | You repeat conventions every session | Rules remember them — always on | | Inconsistent code across team | One rules engine, one standard | | No guardrails on expensive ops | Hooks warn or block dangerous commands |

<p align="center"> <img src="docs/snaps/before-after-concept.png" alt="Before vs After cursor-handbook" width="700" /> </p>

---

Who is this for?

| Audience | Benefit | |----------|---------| | Solo developers | Consistent AI behavior without repeating yourself every session | | Teams | Shared standards; everyone gets the same guardrails and conventions | | Enterprises | Security, compliance, and token efficiency built in from day one |

<p align="center"> <img src="docs/snaps/who-uses-this.png" alt="Who uses cursor-handbook" width="700" /> </p>

---

How It Works

graph TB
    subgraph INPUT ["Your Prompt"]
        A[Developer types a prompt in Cursor]
    end

    subgraph HOOKS_PRE ["Pre-Processing Hooks"]
        B[context-enrichment.sh<br/>Injects project context]
        C[shell-guard.sh<br/>Blocks dangerous commands]
    end

    subgraph ENGINE ["cursor-handbook Engine"]
        D[29 Rules<br/>Always-applied standards]
        E[34 Agents<br/>Specialized AI assistants]
        F[21 Skills<br/>Step-by-step workflows]
        G[14 Commands<br/>Quick actions]
    end

    subgraph CONFIG ["Project Settings"]
        H[project.json<br/>Your project settings]
    end

    subgraph HOOKS_POST ["Post-Processing Hooks"]
        I[post-edit-check.sh<br/>Validates changes]
        J[auto-format.sh<br/>Formats code]
        K[coverage-check.sh<br/>Verifies thresholds]
    end

    subgraph OUTPUT ["AI Response"]
        L[Code that follows YOUR standards<br/>with 30%+ fewer tokens]
    end

    A --> B --> C --> D
    D --> E & F & G
    H -.->|configures| D & E & F & G
    E & F & G --> I --> J --> K --> L

    style INPUT fill:#1a1a2e,stroke:#e94560,color:#fff
    style HOOKS_PRE fill:#16213e,stroke:#0f3460,color:#fff
    style ENGINE fill:#0f3460,stroke:#533483,color:#fff
    style CONFIG fill:#533483,stroke:#e94560,color:#fff
    style HOOKS_POST fill:#16213e,stroke:#0f3460,color:#fff
    style OUTPUT fill:#1a1a2e,stroke:#00d2ff,color:#fff

---

What's Inside

%%{init: {'theme': 'neutral'}}%%
mindmap
  root((cursor-handbook<br/>110 Components))
    Rules — 29
      Architecture — 3
      Backend — 6
      Frontend — 4
      Security — 3
      Database — 3
      Cloud — 3
      Testing — 3
      DevOps — 3
      Core — 1
    Agents — 34
      Architecture — 3
      Backend — 7
      Frontend — 4
      Testing — 4
      Database — 2
      Security — 3
      Cloud — 3
      DevOps — 3
      Business — 2
      AI/ML — 1
      Docs — 1
      Platform — 1
    Skills — 21
      Backend — 4
      Frontend — 2
      Testing — 2
      Database — 3
      Cloud — 3
      DevOps — 4
      Docs — 3
    Commands — 14
    Hooks — 12
    Templates — 9

| Layer | Count | What It Does | How It's Triggered | | ------------- | ----: | ------------------------------------------------- | ----------------------------------- | | Rules | 29 | Enforces coding standards on every AI interaction | Automatically — always on | | Agents | 34 | Specialized assistants for complex tasks | On demand — /agent-name | | Skills | 21 | Step-by-step guided workflows with checklists | Contextually — when patterns match | | Commands | 14 | Lightweight, token-efficient quick actions | On demand — /command | | Hooks | 12 | Automation scripts in the AI loop | Event-driven — before/after actions | | Templates | 9 | Scaffolding for handlers, components, tests, etc. | Referenced by skills and agents |

Note: The 110 component count = Rules + Agents + Skills + Commands + Hooks. Templates (9) are supporting assets referenced by skills and agents.

---

Quick Start (5 minutes)

graph LR
    A["1. Clone"] --> B["2. Setup"] --> C["3. Restart"] --> D["4. Verify"]

    style A fill:#22c55e,stroke:#16a34a,color:#fff,stroke-width:2px
    style B fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:2px
    style C fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px
    style D fill:#8b5cf6,stroke:#7c3aed,color:#fff,stroke-width:2px

One-line install

git clone https://github.com/girijashankarj/cursor-handbook.git .cursor && make -f .cursor/Makefile init

Then edit .cursor/config/project.json and restart Cursor.

Step 1 — Clone

# Into your existing project
git clone https://github.com/girijashankarj/cursor-handbook.git .cursor

Step 2 — Configure

# Option A: One-command setup
make init

# Option B: Interactive generator
./scripts/init-project-config.sh

# Option C: Manual copy
cp .cursor/config/project.json.template .cursor/config/project.json

Edit .cursor/config/project.json — replace placeholders with your project details:

{
	"project": { "name": "my-api", "description": "Order management service" },
	"techStack": {
		"language": "TypeScript",
		"framework": "Express.js",
		"database": "PostgreSQL",
		"testing": "Jest",
		"packageManager": "pnpm"
	},
	"testing": {
		"coverageMinimum": 90,
		"testCommand": "pnpm run test",
		"typeCheckCommand": "pnpm run type-check"
	}
}

Step 3 — Restart Cursor IDE

Close and reopen Cursor. All 110 components are now active.

Step 4 — Verify

Try any of these:

/type-check          → Runs type checking (saves ~90K tokens vs full tests)
/code-reviewer       → AI reviews your code like a senior engineer
/generate-handler    → Scaffolds a complete API handler

Alternative: One-Line Setup

curl -fsSL https://raw.githubusercontent.com/girijashankarj/cursor-handbook/main/scripts/setup-cursor.sh | bash

Alternative: Git Submodule (for teams)

git submodule add https://github.com/girijashankarj/cursor-handbook.git .cursor
make init
# Or: cp .cursor/config/project.json.template .cursor/config/project.json

---

User Flow

Here's what happens at every stage of your development workflow:

sequenceDiagram
    actor Dev as Developer
    participant C as Cursor IDE
    participant H as Hooks
    participant R as Rules (29)
    participant A as Agents/Skills
    participant Code as Codebase

    Dev->>C: Types prompt or command
    C->>H: beforeSubmitPrompt
    H->>H: Enrich with project context
    H->>H: Guard against expensive ops
    H->>R: Pass enriched prompt
    R->>R: Apply 29 always-on rules
    Note over R: Token efficiency<br/>Security guardrails<br/>Code standards<br/>Architecture patterns
    R->>A: Route to agent/skill/command
    A->>Code: Generate or modify code
    Code->>H: afterFileEdit
    H->>H: Post-edit checks
    H->>H: Auto-format
    H->>H: Secret scan
    H-->>Dev: Clean, standards-compliant code

    Note over Dev,Code: Every interaction is governed by your rules.<br/>No exceptions. No token waste.

Typical Workflows

| What You Want | What You Type | What Happens | | -------------------- | -------------------------------- | -------------------------------------------------------------- | | Build a new endpoint | "Create a POST /orders endpoint" | Skill triggers full handler scaffolding (9 files, 7-step flow) | | Review code | /code-reviewer | Agent checks security, performance, correctness, tests | | Fix broken tests | /testing-agent fix these tests | Skill diagnoses failures, fixes mocks, verifies coverage | | Quick validation | /type-check | Runs type check (~10K tokens) instead of full tests (~100K) | | Deploy safely | /deployment-agent | Agent generates deployment checklist with rollback plan