Live handbook: https://girijashankarj.github.io/cursor-handbook/ The open-source rules engine for Cursor IDE — 117 components (rules, agents, skills, commands, hooks) that turn your AI into a senior engineer who follows your standards, knows your codebase, and never wastes a token. If cursor-handbook helps you, consider giving it a ⭐ — it helps others discover it. - Ways to use - The Problem -
Add this skill
npx mdskills install girijashankarj/cursor-handbookComprehensive Cursor IDE rules engine with 117 components covering standards, workflows, and automation
1<p align="center">2 <img src="https://img.shields.io/github/stars/girijashankarj/cursor-handbook?style=social" alt="GitHub stars" />3 <img src="https://img.shields.io/github/forks/girijashankarj/cursor-handbook?style=social" alt="GitHub forks" />4 <img src="https://img.shields.io/github/last-commit/girijashankarj/cursor-handbook" alt="GitHub last commit" />5 <img src="https://img.shields.io/github/issues/girijashankarj/cursor-handbook" alt="GitHub issues" />6 <img src="https://img.shields.io/badge/license-MIT-green" alt="License MIT" />7 <img src="https://img.shields.io/badge/version-1.4.0-blue" alt="Version" />8 <img src="https://img.shields.io/badge/Components-117-green" alt="117 Components" />9 <img src="https://img.shields.io/badge/Token%20Savings-30%25%2B-green?style=for-the-badge" alt="30%+ Savings" />10</p>1112# cursor-handbook1314🌐 **Live handbook:** [https://girijashankarj.github.io/cursor-handbook/](https://girijashankarj.github.io/cursor-handbook/)1516**The open-source rules engine for Cursor IDE — 117 components (rules, agents, skills, commands, hooks) that turn your AI into a senior engineer who follows your standards, knows your codebase, and never wastes a token.**1718> 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.1920<p align="center">21 <strong>If cursor-handbook helps you, consider giving it a ⭐ — it helps others discover it.</strong>22</p>2324<p align="center">25 <img src="docs/snaps/readme-hero-banner.png" alt="cursor-handbook — Rules engine for Cursor IDE" width="800" />26</p>2728---2930## Table of Contents3132- [Ways to use](#ways-to-use-cursor-handbook)33- [The Problem](#the-problem)34- [Before vs After](#before-vs-after)35- [Who is this for?](#who-is-this-for)36- [How It Works](#how-it-works)37- [Quick Start](#quick-start-5-minutes)38- [Documentation](#documentation)3940---4142## Ways to use cursor-handbook4344Pick the option that fits your workflow:4546| Option | Best for |47|--------|----------|48| **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. |49| **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. |505152| **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. |53| **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. |54| **5. Handbook website** | **Browse** components or read **Guidelines** (Cursor IDE topics) in the browser — **[GitHub Pages](https://girijashankarj.github.io/cursor-handbook/)** (optional; clone, ZIP, and command line still work). |5556**Improvements welcome.** If you want to add or improve rules, skills, hooks, agents, or commands, see [CONTRIBUTING.md](CONTRIBUTING.md) and open an issue or PR.5758> **Forking?** Replace `girijashankarj` with your GitHub org/username in badges, clone URLs, `scripts/setup-cursor.sh`, `.github/CODEOWNERS`, and docs before pushing.5960---6162## The Problem6364Every time you open Cursor IDE, your AI assistant starts from zero. It doesn't know your:6566- Code conventions and architecture patterns67- Security policies (and happily hardcodes your API keys)68- Testing thresholds (and runs the full 100K-token test suite when you just wanted a type check)69- Handler patterns, naming conventions, or folder structure7071You end up repeating yourself, burning tokens, and fixing the same mistakes. **cursor-handbook fixes this permanently.**7273---7475## Before vs After7677| Before cursor-handbook | After cursor-handbook |78|------------------------|------------------------|79| AI hardcodes API keys | Security rules block it |80| AI runs full test suite (~100K tokens) | Uses type-check (~10K) or single-file tests |81| You repeat conventions every session | Rules remember them — always on |82| Inconsistent code across team | One rules engine, one standard |83| No guardrails on expensive ops | Hooks warn or block dangerous commands |8485<p align="center">86 <img src="docs/snaps/before-after-concept.png" alt="Before vs After cursor-handbook" width="700" />87</p>8889---9091## Who is this for?9293| Audience | Benefit |94|----------|---------|95| **Solo developers** | Consistent AI behavior without repeating yourself every session |96| **Teams** | Shared standards; everyone gets the same guardrails and conventions |97| **Enterprises** | Security, compliance, and token efficiency built in from day one |9899<p align="center">100 <img src="docs/snaps/who-uses-this.png" alt="Who uses cursor-handbook" width="700" />101</p>102103---104105## How It Works106107```mermaid108graph TB109 subgraph INPUT ["Your Prompt"]110 A[Developer types a prompt in Cursor]111 end112113 subgraph HOOKS_PRE ["Pre-Processing Hooks"]114 B[context-enrichment.sh<br/>Injects project context]115 C[shell-guard.sh<br/>Blocks dangerous commands]116 end117118 subgraph ENGINE ["cursor-handbook Engine"]119 D[30 Rules<br/>Always-applied standards]120 E[34 Agents<br/>Specialized AI assistants]121 F[22 Skills<br/>Step-by-step workflows]122 G[14 Commands<br/>Quick actions]123 end124125 subgraph CONFIG ["Project Settings"]126 H[project.json<br/>Your project settings]127 end128129 subgraph HOOKS_POST ["Post-Processing Hooks"]130 I[post-edit-check.sh<br/>Validates changes]131 J[auto-format.sh<br/>Formats code]132 K[coverage-check.sh<br/>Verifies thresholds]133 end134135 subgraph OUTPUT ["AI Response"]136 L[Code that follows YOUR standards<br/>with 30%+ fewer tokens]137 end138139 A --> B --> C --> D140 D --> E & F & G141 H -.->|configures| D & E & F & G142 E & F & G --> I --> J --> K --> L143144 style INPUT fill:#1a1a2e,stroke:#e94560,color:#fff145 style HOOKS_PRE fill:#16213e,stroke:#0f3460,color:#fff146 style ENGINE fill:#0f3460,stroke:#533483,color:#fff147 style CONFIG fill:#533483,stroke:#e94560,color:#fff148 style HOOKS_POST fill:#16213e,stroke:#0f3460,color:#fff149 style OUTPUT fill:#1a1a2e,stroke:#00d2ff,color:#fff150```151152---153154## What's Inside155156```mermaid157%%{init: {'theme': 'neutral'}}%%158mindmap159 root((cursor-handbook<br/>117 Components))160 Rules — 30161 Architecture — 3162 Backend — 6163 Frontend — 4164 Security — 3165 Database — 3166 Cloud — 3167 Testing — 3168 DevOps — 3169 Core — 1170 Agents — 34171 Architecture — 3172 Backend — 7173 Frontend — 4174 Testing — 4175 Database — 2176 Security — 3177 Cloud — 3178 DevOps — 3179 Business — 2180 AI/ML — 1181 Docs — 1182 Platform — 1183 Skills — 21184 Backend — 4185 Frontend — 2186 Testing — 2187 Database — 3188 Cloud — 3189 DevOps — 4190 Docs — 3191 Commands — 14192 Hooks — 12193 Templates — 9194```195196| Layer | Count | What It Does | How It's Triggered |197| ------------- | ----: | ------------------------------------------------- | ----------------------------------- |198| **Rules** | 30 | Enforces coding standards on every AI interaction | Automatically — always on |199| **Agents** | 34 | Specialized assistants for complex tasks | On demand — `/agent-name` |200| **Skills** | 22 | Step-by-step guided workflows with checklists | Contextually — when patterns match |201| **Commands** | 14 | Lightweight, token-efficient quick actions | On demand — `/command` |202| **Hooks** | 12 | Automation scripts in the AI loop | Event-driven — before/after actions |203| **Templates** | 9 | Scaffolding for handlers, components, tests, etc. | Referenced by skills and agents |204205> **Note:** The 117 component count = Rules + Agents + Skills + Commands + Hooks. Templates (9) are supporting assets referenced by skills and agents.206207---208209## Quick Start (5 minutes)210211```mermaid212graph LR213 A["1. Clone"] --> B["2. Setup"] --> C["3. Restart"] --> D["4. Verify"]214215 style A fill:#22c55e,stroke:#16a34a,color:#fff,stroke-width:2px216 style B fill:#3b82f6,stroke:#2563eb,color:#fff,stroke-width:2px217 style C fill:#f59e0b,stroke:#d97706,color:#fff,stroke-width:2px218 style D fill:#8b5cf6,stroke:#7c3aed,color:#fff,stroke-width:2px219```220221### One-line install222223```bash224git clone https://github.com/girijashankarj/cursor-handbook.git .cursor && make -f .cursor/Makefile init225```226227Then edit `.cursor/config/project.json` and restart Cursor.228229### Step 1 — Clone230231```bash232# Into your existing project233git clone https://github.com/girijashankarj/cursor-handbook.git .cursor234```235236### Step 2 — Configure237238```bash239# Option A: One-command setup240make init241242# Option B: Interactive generator243./scripts/init-project-config.sh244245# Option C: Manual copy246cp .cursor/config/project.json.template .cursor/config/project.json247```248249Edit `.cursor/config/project.json` — replace placeholders with your project details:250251```json252{253 "project": { "name": "my-api", "description": "Order management service" },254 "techStack": {255 "language": "TypeScript",256 "framework": "Express.js",257 "database": "PostgreSQL",258 "testing": "Jest",259 "packageManager": "pnpm"260 },261 "testing": {262 "coverageMinimum": 90,263 "testCommand": "pnpm run test",264 "typeCheckCommand": "pnpm run type-check"265 }266}267```268269### Step 3 — Restart Cursor IDE270271Close and reopen Cursor. All 117 components are now active.272273### Step 4 — Verify274275Try any of these:276277```278/type-check → Runs type checking (saves ~90K tokens vs full tests)279/code-reviewer → AI reviews your code like a senior engineer280/generate-handler → Scaffolds a complete API handler281```282283### Alternative: One-Line Setup284285```bash286curl -fsSL https://raw.githubusercontent.com/girijashankarj/cursor-handbook/main/scripts/setup-cursor.sh | bash287```288289### Alternative: Git Submodule (for teams)290291```bash292git submodule add https://github.com/girijashankarj/cursor-handbook.git .cursor293make init294# Or: cp .cursor/config/project.json.template .cursor/config/project.json295```296297---298299## User Flow300301Here's what happens at every stage of your development workflow:302303```mermaid304sequenceDiagram305 actor Dev as Developer306 participant C as Cursor IDE307 participant H as Hooks308 participant R as Rules (30)309 participant A as Agents/Skills310 participant Code as Codebase311312 Dev->>C: Types prompt or command313 C->>H: beforeSubmitPrompt314 H->>H: Enrich with project context315 H->>H: Guard against expensive ops316 H->>R: Pass enriched prompt317 R->>R: Apply 30 always-on rules318 Note over R: Token efficiency<br/>Security guardrails<br/>Code standards<br/>Architecture patterns319 R->>A: Route to agent/skill/command320 A->>Code: Generate or modify code321 Code->>H: afterFileEdit322 H->>H: Post-edit checks323 H->>H: Auto-format324 H->>H: Secret scan325 H-->>Dev: Clean, standards-compliant code326327 Note over Dev,Code: Every interaction is governed by your rules.<br/>No exceptions. No token waste.328```329330### Typical Workflows331332| What You Want | What You Type | What Happens |333| -------------------- | -------------------------------- | -------------------------------------------------------------- |334| Build a new endpoint | "Create a POST /orders endpoint" | Skill triggers full handler scaffolding (9 files, 7-step flow) |335| Review code | `/code-reviewer` | Agent checks security, performance, correctness, tests |336| Fix broken tests | `/testing-agent fix these tests` | Skill diagnoses failures, fixes mocks, verifies coverage |337| Quick validation | `/type-check` | Runs type check (~10K tokens) instead of full tests (~100K) |338| Deploy safely | `/deployment-agent` | Agent generates deployment checklist with rollback plan |339| Optimize a query | `/query-opt-agent` | Agent runs EXPLAIN ANALYZE, rewrites query, adds indexes |340341---342343## Processing Pipeline344345Every prompt flows through a layered processing pipeline that ensures quality, security, and efficiency:346347```mermaid348graph TD349 subgraph L1 ["Layer 1: Pre-Processing"]350 direction LR351 A1[Context Enrichment] --> A2[Shell Guard] --> A3[Pre-Commit Check]352 end353354 subgraph L2 ["Layer 2: Rules Engine — Always Active"]355 direction LR356 B1[Token Efficiency] --> B2[Security Guardrails] --> B3[Code Standards]357 B3 --> B4[Architecture] --> B5[Testing Standards]358 end359360 subgraph L3 ["Layer 3: Specialized Processing"]361 direction LR362 C1[Agents<br/>Complex tasks]363 C2[Skills<br/>Guided workflows]364 C3[Commands<br/>Quick actions]365 end366367 subgraph L4 ["Layer 4: Post-Processing"]368 direction LR369 D1[Edit Validation] --> D2[Auto-Format] --> D3[Coverage Check]370 end371372 L1 --> L2 --> L3 --> L4373374 style L1 fill:#1e293b,stroke:#475569,color:#fff375 style L2 fill:#0c4a6e,stroke:#0284c7,color:#fff376 style L3 fill:#3730a3,stroke:#6366f1,color:#fff377 style L4 fill:#1e293b,stroke:#475569,color:#fff378```379380### Layer Breakdown381382**Layer 1 — Pre-Processing (Hooks)**383Before your prompt even reaches the AI, hooks inject your project context, block dangerous shell commands, and validate git operations.384385**Layer 2 — Rules Engine (30 Rules, Always Active)**386Every AI response is shaped by your rules. These aren't suggestions — they're hard constraints:387388| Rule Category | What It Enforces |389| ----------------- | ----------------------------------------------------------- |390| Token Efficiency | No auto-running full tests/lint; confirm 50K+ ops |391| Security | No hardcoded secrets; no PII in logs; parameterized queries |392| Architecture | Handler pattern; dependency direction; error hierarchy |393| Code Organization | Naming conventions; import order; folder structure |394| Database | Soft delete only; required columns; migration safety |395| Testing | 90%+ coverage; mock patterns; AAA pattern |396397**Layer 3 — Specialized Processing**398Based on your prompt, the right component activates: an agent for complex tasks, a skill for guided workflows, or a command for quick operations.399400**Layer 4 — Post-Processing (Hooks)**401After code is generated, hooks validate the output, auto-format files, scan for leaked secrets, and verify test coverage.402403---404405## Token Savings406407cursor-handbook is engineered to cut your AI token costs by 30% or more:408409```mermaid410pie title Token Usage Comparison (per operation)411 "Type Check (cursor-handbook)" : 10412 "Saved vs Full Tests" : 90413```414415| Without cursor-handbook | With cursor-handbook | Tokens Saved |416| ------------------------------- | -------------------------------------- | -------------- |417| Full test suite: ~100K tokens | `/type-check`: ~10K tokens | **~90K (90%)** |418| Full lint run: ~50K tokens | `/lint-check` (read_lints): ~2K tokens | **~48K (96%)** |419| Full test suite: ~100K tokens | `/test-single`: ~5K tokens | **~95K (95%)** |420| Unfiltered context: ~30K tokens | Context layering: ~10K tokens | **~20K (67%)** |421| Verbose AI output: ~15K tokens | Concise guidelines: ~5K tokens | **~10K (67%)** |422423**Conservative estimate**: A developer making 50 AI interactions/day saves **~200K tokens/day** — that's real money at scale.424425---426427## Customization428429cursor-handbook is 100% project-driven. Every component adapts to your project through a single file:430431### How It Adapts to Your Project432433```mermaid434graph TB435 PJ["project.json<br/>Your Configuration"]436437 PJ --> R["Rules<br/>{{CONFIG.techStack.language}}<br/>{{CONFIG.testing.coverageMinimum}}"]438 PJ --> A["Agents<br/>{{CONFIG.techStack.framework}}<br/>{{CONFIG.paths.handlerBasePath}}"]439 PJ --> S["Skills<br/>{{CONFIG.patterns.handlerFlow}}<br/>{{CONFIG.fileNames.handlerEntry}}"]440 PJ --> CMD["Commands<br/>{{CONFIG.testing.testCommand}}<br/>{{CONFIG.testing.typeCheckCommand}}"]441 PJ --> H["Hooks<br/>{{CONFIG.project.name}}<br/>{{CONFIG.database.softDeleteField}}"]442443 style PJ fill:#f59e0b,stroke:#d97706,color:#000,stroke-width:3px444 style R fill:#3b82f6,stroke:#2563eb,color:#fff445 style A fill:#8b5cf6,stroke:#7c3aed,color:#fff446 style S fill:#22c55e,stroke:#16a34a,color:#fff447 style CMD fill:#ef4444,stroke:#dc2626,color:#fff448 style H fill:#06b6d4,stroke:#0891b2,color:#fff449```450451### What You Can Customize452453| Section | What It Controls | Example |454| ------------- | -------------------------- | ---------------------------------------------- |455| `project` | Project identity | Name, description, repo URL |456| `techStack` | Language, framework, tools | TypeScript + Express or Python + FastAPI |457| `paths` | Directory structure | Where handlers, services, and common code live |458| `domain` | Business entities | Order, Product, Customer + lifecycle states |459| `patterns` | Code patterns | 7-step handler flow, error handling strategy |460| `testing` | Quality gates | 90% coverage, test/lint/type-check commands |461| `database` | DB conventions | Soft delete field, timestamp columns, naming |462| `packages` | Internal packages | `@your-org` scope, registry URL |463| `conventions` | Git and workflow | Branch prefixes, commit format, PR templates |464465### Ready-Made Stack Presets466467Don't start from scratch — pick your stack:468469| Stack | File | Language | Framework |470| ------------------ | -------------------------------------------------------------- | ---------- | ----------- |471| TypeScript/Express | [`examples/typescript-express/`](examples/typescript-express/) | TypeScript | Express.js |472| TypeScript/NestJS | [`examples/typescript-nest/`](examples/typescript-nest/) | TypeScript | NestJS |473| Python/FastAPI | [`examples/python-fastapi/`](examples/python-fastapi/) | Python | FastAPI |474| Go/Chi | [`examples/go-chi/`](examples/go-chi/) | Go | Chi |475| React SPA | [`examples/react/`](examples/react/) | TypeScript | React |476| Next.js | [`examples/nextjs/`](examples/nextjs/) | TypeScript | Next.js |477| Rust/Actix | [`examples/rust-actix/`](examples/rust-actix/) | Rust | Actix Web |478| Kotlin/Spring | [`examples/kotlin-spring/`](examples/kotlin-spring/) | Kotlin | Spring Boot |479| Flutter | [`examples/flutter/`](examples/flutter/) | Dart | Flutter |480481```bash482# Use a pre-made preset483cp examples/typescript-express/project.json .cursor/config/project.json484# Then customize with your project specifics485```486487---488489## Component Deep Dive490491### Rules (30) — Your AI's Permanent Memory492493Rules are the backbone. They load on every interaction, every time, with zero effort.494495```mermaid496graph LR497 subgraph MAIN ["Core"]498 M[main-rules]499 end500501 subgraph ARCH ["Architecture"]502 A1[token-efficiency]503 A2[core-principles]504 A3[dependency-mgmt]505 end506507 subgraph BE ["Backend"]508 B1[handler-patterns]509 B2[code-organization]510 B3[error-handling]511 B4[api-design]512 B5[typescript]513 B6[nodejs]514 end515516 subgraph FE ["Frontend"]517 F1[components]518 F2[accessibility]519 F3[state-mgmt]520 F4[performance]521 end522523 subgraph SEC ["Security"]524 S1[guardrails]525 S2[secrets]526 S3[compliance]527 end528529 subgraph DB ["Database"]530 D1[query-patterns]531 D2[schema-design]532 D3[migrations]533 end534535 subgraph CLD ["Cloud"]536 C1[infrastructure]537 C2[serverless]538 C3[containers]539 end540541 subgraph TST ["Testing"]542 T1[standards]543 T2[mocks]544 T3[integration]545 end546547 subgraph OPS ["DevOps"]548 O1[ci-cd]549 O2[monitoring]550 O3[documentation]551 end552553 M --> ARCH & BE & FE & SEC & DB & CLD & TST & OPS554```555556### Agents (34) — Your On-Demand Specialists557558| Domain | Agent | Invocation | Best For |559| ---------------- | -------------------- | ----------------------- | --------------------------------- |560| **Architecture** | Design Agent | `/design-agent` | System design, trade-off analysis |561| | Refactoring Agent | `/refactoring-agent` | Safe incremental refactoring |562| | Migration Agent | `/migration-agent` | Framework upgrades, migrations |563| **Backend** | Code Reviewer | `/code-reviewer` | PR reviews, security checks |564| | Implementation Agent | `/implementation-agent` | Building features end-to-end |565| | Debugging Agent | `/debugging-agent` | Root cause analysis |566| | API Agent | `/api-agent` | REST API design |567| | Performance Agent | `/performance-agent` | Bottleneck identification |568| | Database Agent | `/database-agent` | Schema design, queries |569| | Event Handler Agent | `/event-handler-agent` | Async event processing |570| **Frontend** | UI Component Agent | `/ui-component-agent` | Accessible components |571| | State Agent | `/state-agent` | State management decisions |572| | Styling Agent | `/styling-agent` | CSS architecture, theming |573| | Frontend Perf Agent | `/frontend-perf-agent` | Core Web Vitals optimization |574| **Testing** | Testing Agent | `/testing-agent` | Write comprehensive tests |575| | E2E Agent | `/e2e-agent` | End-to-end test flows |576| | Load Test Agent | `/load-test-agent` | Performance benchmarking |577| | Security Test Agent | `/security-test-agent` | Vulnerability scanning |578| **Database** | Schema Agent | `/schema-agent` | Schema design, ER diagrams |579| | Query Opt Agent | `/query-opt-agent` | Query performance tuning |580| **Security** | Security Audit Agent | `/security-audit-agent` | Comprehensive security audit |581| | Auth Agent | `/auth-agent` | Auth flows, RBAC |582| | Compliance Agent | `/compliance-agent` | GDPR, SOC 2, HIPAA |583| **Cloud** | Infra Agent | `/infra-agent` | IaC, cloud architecture |584| | Deployment Agent | `/deployment-agent` | Zero-downtime deployments |585| | Cost Agent | `/cost-agent` | Cloud cost optimization |586| **DevOps** | CI/CD Agent | `/ci-cd-agent` | Pipeline design |587| | Monitoring Agent | `/monitoring-agent` | Observability setup |588| | Incident Agent | `/incident-agent` | Incident response |589| **Business** | Requirements Agent | `/requirements-agent` | User stories, specs |590| | Estimation Agent | `/estimation-agent` | Effort estimation |591| **AI/ML** | Prompt Agent | `/prompt-agent` | Prompt engineering |592| **Docs** | Docs Agent | `/docs-agent` | Technical documentation |593| **Platform** | DX Agent | `/dx-agent` | Developer experience |594595### Commands (17) — Token-Efficient Quick Actions596597```mermaid598graph LR599 TC["/type-check<br/>~10K tokens"] ---|saves 90K vs| FT["Full Tests<br/>~100K tokens"]600 TS["/test-single<br/>~5K tokens"] ---|saves 95K vs| FT601 LC["/lint-check<br/>~2K tokens"] ---|saves 48K vs| FL["Full Lint<br/>~50K tokens"]602603 style TC fill:#22c55e,stroke:#16a34a,color:#fff604 style TS fill:#22c55e,stroke:#16a34a,color:#fff605 style LC fill:#22c55e,stroke:#16a34a,color:#fff606 style FT fill:#ef4444,stroke:#dc2626,color:#fff607 style FL fill:#ef4444,stroke:#dc2626,color:#fff608```609610| Command | What It Does | Why It's Better |611| ------------------- | -------------------------- | --------------------------------- |612| `/type-check` | TypeScript type validation | 10K tokens vs 100K for full tests |613| `/lint-check` | Use `read_lints` tool | 2K tokens vs 50K for full lint |614| `/lint-fix` | Auto-fix lint issues | One-step lint resolution |615| `/format` | Format code files | Consistent formatting |616| `/generate-handler` | Scaffold API handler | Full 9-file handler in seconds |617| `/test-single` | Test one file only | 5K tokens vs 100K for full suite |618| `/test-coverage` | Coverage report | Targeted coverage analysis |619| `/coverage` | Quick coverage check | Fast coverage snapshot |620| `/build` | Build the project | Validated production build |621| `/deploy` | Deploy the application | Guided deployment flow |622| `/docker-build` | Build Docker image | Correct multi-stage build |623| `/audit-deps` | Vulnerability scan | Catch CVEs before shipping |624| `/audit` | Full security audit | Comprehensive security check |625| `/check-secrets` | Secret detection | Find leaked keys before commit |626627---628629## Sharing & Team Adoption630631cursor-handbook is designed to scale from solo developer to enterprise teams:632633```mermaid634graph TD635 subgraph SOLO ["Solo Developer"]636 S1[Clone cursor-handbook<br/>into .cursor/]637 S2[Customize project.json]638 S3[Commit to your project]639 end640641 subgraph TEAM ["Team Sharing"]642 T1[Fork cursor-handbook]643 T2[Add team-specific rules]644 T3[Share as Git submodule<br/>in all team repos]645 end646647 subgraph ORG ["Organization-Wide"]648 O1[Maintain internal fork]649 O2[Add org standards<br/>& compliance rules]650 O3[Distribute via<br/>internal package registry]651 end652653 subgraph OSS ["Open Source"]654 OS1[Contribute rules & agents<br/>back to cursor-handbook]655 OS2[Share stack-specific<br/>examples]656 OS3[Build community<br/>components]657 end658659 SOLO --> TEAM --> ORG660 SOLO --> OSS661 TEAM --> OSS662663 style SOLO fill:#22c55e,stroke:#16a34a,color:#fff664 style TEAM fill:#3b82f6,stroke:#2563eb,color:#fff665 style ORG fill:#8b5cf6,stroke:#7c3aed,color:#fff666 style OSS fill:#f59e0b,stroke:#d97706,color:#000667```668669### Adoption Hierarchy670671| Level | Method | Best For |672| ---------------- | ------------------------------------- | ---------------------------------- |673| **Personal** | Clone directly into `.cursor/` | Solo developers, personal projects |674| **Team** | Git submodule in shared repos | Small teams (2-10 developers) |675| **Organization** | Internal fork with org-specific rules | Companies with coding standards |676| **Community** | PR contributions to this repo | Open source stack-specific configs |677678### Team Setup (Git Submodule)679680```bash681# One team member sets it up682git submodule add https://github.com/your-org/cursor-handbook.git .cursor683git commit -m "feat: add cursor-handbook for team standards"684git push685686# Every other team member gets it automatically687git pull688git submodule update --init689make init690691# Update across the team692cd .cursor && git pull origin main && cd ..693git add .cursor && git commit -m "chore: update cursor-handbook"694```695696### Organization Fork Strategy697698```bash699# 1. Fork cursor-handbook to your org700# 2. Add org-specific rules701# 3. All teams use the org fork as their submodule702git submodule add https://github.com/girijashankarj/cursor-handbook.git .cursor703```704705---706707## Project Structure708709```710cursor-handbook/711├── .cursor/712│ ├── config/ # project.json, schema, templates713│ │ ├── project.json.template # Template (start here)714│ │ ├── project.json.example # Complete example715│ │ └── project-schema.json # JSON Schema validation716│ ├── rules/ # 30 always-applied rules717│ │ ├── main-rules.mdc # Master rules718│ │ ├── architecture/ # 3 architecture rules719│ │ ├── backend/ # 6 backend rules720│ │ ├── frontend/ # 4 frontend rules721│ │ ├── security/ # 3 security rules722│ │ ├── database/ # 3 database rules723│ │ ├── cloud/ # 3 cloud rules724│ │ ├── testing/ # 3 testing rules725│ │ └── devops/ # 3 devops rules726│ ├── agents/ # 34 specialized AI agents727│ │ ├── architecture/ # 3 agents728│ │ ├── backend/ # 7 agents729│ │ ├── frontend/ # 4 agents730│ │ ├── testing/ # 4 agents731│ │ ├── database/ # 2 agents732│ │ ├── security/ # 3 agents733│ │ ├── cloud/ # 3 agents734│ │ ├── devops/ # 3 agents735│ │ ├── business/ # 2 agents736│ │ ├── ai-ml/ # 1 agent737│ │ ├── documentation/ # 1 agent738│ │ └── platform/ # 1 agent739│ ├── skills/ # 22 guided workflows740│ ├── commands/ # 14 quick actions741│ ├── hooks/ # 12 automation scripts742│ ├── templates/ # 9 code templates743│ └── settings/ # IDE settings744├── docs/ # Full documentation745│ ├── getting-started/ # Quick start & setup746│ ├── components/ # Component guides747│ ├── guides/ # Best practices748│ ├── security/ # Security guide749│ └── reference/ # Schema & reference750├── examples/ # 9 stack-specific presets751├── scripts/ # Setup scripts752├── .cursorignore # AI context exclusions753├── AGENTS.md # Agent instructions754├── CLAUDE.md # Claude-specific instructions755├── CONTRIBUTING.md # Contribution guide756├── COMPONENT_INDEX.md # Full component reference757├── LICENSE # MIT License758└── README.md # You are here759```760761---762763## Why You Should Use This764765### For Individual Developers766767- **Save money** — 30%+ reduction in token costs adds up fast768- **Save time** — Stop repeating your standards every session769- **Better code** — AI follows your patterns, not random internet patterns770- **Security by default** — Guardrails prevent accidental secret leaks771- **Instant scaffolding** — Full handler/component in seconds, not minutes772773### For Teams774775- **Consistency** — Every developer gets the same AI behavior776- **Onboarding** — New team members get productive on day one777- **Standards enforcement** — Rules apply automatically, no code review friction778- **Institutional knowledge** — Your patterns are codified, not tribal knowledge779- **Cost control** — Token savings compound across the whole team780781### For Organizations782783- **Compliance** — Security and data handling rules are always enforced784- **Scalability** — Same standards across 10 projects or 1,000785- **Governance** — Central control over AI behavior across all teams786- **ROI** — Measurable token savings and developer time savings787- **Risk reduction** — No more hardcoded secrets or PII in logs788789### By The Numbers790791| Metric | Value |792| --------------------------- | ------------------ |793| Components | 117 |794| Supported tech stacks | 9 |795| Token savings per operation | 67-96% |796| Setup time | ~5 minutes |797| Files to customize | 1 (`project.json`) |798| Lines to edit | ~50 |799| Price | Free (MIT License) |800801---802803## Contributing804805We welcome contributions. Whether it's a new rule for a framework we don't cover, a new agent for a workflow you've mastered, or a bug fix — every contribution helps the community.806807See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.808809```mermaid810graph LR811 A[Fork] --> B[Branch] --> C[Build] --> D[Test in Cursor] --> E[PR]812813 style A fill:#22c55e,stroke:#16a34a,color:#fff814 style B fill:#3b82f6,stroke:#2563eb,color:#fff815 style C fill:#8b5cf6,stroke:#7c3aed,color:#fff816 style D fill:#f59e0b,stroke:#d97706,color:#000817 style E fill:#ef4444,stroke:#dc2626,color:#fff818```819820**High-impact areas for contribution:**821822- New stack-specific examples (Vue, Django, Rails, Spring, etc.)823- Specialized agents for niche domains (ML pipelines, game dev, embedded)824- Translations of documentation825- Performance benchmarks and case studies826827---828829## Documentation830831| Document | Description |832| ------------------------------------------------------------- | ------------------------------------ |833| [Architecture](ARCHITECTURE.md) | System design, data flow, extension points |834| [Quick Start](docs/getting-started/quick-start.md) | Get running in 5 minutes |835| [Project Setup](docs/getting-started/configuration.md) | Customize rules to your stack |836| [Component Overview](docs/components/overview.md) | How components work together |837| [Component readiness](docs/component-readiness.md) | Production-ready, generic components list |838| [Best Practices](docs/guides/best-practices.md) | Get the most out of cursor-handbook |839| [Cursor usage](docs/guides/cursor-usage.md) | Token usage, agent review, BugBot setup |840| [Claude IDE support](docs/guides/claude-ide-support.md) | Use with Claude Code and other IDEs |841| [Security Guide](docs/security/security-guide.md) | Security features and policies |842| [Schema Reference](docs/reference/configuration-reference.md) | Full `project.json` schema |843| [Component Index](COMPONENT_INDEX.md) | Complete list of all 117 components |844| [Handbook website](https://girijashankarj.github.io/cursor-handbook/) | **Browse** (components) and **Guidelines** (Cursor IDE topics); search; copy paths (GitHub Pages) |845| [Cursor guidelines](docs/cursor-guidelines/README.md) | Settings, rules, skills, agents, hooks, token efficiency, security, MCP, comparisons, workflow examples |846| [Non-technical guide](docs/getting-started/non-technical.md) | Using cursor-handbook without writing code |847| [SDLC role map](docs/reference/sdlc-role-map.md) | Components by role (PM, QA, DevOps, …) |848| [Contributing](CONTRIBUTING.md) | How to contribute |849| [Contribution Examples](docs/guides/contribution-examples.md) | Concrete examples of adding components |850851**Handbook website (GitHub Pages):** [girijashankarj.github.io/cursor-handbook](https://girijashankarj.github.io/cursor-handbook/) is built from `main` by [`.github/workflows/pages.yml`](.github/workflows/pages.yml). In the repository **Settings → Pages**, set **Source** to **GitHub Actions** once so deployments appear.852853---854855## License856857[MIT License](LICENSE) — use freely in personal and commercial projects. No attribution required (but appreciated).858859---860861<p align="center">862 <strong>Stop teaching your AI the same things twice.</strong><br/>863 Clone cursor-handbook, set your project once, and let 117 components work for you — every prompt, every project, every day.864</p>865866<p align="center">867 <a href="#quick-start-5-minutes">Get Started</a> • 868 <a href="COMPONENT_INDEX.md">Browse Components</a> • 869 <a href="CONTRIBUTING.md">Contribute</a> • 870 <a href="docs/getting-started/quick-start.md">Documentation</a>871</p>872
Full transparency — inspect the skill content before installing.