title: "Environment & Project Setup" description: "Configure Cursor optimally — instructions.md, rules, skills, hooks, commands, and monorepo patterns." section: "Full Guide" readTime: "15 min"

Environment & Project Setup

Proper setup gives you 30% faster responses, better context, and fewer hallucinations.

Recommended .cursor/ Directory Layout

.cursor/
├── rules/                      # Always-on constraints (any .md file)
│   ├── typescript.md
│   ├── react-patterns.md
│   └── security.md
├── skills/                     # Optional reusable workflows
│   ├── test-loop/SKILL.md
│   └── scaffold-package/SKILL.md
├── commands/                   # Reusable prompts (/command-name)
│   ├── pr-review.md
│   └── new-feature.md
├── hooks.json                  # Lifecycle hooks
└── mcp.json                    # MCP server config

instructions.md                 # Project context (root — REQUIRED)
AGENTS.md                       # Simple alternative to rules/
.cursorignore                   # Indexing exclusions

.cursorignore by Repo Size

Small (<10k files): Index everything — exclude only noise.

node_modules/
.git/
*.log
dist/
build/

Medium (10k–50k files): Exclude generated code and assets.

node_modules/
dist/
build/
.next/
*.generated.ts
__generated__/
*.mp4
*.jpg
*.png

Large monorepo (50k+ files): Aggressive filtering.

packages/*/node_modules/
!packages/my-package/
dist/
build/
*.generated.ts
coverage/

Check indexed files: Cursor Settings > Indexing & Docs > View included files

The instructions.md File (Most Important)

Create instructions.md in your project root. Reference it in every significant prompt with @instructions.md.

What to include:

# Project Overview
- Name, purpose, tech stack with versions
- Architecture: monorepo/microservices/monolith
 
# Coding Standards
- Language, style (Prettier config)
- Naming conventions, async patterns
 
# Common Patterns
- API response shape: { data, error }
- Error class: AppError
- State: Zustand / Redux
 
# Testing Requirements
- Framework: Vitest, 80% coverage minimum
- Test files: *.test.ts next to source
 
# Anti-Patterns to Avoid
- No `any` without @ts-ignore
- No console.log in production
- No direct DB queries outside repositories
 
# Deployment Process
- CI/CD: GitHub Actions

Usage:

@instructions.md

Implement checkout endpoint for shopping cart.
Follow existing patterns and conventions.

Keep it under 500 lines. Update when patterns change.

Rules Configuration

Any .md file in .cursor/rules/ is loaded as a rule. Control activation via frontmatter:

Example rule (typescript.md):

---
description: "TypeScript best practices and type safety standards"
alwaysApply: false
---
 
# TypeScript Best Practices
 
## Type Safety
- Use strict mode
- Avoid `any` — use `unknown` for truly unknown types
- Prefer interfaces for objects
 
## Error Handling
- Always handle promise rejections
- Return Result types for fallible operations

Write rules as encyclopedia articles, not commands. No "You are a senior engineer…" — write factual standards your team would document internally.

AGENTS.md is a simpler alternative for straightforward projects — just a plain markdown file in the project root. Supports nesting in subdirectories.

Legacy .cursorrules will be deprecated — migrate to .cursor/rules/*.md.

Skills Configuration

Skills are optional workflows that activate when relevant (unlike rules which are always on).

.cursor/skills/
  test-loop/SKILL.md
  scaffold-package/SKILL.md
  api-migration/SKILL.md

Example skill (test-loop/SKILL.md):

---
name: "test-loop"
description: "Run tests, fix failures, iterate until all pass"
commands:
  - "test-loop"
  - "tdd"
---
 
# Test-Fix-Iterate Loop
 
## When to Use
- Implementing TDD workflow
- Fixing failing tests
 
## Workflow
1. Run test suite: `npm test`
2. Analyze failures — identify root cause
3. Apply fix
4. Re-run tests
5. Repeat until all tests pass
 
## Success Criteria
- All tests passing
- Coverage maintained or improved

Activation patterns:

• Slash command: /test-loop
• Automatic: agent recognizes "TDD approach" → activates skill
• Explicit mention: "Use the test-loop skill"

Create skills for multi-step workflows (3+ steps). Don't create skills for single commands.

Hooks Configuration

Hooks control agent lifecycle — enable verification loops so the agent iterates autonomously until a condition is met.

.cursor/hooks.json:

{
  "hooks": {
    "stop": {
      "script": "./scripts/stop-when-tests-pass.sh",
      "description": "Continue iterating until all tests pass"
    }
  }
}

./scripts/stop-when-tests-pass.sh:

#!/bin/bash
# Exit 0 = continue, Exit 1 = stop
npm test --silent
if [ $? -eq 0 ]; then
  echo "All tests passing - stopping"
  exit 1
else
  echo "Tests failing - continuing"
  exit 0
fi

chmod +x scripts/stop-when-tests-pass.sh

Other hook patterns: quality gate (coverage %), build verification, production safety check.

Best practices: Keep hooks under 5 seconds. Use clear exit codes. Test hooks independently.

Commands (Reusable Prompts)

Create .cursor/commands/<name>.md. Invoke with /name.

Example (pr-review.md):

# PR Review Checklist
 
Review the current branch:
 
## Code Quality
- [ ] No hardcoded secrets or API keys
- [ ] Error handling for all async operations
- [ ] No `any` types in TypeScript
 
## Testing
- [ ] Unit tests for new functions (>80% coverage)
- [ ] Integration tests for API endpoints
 
## Security
- [ ] Input validation on all public APIs
- [ ] Auth on protected routes
 
Run tests and generate report.

Monorepo Strategies

Option 1: Open subdirs as separate workspaces — clean separation, focused indexing.

cursor frontend/   # Index React only
cursor backend/    # Index Go only

Option 2: Per-package .cursorignore — exclude sibling packages.

Option 3: Per-package instructions.md — each package has its own context file.

Trade-off: Narrower index = faster, but agent can't cross-reference other packages. Use @web or manual file references for cross-package queries.

MCP Server Config

.cursor/mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Never commit secrets — use .env and add to .gitignore.

Setup Checklist

• instructions.md created with project context
• .cursorignore configured for repo size
• .cursor/rules/*.md with at least 1 rule (or AGENTS.md)
• At least one skill created (e.g., test-loop)
• Hooks configured for verification loops
• At least one command in .cursor/commands/
• Tested Tab autocomplete, Inline Edit (Cmd+K), Agent (Cmd+I)