Cursor AI complete guide

What you'll learn

This guide shows how to set up Cursor, choose the right working surface, write current Project Rules, control scope, review changes that are written to disk, and validate the result. It also explains what codebase context, Privacy Mode, and .cursorignore do—and what they do not do.

Last verified: August 14, 2026. The workflow and factual claims below were checked against Cursor's current official quickstart, Rules, Agent, Plan Mode, Agent Security, Agents Window, ignore-file, models-and-pricing, and data-use documentation.

Who this is for

• Developers moving from a traditional editor to an agent-assisted workflow
• Cursor users still following old .cursorrules or Composer tutorials
• Teams that want repeatable review, testing, and rollback habits
• Maintainers deciding what an agent may read, edit, or run

You do not need to hand over an entire feature on day one. Start with one small, reversible task in a version-controlled repository.

What Cursor is now

Cursor has a VS Code-based Editor and a separate Agents Window. The Editor is the familiar IDE surface with files, terminals, extensions, and flexible splits. The Agents Window is designed for managing agent work across projects. You can move between them; do not assume the whole product is identical to VS Code or that every extension behaves exactly the same.

The important working surfaces are:

• Tab for autocomplete suggestions while you type
• Inline Edit for a targeted change at the cursor or within a selection
• Agent for repository search, multi-file edits, commands, and longer tasks
• Plan Mode for researching and reviewing an implementation plan before building

Cursor's official quickstart opens Agent with Cmd/Ctrl+I. Inline Edit uses Cmd/Ctrl+K. Plan Mode is available from the mode picker or with Shift+Tab. Keybindings can be remapped, so the current UI is the final source of truth.

The safety model to understand first

Agent can read and search project files, edit files, and use tools. Cursor's current security documentation says workspace file changes can be written without an approval prompt and saved immediately, except for protected configuration-file cases. By default, terminal commands require approval, but settings can change that behavior.

That means the diff is a review surface, not a guaranteed gate in front of every edit. Keep the repository under Git, watch what Agent changes, stop it if the scope drifts, and run the project's real checks before keeping the result. Cursor checkpoints can restore Agent changes, but Cursor explicitly says checkpoints are not version control.

If a development server auto-reloads, a file edit may execute before you finish reviewing it. Use a disposable local environment for risky migrations, scripts, or generated configuration.

Setup from zero

1. Install and choose the working surface

Download Cursor from the official download page and complete onboarding. If you import VS Code settings or extensions, verify the extensions your work depends on. Use the classic Editor when you want the IDE and VS Code extensions; use the Agents Window when managing agent-heavy work is the main task.

2. Start from a known Git state

Before asking Agent to edit anything, inspect the repository:

git status --short

Understand any existing changes so you do not overwrite or misattribute them. Create a normal Git commit or branch according to your team's workflow before a risky change. A clean checkpoint makes review and recovery much easier.

3. Keep secrets out of reach

Keep secrets outside the repository when possible. Add sensitive paths and irrelevant generated trees to a root .cursorignore file:

.env
.env.*
*.pem
secrets/
coverage/
dist/

Cursor documents that .cursorignore blocks indexed and direct AI access for Agent, Tab, Inline Edit, and file references. It is not a complete security boundary: terminal and MCP tools can still access ignored paths, and the documentation warns that complete protection is not guaranteed. Restrict tool permissions and never rely on an ignore file as the only secret control.

4. Create current Project Rules

Do not teach a new project to start with .cursorrules; Cursor lists that as a legacy format. Create a Project Rule with /create-rule in Agent or Customize → Rules → Add Rule. Project Rules live in .cursor/rules/*.mdc and include frontmatter that controls when they apply.

A focused file-scoped rule can look like this:

---
description: Next.js App Router component conventions
globs: src/app/**/*.tsx
alwaysApply: false
---

- Inspect neighboring components before adding a new pattern.
- Prefer Server Components unless browser state or APIs require a client boundary.
- Reuse the project's existing validation and styling utilities.
- Run the repository's real lint and type-check commands after edits.
- Never place credentials or private keys in source code.

Cursor exposes four application choices: Always Apply, Apply Intelligently, Apply to Specific Files, and Apply Manually. Pick the narrowest option that matches the instruction. If you only need simple Markdown instructions, a root or nested AGENTS.md is the lighter alternative.

Rules should document stable project decisions, not replace linters, tests, or repository examples. Cursor's current Rules FAQ also says rules do not control Cursor Tab.

A safe first Agent workflow

Step 1 — ask for orientation

Open Agent and ask it to locate the actual architecture before proposing a change:

Explain this repository's main entry points and the request flow for the
contact form. Identify the existing validation, API, error, and test patterns.
Do not edit files yet.

Agent searches and retrieves relevant files. It does not place the entire repository into every model request. Context remains finite, so reference known-relevant files and correct a missed dependency before asking for implementation.

Step 2 — use Plan Mode for a larger change

For a feature touching several files, switch to Plan Mode and state the outcome, boundaries, and verification:

Goal: add server-side validation to the existing contact form.

Preserve:
- the current route and response contract
- the existing UI styling
- unrelated form fields

Use:
- the validation library already installed
- the nearest existing API error pattern

Before building:
- identify affected callers
- list exact files
- explain likely regressions
- provide the lint, type-check, test, and build commands that exist here

Plan Mode researches the codebase and produces a reviewable plan before writing code. Edit the plan if it changes the API shape, invents a second validation system, or touches unrelated pages. Build only when the plan matches the request.

Step 3 — let Agent implement, but watch the scope

During implementation, compare the live file list with the approved plan. Stop the run if it starts replacing established architecture, editing generated files, or widening the task without evidence.

A useful implementation prompt names acceptance criteria, not just files:

Implement the approved plan.

Acceptance criteria:
- invalid email returns the existing field-error shape
- valid submission keeps the current success behavior
- no new dependency
- no logging of names, email addresses, messages, tokens, or secrets
- update the existing tests for valid and invalid input
- run the repository's documented checks and report actual output

File limits can help, but do not use them blindly if the real fix requires a direct caller or shared type. Ask Agent to explain a necessary scope change before making it.

Step 4 — review like a pull request

Review every changed file, not only the last diff pane. Check:

• unexpected deletions, renamed exports, or changed return shapes
• authentication, authorization, validation, and error paths
• logging of personal data, tokens, or request bodies
• dependency and configuration changes
• loading, empty, success, and failure behavior
• tests that assert behavior rather than merely snapshotting new output
• formatting-only churn that hides the functional change

For auth, payments, cryptography, migrations, and destructive scripts, trace the control flow and test the failure paths manually. AI-generated code receives the same security review as human-generated code.

Step 5 — run real validation

Inspect the repository's scripts instead of inventing command names. Depending on the project, validation might include:

npm run lint
npm run typecheck
npm test
npm run build

Only run commands the repository actually defines. Read the error output and fix the root cause; do not weaken a check just to make it green. For UI work, inspect the affected route on desktop and mobile. For an API, test success, invalid input, unauthorized access where relevant, and server failure.

Step 6 — keep or recover deliberately

If the result is wrong, stop and inspect before sending several corrective prompts. For a flawed plan, restore the Agent checkpoint or use the team's normal Git recovery workflow, refine the plan, and build again. Remember that checkpoints track Agent changes, not every manual edit, and are cleaned up automatically.

Never treat Ctrl+Z as a reliable way to unwind an entire multi-file session.

Choosing the right surface

Use the smallest surface that can complete the task. A five-line edit does not need an autonomous repository run, and a cross-cutting migration should not begin as an unreviewed inline rewrite.

Context without the “whole codebase” myth

Codebase indexing and search help Cursor find relevant files and chunks. They do not make every file part of every prompt. Ask Agent to show which files support its conclusion. Attach or reference a known dependency when it misses one, and start a new task when a long conversation has accumulated irrelevant assumptions.

Available context controls differ between the Editor and Agents Window and can evolve. Use the file and @ controls shown in your current interface instead of memorizing an old exhaustive command list.

For large monorepos, place scoped .cursor/rules directories or AGENTS.md files near the relevant packages. Keep global rules truly global; frontend conventions should not silently govern a database migration.

Data use and Privacy Mode

Cursor sends prompts and relevant code context through its backend to model providers when AI features run. Its current data-use page says:

• with Privacy Mode enabled, Customer Data is not used for training by Cursor and providers are covered by zero-data-retention agreements, subject to abuse-detection handling and explicitly enabled non-ZDR model exceptions
• with Privacy Mode disabled, codebase data, prompts, editor actions, snippets, and other code data may be stored or used to improve AI features and train models
• codebase indexing uploads chunks to compute embeddings; embeddings and metadata such as hashes and file names may be stored
• encrypted file contents may be cached temporarily
• requests still pass through Cursor's backend when you use your own API key

Review the current policy, your workspace settings, enabled model, and connected tools before using Cursor with confidential code. Privacy Mode reduces specified data use; it does not replace access control, secret management, vendor review, or human judgment.

Common mistakes

Following legacy setup guides — .cursorrules, Composer-as-a-workflow name, fixed model lists, and old request quotas age quickly. Use the current Rules, Agent, and Models & Pricing pages.

Assuming Agent waits before every edit — workspace edits can save immediately. Watch the diff, keep Git available, and use Plan Mode when the approach needs approval first.

Writing one giant rule — split stable instructions by domain and application condition. Point to canonical source files instead of copying a style guide that will drift.

Expecting rules to change Tab — Cursor documents that rules do not affect Tab. Evaluate autocomplete separately.

Giving broad authority without acceptance criteria — “improve this app” invites churn. Name the user-visible outcome, preserved behavior, allowed scope, and required checks.

Trusting a confident repository explanation — ask for source files and trace the actual callers. Retrieval can miss context.

Treating a passing build as complete QA — builds catch compilation problems, not every authorization, mobile, accessibility, or business-rule regression.

Troubleshooting

A Project Rule is not applied — open Customize and confirm the rule is enabled. Check its application type, description, glob, and whether a matching file is in context. Confirm the file uses the .mdc extension; plain .md files in .cursor/rules are ignored.

Agent changes unrelated files — stop the run, inspect the diff, restore deliberately if needed, and tighten the plan. Add acceptance criteria and require an explanation before widening scope.

The whole file appears changed — inspect line endings, formatter versions, generated output, and format-on-save settings. Separate formatting cleanup from a functional patch.

Agent cannot find a file — check .cursorignore, repository roots, and the current workspace. Reference the file directly and ask Agent to trace its imports and callers.

A command should not run — reject it. Keep default approvals or a narrow allowlist, and inspect any script that can delete data, modify infrastructure, publish content, or contact an external system.

Checklist

• [ ] Working surface chosen for the task: Tab, Inline Edit, Agent, or Plan Mode
• [ ] Repository status inspected and existing changes understood
• [ ] Secrets kept outside the repository where possible
• [ ] Sensitive paths added to .cursorignore, with tool limitations understood
• [ ] Current .cursor/rules/*.mdc or AGENTS.md instructions scoped correctly
• [ ] Agent asked to inspect existing architecture before creating a new pattern
• [ ] Goal, preserved behavior, scope, and acceptance criteria written down
• [ ] Live and final diffs reviewed across every changed file
• [ ] Security-sensitive paths reviewed line by line
• [ ] Actual lint, type, test, build, API, or UI checks run as appropriate
• [ ] Checkpoints treated as short-term recovery, not a Git replacement
• [ ] Privacy Mode, model, tools, and workspace data policy reviewed

Practice task

Choose one small bug in a version-controlled practice repository. Ask Agent to explain the path without editing. Write one focused Project Rule or use the existing AGENTS.md. If more than one file is involved, create and review a Plan. Let Agent implement, watch the file list, review the complete diff, and run the repository's real checks. Record one missed assumption and improve the task or rule only if that lesson is likely to repeat.

FAQ

Is Cursor just VS Code with an extension?

Cursor's classic Editor is VS Code-based and supports importing VS Code settings and extensions. Cursor also has an Agents Window with a different agent-first workflow. Verify critical extensions and keybindings after moving; import support is not a guarantee of identical behavior.

Does Cursor see my whole repository?

Agent can search the repository and read relevant files. That is retrieval, not the entire codebase injected into every request. Context remains finite, and ignored files or missed dependencies can change the answer.

Which model or plan should I choose?

Model availability, Auto modes, included usage, and prices change. Test a current option on representative work and consult Cursor's Models & Pricing documentation and pricing page before buying. Do not treat a model named in an old review as the permanent default.

Are Project Rules applied to Tab suggestions?

No. Cursor's current Rules FAQ says rules do not affect Cursor Tab or other AI features. Use rules for Agent and the surfaces documented by the current rule type, then evaluate Tab independently.

Can I use Cursor on a monorepo?

Yes. Use root and nested .cursor/rules directories or root and nested AGENTS.md files to scope instructions to the packages they govern. Avoid duplicating an always-applied rule across roots without a reason.

Is Privacy Mode enough for a repository containing secrets?

No. Keep secrets out of the repository, use .cursorignore, restrict terminal and MCP permissions, and follow your organization's vendor and data policy. Cursor documents important protections for Privacy Mode, but also indexing, caching, abuse-detection, non-ZDR, and BYOK/backend details that must be understood.

Official Cursor sources checked

• Quickstart
• Agents Window
• Agent overview
• Plan Mode
• Rules
• Agent Security
• Ignore file
• Data Use & Privacy
• Models & Pricing

Takeaways

Cursor is most useful when the developer controls scope and evidence: choose the smallest suitable surface, give Agent the real acceptance criteria, review immediate file changes, and run the repository's checks. Use current Project Rules instead of legacy .cursorrules, and treat Privacy Mode and .cursorignore as documented controls rather than absolute guarantees.

If you remember one thing: Agent can act before you finish reviewing. Keep Git available, watch the diff, and verify the result against the actual project.