Search for AI Courses, Tech News and, Blogs

How to Use Cursor on a Real Project Without Losing Control of the Code

by Jose Aleman | 2 weeks ago | 15 min read
@@ same bug report, two ways to run it @@
-

"fix the checkout bug", then walk away

27 files changed, none of them read

+

plan, one small diff, review, commit

3 files changed, all of them understood

Last spring I gave Cursor's agent a one-line bug report on a client codebase and went to make coffee. When I got back it had changed 27 files. The bug lived in one of them. Every edit looked reasonable, the tests passed, and I still lost the afternoon working out which changes to keep.

That was the day I stopped treating Cursor as autocomplete with ambition and started treating it as a very fast junior developer who needs a brief, a fence and a code review.

I've used it on production work every day since, through the Cursor 3 release, Auto-review and this month's Projects beta. It has become far more autonomous in that time. Agents now run in the cloud for hours and open pull requests while your laptop is shut. Handy. It also means that if you set nothing up, you end up with a repo full of code nobody on your team has read.

Below is the setup and working loop I use to avoid that. I checked every setting against Cursor's documentation as it stands this month, because a lot of older advice describes options that have since been renamed or retired.

New to the tool? Start with our test of Cursor AI from the sign-up screen inward, which covers onboarding, the free tier and what it costs. This guide picks up once Cursor is installed and pointed at code you care about.

The short version

• Write your rules and ignore files before the first prompt, and commit them.

• Keep the run mode on Auto-review or a tight Allowlist. Run Everything has no place on a repo that holds credentials.

• Plan first, keep each diff small enough to read in one sitting, commit after every accepted step.

• Cloud agent output gets the same pull request review a person would get.

Title: Cursor's Agents Window - Description: Cursor Agents Window showing a list of agent chats, a task summary, and a diff of uncommitted files with Review and Commit and Push buttons

What losing control looks like

Nobody decides to stop understanding their own codebase. It happens in four ordinary ways.

The diff you can't read

Cursor puts no limit on tool calls per task, so a vague prompt can spread across dozens of files. Once reviewing takes longer than writing it yourself, you start approving on faith.

The command you didn't expect

The agent runs shell commands: installs, migrations, Git operations. What runs without asking depends on a setting many people never open.

Conventions that quietly erode

Models carry nothing over between sessions. Without written rules, each chat reinvents your patterns, and one service ends up with three styles of error handling.

The invoice

Past your included usage, requests bill per token at API rates. A long agent run on a premium model is not cheap.

Worth knowing. A randomized trial published by METR in July 2025 had 16 experienced open-source developers complete 246 tasks in repos they knew well, mostly with Cursor Pro. With AI allowed they took 19% longer, and afterwards still believed they had been 20% faster. Models have improved since. The gap between feeling fast and being fast is the part I keep in mind.

Set up the repo before you type a prompt

Cursor reads a handful of config files straight from the repo. Commit them and every teammate, and every cloud agent, starts inside the same fence.

Cursor config files worth committing

FileWhat it controlsThe catch
.cursor/rules/*.mdcProject rules, scoped with frontmatterA plain .md file in this folder is ignored
AGENTS.mdPlain markdown instructions, root or per folderNested files combine, and the more specific one wins. CLAUDE.md is read the same way
.cursorignoreFiles hidden from Agent, Tab, Inline Edit and @ mentionsTerminal and MCP tools can still reach ignored files
.cursor/permissions.jsonTerminal and MCP allowlists, plus guidance for Auto-reviewAn allowlist set here makes the in-app editor read-only
.cursor/sandbox.jsonNetwork domains and paths a sandboxed command can reachTeam admin policy always sits on top of it
.cursor/hooks.jsonScripts that allow or block agent actionsHooks fail open unless you say otherwise
.cursor/worktrees.jsonSetup commands for worktrees, such as npm ciCursor advises against symlinking dependencies
.cursor/BUGBOT.mdReview rules for Bugbot and Agent ReviewYour .mdc rules do not apply to Bugbot runs

Rules that earn their place

Project rules come in four types: Always Apply, Apply Intelligently (the agent reads the description and decides), Apply to Specific Files (matched by glob) and Apply Manually (only when you @-mention it). Typing /create-rule in chat gets the agent to write one for you.

Cursor's own guidance is blunt, and I agree with it. Keep rules under 500 lines. Point to a canonical file instead of pasting code. Skip the style guide, because that is a linter's job. Add a rule when the agent makes the same mistake twice, not before. When rules conflict, Team Rules beat Project Rules, which beat User Rules. None of them affect Tab completions.

Title: Team Rules in the Cursor dashboard - Description: Team Rules page in the Cursor dashboard with one rule named React plus GraphQL

.cursor/rules/payments.mdc

---

globs: src/payments/**/*.ts

alwaysApply: false

---

- Money is integer cents everywhere. No floats.

- Never edit files under src/payments/ledger/ without asking first.

- Match the error shape in @src/payments/errors.ts

- Every new endpoint ships with a test in src/payments/__tests__/

.cursorignore is a privacy screen, not a vault

Everything in .gitignore is already hidden from the agent, along with .env* files and lockfiles. Add keys, certificates and data exports. Then read the fine print. Cursor's docs state that terminal and MCP tools can't enforce .cursorignore, so an agent that runs cat on an ignored file can still see it. Real secrets belong outside the workspace.

Working solo? Switch on Privacy Mode under Settings, then General, so your code is never used for training. Don't assume it's on. When we tested Cursor's onboarding on a fresh account, the data sharing switch arrived already flipped on. Team plans get Privacy Mode by default.

Pick a run mode on purpose

Open Settings, then Agents, then Approvals & Execution. This one dropdown decides how much the agent does without asking you.

Cursor run modes for local agents

ModeWhat runs without askingSandboxWhere I'd use it
Auto-reviewAllowlisted calls run at once. Other shell commands run sandboxed where possible. The rest go to a classifier that can allow, redirect the agent, or ask youYesMost repositories. Recommended default since Cursor 3.6
AllowlistOnly what you list. Leave the list empty and every command asks firstOptionalAnything close to production
Run EverythingEvery tool callNoThrowaway prototypes in a disposable environment

"Ask Every Time" was deprecated in Cursor 3.5 in May. An empty allowlist gives you the same behaviour. Auto-review arrived a week later, and Cursor's run modes documentation is upfront that it "is not a security boundary". The classifier can wave through a call you'd have blocked. So steer it. A permissions.json in the repo takes plain-English instructions:

.cursor/permissions.json

{

  "terminalAllowlist": [

    "git status",

    "git diff",

    "npm:test*",

    "npm:run lint*"

  ],

  "autoRun": {

    "block_instructions": [

      "Database migrations need my approval first.",

      "Any git push, rebase or reset needs my approval first."

    ]

  }

}

Leave File-Deletion, External-File and Browser Protection switched on too. They force an approval even when the mode would otherwise run the call.

Gotcha. Agent edits save to disk the moment they're made. If a dev server with hot reload is running, the new code can execute before you've read it. I stop the server, or move to a worktree, for anything that touches startup code or migrations.

Work in a loop you can review

This is the part that matters most, and it costs nothing.

1

Plan before any code

Shift+Tab switches the chat to Plan Mode. The agent asks questions, reads the codebase and writes a plan you can edit. I read the file list first. If it names files I didn't expect, my prompt was too vague. "Save to workspace" keeps the plan in the repo next to the code it produced.

2

Hand over narrow context

@-mention the files that matter, or use @Branch to attach your whole branch diff. The ring beside the input shows how full the context window is. Once Cursor starts summarising older turns, I open a fresh chat.

3

Watch, and interrupt early

The diff view updates live. Hit Stop (Cmd+Shift+Backspace) the moment it heads somewhere odd. Enter queues your next message, and Cmd+Enter sends it straight away.

4

Checkpoints for undo, Git for history

Cursor snapshots the files it modifies, and you restore from the chat timeline. Checkpoints are local and separate from Git. They revert files only, so they won't un-run a migration.

5

Review before you commit

Run /agent-review, or use the Source Control tab to check all local changes against main. Quick depth suits small diffs. Deep is for auth, money and concurrency. Then read the diff yourself anyway.

6

Commit small

One accepted step, one commit. If the history got messy, ask the agent to rework it into logical commits, which Cursor's review guide also recommends.

Title: Read the handoff before the diff - Description: A finished Cursor agent run with a summary, a testing section listing passed and failed checks, and a Create PR button
When to start over. Cursor's docs say reverting and sharpening the plan is often faster than fixing a wrong build with follow-ups. My rule is two corrective prompts, then revert.

Put risky work in a worktree

Start a prompt with /worktree and the rest of that chat runs in a separate Git checkout. Your main checkout stays untouched. /apply-worktree brings the result back, /delete-worktree clears it, and /best-of-n runs the same task across several models so you can compare.

Gotcha. Cursor cleans up old worktrees automatically, with a default cap of 25 per machine, and worktrees you made yourself with git worktree add are fair game too. Push or apply anything you care about.

Use hooks for the rules that must never bend

Rules and classifiers are advice to a model. Hooks are code. A hook is a script that receives JSON on stdin at a set point in the agent loop and answers allow, deny or ask. Exit code 2 blocks the action outright. When several hooks respond, deny beats ask, and ask beats allow.

.cursor/hooks.json

{

  "version": 1,

  "hooks": {

    "beforeShellExecution": [

      {

        "command": ".cursor/hooks/guard-db.sh",

        "matcher": "migrate|psql|prisma",

        "failClosed": true

      }

    ],

    "afterFileEdit": [{ "command": ".cursor/hooks/format.sh" }]

  }

}

The catch is that a hook which crashes or times out fails open by default, and the action goes ahead. Set failClosed: true on anything security-critical. Cloud agents run project hooks from the repo but never see your personal ~/.cursor/hooks.json.

With cloud agents, the pull request is your only gate

Cloud agents run in isolated VMs, work on their own branch and push for handoff. Run modes don't apply to them, and the agent never stops to ask for approval. All of your control moves to the pull request.

Where your control sits, local versus cloud

 Local agentCloud agent
Approval promptsSet by your run mode and sandboxNone
UndoCheckpoints, then GitClose the PR or revert the branch
Your gateLive diff view and Agent ReviewPR review, Bugbot, CI and branch protection

So protect main and require a human approval. Add Bugbot, which reviews every PR update. One detail catches teams out. Bugbot findings report a neutral check status by default, so requiring the check won't block a merge unless fail-on-unresolved-issues is enabled for your organization.

Title: A Bugbot review on a pull request, with an Autofix prepared and waiting for a person to accept it - Description: A Cursor Bugbot comment on a pull request reporting one potential issue with a prepared Autofix and a Create PR button

This matters more than it did a few months ago. Since August, cloud agents subscribe to the PRs they open and keep pushing until CI is green. Projects, in beta since September 10, adds a coordinator agent that plans, delegates to other agents, and can watch a Slack channel and act unprompted. I use all of it with tight scope, and nothing reaches main unread.

Cap the bill while you're at it

Cursor pricing, September 2026

PlanPriceWhat you get
Pro$20 a monthBoth usage pools, unlimited Tab, Bugbot, Cloud Agents
Pro Plus$60 a monthSame features, more included usage
Ultra$200 a monthSame features, the most included usage
Teams$40 per user (Standard), $120 (Premium)Central billing, Team Rules, enforced Privacy Mode, SSO

Paid plans have two usage pools. Cursor Models (Grok 4.6, Grok 4.5 and Composer 2.5) come with far more included usage. Other Models bill at the provider's API price. Cursor's docs estimate that daily Agent users land between $60 and $100 a month in total usage.

On individual plans, on-demand billing stays off until you enable it. If you do, set a spend limit, and know that enforcement isn't instant. I run routine edits on Composer and keep the expensive models for planning and hard debugging.

What Cursor gets right, and where you still have to watch it

@@ after daily use on production code @@
+Guardrails live in the repo as files, so they go through code review like everything else.
+Plan Mode gives you an editable plan before a single line exists.
+Checkpoints and worktrees make experiments cheap to throw away.
+Hooks give you enforcement that doesn't depend on the model behaving.
-.cursorignore does not bind terminal or MCP tools.
-Auto-review can misjudge a command, and Cursor says so itself.
-Cloud agents never pause for approval, so weak PR review means no review.
-Long autonomous runs on premium models get expensive.
-Settings get renamed and moved almost monthly, so tutorials go stale fast.

My pre-merge checklist

I run through this before any agent-written branch goes up for review.

☐     I can explain every changed file without opening the chat.

☐     The diff matches the saved plan, and nothing outside it moved.

☐     Tests, types and lint pass locally, and I ran them myself.

☐     Agent Review or Bugbot findings are resolved, not dismissed.

☐     No new dependency, env var or migration slipped in unmentioned.

☐     Each commit is small enough that a teammate could revert it alone.

Final verdict

I still open Cursor every working day, and I no longer get the 27-file surprise. A smarter model didn't fix that. An afternoon of setup did: four rule files, a .cursorignore, a short permissions.json, and one hook that keeps everything away from the database unless I say so. Since then the agent has worked inside a fence the whole team can read, and my job has shifted from typing to planning and reviewing, which is where a senior developer's time should go anyway.

I trust it with well-scoped features, test coverage, refactors behind good tests, and the dull migrations nobody wants. I don't hand it auth, billing logic, or anything where I couldn't explain the diff line by line. Cloud agents and the Projects beta I treat like a contractor I've never met. Glad of the help, and every line goes through a pull request.

If you keep one thing from this page, keep the loop: plan, small diff, review, commit. Cursor is quick enough that the discipline barely slows you down. Skipping it is how you end up maintaining code you've never read.