cursor-desktop-guide

# Cursor Desktop Guide

## Context Architecture

Understand the priority of context loading to effectively manage the agent's knowledge:

1. **Team Rules** (Highest priority)
2. **Project Rules** (`.cursor/rules/`)
3. **User Rules** (Cursor Settings)
4. **AGENTS.md** (Project root and subdirectories)
5. **Skills** (Automatically discovered)

## Core Components

### AGENTS.md

- **Purpose**: Global instructions and context for the project.
- **Best Practice**: Keep compact (<100 lines). Use nested `AGENTS.md` for subdirectories.
- **Location**: Project root (`AGENTS.md`) or subdirectories (e.g., `projects/foo/AGENTS.md`).

### Project Rules (`.cursor/rules/`)

- **Purpose**: Specific, versioned rules.
- **Format**: `.md` or `.mdc` (with YAML frontmatter).
- **Types**:
  - **Always Apply**: `alwaysApply: true`
  - **Apply Intelligently**: `alwaysApply: false` (Agent decides based on description)
  - **Apply to Specific Files**: `globs: ["pattern"]`
  - **Apply Manually**: `@rule-name` mention

### Skills (`.cursor/skills/`)

- **Purpose**: Portable, versioned packages for domain-specific workflows.
- **Structure**: Directory with `SKILL.md`, `scripts/`, `assets/`, `references/`.
- **Usage**: Multi-step workflows requiring resources or scripts.

### Commands (`.cursor/commands/`)

- **Purpose**: One-off actions triggered by `/command` in chat.
- **Format**: Simple Markdown files.

### Subagents

- **Purpose**: Isolated AI assistants for heavy tasks or parallel execution.
- **Usage**: Use `Task` tool.
- **When to use**: Context isolation needed, parallel work, or specialized long-running tasks.
- **Cost**: Each subagent has its own context window (token overhead).

### MCP Servers & Integrations

- **Local**: Use MCP for stateful connections (e.g., Slack) or CLI tools via `Shell` for request-response (e.g., Jira, GitLab).
- **Cloud Agents**: Not used in this system (require remote repo).

### Hooks (`.cursor/hooks.json`)

- **Purpose**: Scripts triggered on agent events (e.g., `preToolUse`, `afterFileEdit`).
- **Types**: Command-based (shell script) or Prompt-based (LLM evaluation).

## Best Practices

1. **AGENTS.md** is the entry point, not an encyclopedia.
2. Use **Rules** with globs for file formats (e.g., ADRs).
3. Use **Skills** for complex workflows (reviews, reports).
4. Use **Commands** for simple rituals (`/morning`).
5. Use **Subagents** only when context isolation is strictly necessary.
6. Use **`.cursorignore`** to exclude archives and cache from Semantic Search.
7. Use **Max Mode** (1M tokens) for heavy workflows.

## References

- Full documentation: [references/REFERENCE.md](references/REFERENCE.md)
- Online up-to-date documentation: [https://www.cursor.com/docs](https://www.cursor.com/docs)