Skip to main content

Cursor Integration

Cursor is the most popular AI-first IDE. vybdocs integrates with Cursor through two mechanisms: a pre-commit hook that runs vyb check --staged before every commit, and CI enforcement on pull requests.

How Cursor + vybdocs works​

When a developer writes code with Cursor's AI (Composer, inline edit, or chat), the AI generates code according to its training — not your team's standards. vybdocs intercepts at the commit boundary:

Developer prompts Cursor AI
          │
          ▼
Cursor generates code changes
          │
          ▼
Developer commits (git commit)
          │
          ▼
Pre-commit hook: vyb check --staged
          │
    ┌─────┴──────┐
  PASS          FAIL
    │              │
  commit       Violations shown,
  proceeds     commit aborted

The developer sees violations in their terminal immediately, before the commit lands. They fix the AI-generated code and commit again.

Setting up the pre-commit hook​

Automatic setup​

vyb init --with-hooks

This writes .git/hooks/pre-commit automatically.

Manual setup​

.git/hooks/pre-commit
#!/bin/sh
npx @vybdocs/vyb check --staged

Make it executable:

chmod +x .git/hooks/pre-commit

Team-wide hooks with Husky​

For consistent hooks across the team, use Husky:

npm install --save-dev husky
npx husky install
npx husky add .husky/pre-commit "vyb check --staged"

Add to package.json:

{
  "scripts": {
    "prepare": "husky install"
  }
}

Now every developer who runs npm install automatically gets the pre-commit hook.

Cursor-specific patterns to enforce​

Some Cursor AI behaviors benefit from specific rule patterns. Common Cursor-generated code issues:

Cursor uses any type excessively​

- id: ts-001
  name: no-explicit-any
  description: >
    Cursor AI frequently defaults to 'any' type to make code
    compile quickly. Require explicit types.
  severity: warn
  pattern: ":\\s*any\\b|as any"
  exclude:
    - "**/*.d.ts"
    - "**/generated/**"
  remediation: >
    Replace 'any' with the actual type. Use 'unknown' if the
    type is genuinely not known at compile time, then narrow
    it with type guards.

Cursor suggests console.log for debugging​

- id: be-001
  name: no-console-log
  severity: warn
  pattern: "console\\.log\\("
  exclude: ["**/*.test.ts"]
  remediation: Use the project logger at src/lib/logger.ts

Cursor uses older React patterns​

- id: fe-002
  name: no-class-components
  severity: info
  pattern: "class\\s+\\w+\\s+extends\\s+(React\\.)?Component"
  exclude: ["**/ErrorBoundary*"]
  remediation: Rewrite as a functional component with hooks.

Cursor rules file (.cursorrules)​

You can also guide Cursor's AI directly by adding a .cursorrules file to your project root. While this doesn't enforce constraints, it steers Cursor toward compliant patterns before the code is even written — reducing violation frequency:

.cursorrules
# Engineering standards for this project — vybdocs enforced

## Tech stack
- TypeScript + Next.js 14 (App Router)
- Postgres with Prisma ORM
- Zod for all runtime validation
- date-fns for date manipulation (not moment.js)
- TailwindCSS for styling (no CSS-in-JS)
- Our logger at src/lib/logger.ts (not console.log)

## Rules
- Never use eval() or Function() constructor
- Never hardcode secrets — use process.env.*
- Use React hooks and functional components (not class components)
- Use useRef() for DOM access (not document.getElementById)
- All API routes must validate input with Zod before processing
- All imports must be named exports (not default)

## This project runs vyb check before every commit.
## Code that violates the above will be blocked.

The .cursorrules file and the .vyb/spec.yaml are complementary: .cursorrules guides the AI's output, spec.yaml enforces compliance regardless of what the AI produces.

Viewing violations in Cursor​

When vyb check --staged fails the pre-commit hook, the output appears in the Cursor terminal:

vyb check --staged  v1.0.0
───────────────────────────────────────────────
  [BLOCK]  sec-001 / no-eval
           src/utils/sandbox.ts:14
           const result = eval(expression)
           → Use a safe expression evaluator library.

  FAIL  (1 block)
───────────────────────────────────────────────
husky - pre-commit hook exited with code 1 (error)

Cursor displays this in its integrated terminal. The developer fixes the violation, stages the fix, and commits again.

Next: GitHub Copilot Integration