Using Cursor

Cursor will happily take a one-line request and rewrite a dozen files in a single turn. That speed is the whole point, and it is also exactly where it goes wrong. The agent does not understand your intent. It predicts plausible edits from whatever sits in its context, and plausible is the dangerous kind, because plausible code compiles, reads well, and quietly does the wrong thing.

Picture the expensive version. A developer opens the Agent chat and types "clean up the signup flow and fix the validation." No plan, no attached files. The agent searches the index, decides the signup flow includes the shared form utilities, and refactors those too. It renames a prop used in four other forms, updates the ones it found, and misses the two it did not. The diff is 340 lines across nine files. The developer skims it, sees green tests (the agent did not touch those), and accepts the whole set. Two days later a different signup page throws at runtime, and now the cause is buried in a large accepted commit nobody read closely.

None of that is a Cursor failure. It is the absence of the three levers. The developer supplied no context boundary, agreed no plan, and did not review the diff file by file. Each lever maps to a built-in Cursor surface: rules and @-mentions for context, Plan Mode for the plan, and the staged per-file diff plus checkpoints for review. The payoff of using them is concrete. Cursor's own engineers report that most new features now begin with the agent writing a plan, and that the discipline significantly improves the code generated. The mechanism behind each lever is what the next section breaks down.

Cursor is VS Code with an agent loop wired into it. The agent reads, searches, edits, and runs commands in a turn, and the surfaces you control sit at each stage of that loop.

• The index. When you open a workspace, Cursor breaks the code into chunks (functions, classes, blocks), converts each into a vector embedding, and stores them so the agent can search by meaning. Indexing starts automatically and semantic search comes online at 80% completion. The agent combines this with plain grep, which together answer codebase questions roughly 12.5% more accurately than grep alone, with the largest gain on repos over 1,000 files.
• @-mentions. @Files and @Folders pin exact context into the prompt, @Code pulls a specific snippet, and @Codebase searches the whole index. Pinning is how you correct a bad retrieval guess before it happens.
• Rules. .mdc files under .cursor/rules/ carry your conventions. Each has frontmatter with three fields: alwaysApply, a description for intelligent selection, and globs for file matching. That yields four behaviors: Always (every chat), Auto Attached (when a matching file is in context), Agent Requested (the agent pulls it by description), and Manual (you @-mention it).
• Plan Mode and Agent. Plan Mode is read-and-research only; Agent is the mode that writes and runs.
• Checkpoints. Cursor snapshots state before every Agent operation, and edits stage as one diff with per-file accept and reject.

The distinction that decides success is Plan Mode versus jumping straight to Agent. Plan Mode researches the codebase, asks clarifying questions, and produces a Markdown plan with real file paths and a list of to-dos that you can edit directly. As Cursor puts it, planning forces clear thinking about what you are building and gives the agent concrete goals to work toward. For a routine, single-file change you can skip it. For anything with more than one reasonable approach, or anything that spans systems, plan first so you negotiate the approach in cheap prose before any code exists.

The second distinction is verifiable versus vague goals. The agent self-corrects against signals it can read: a failing test, a type error, a linter warning. Cursor's best-practice guidance is blunt that agents cannot fix what they do not know about, so a typed language, a linter, and tests give the loop a target. "Make it cleaner" gives it nothing to check, and it will declare victory on a guess. With the parts named, the next section walks one change through end to end.

Maya, a developer on a small web app, needs to add server-side rate limiting to the login endpoint. The repo has an auth module she half remembers and a middleware folder she does not. She opens Cursor and resists the urge to type "add rate limiting" into Agent.

1. Set the context. She attaches what she knows matters: @Files login.ts authMiddleware.ts and @Folders src/middleware. This pins the real files instead of trusting the index to guess which "auth" she means.
2. Enter Plan Mode. She presses Shift+Tab and writes "Add rate limiting to the login endpoint: 5 attempts per IP per 15 minutes, return 429 with a Retry-After header." The agent asks two clarifying questions: in-memory or Redis-backed, and whether existing successful logins should reset the counter. She answers Redis and yes.
3. Read and edit the plan. The agent writes a Markdown plan touching four files, with a to-do to add a rateLimiter.ts middleware. The plan also proposes editing userRoutes.ts, which Maya does not want changed, so she deletes that to-do directly in the plan and saves it to the workspace under .cursor/plans/.
4. Execute with Agent. She switches to Agent and lets it build from the edited plan. The live diff stages 78 lines across three files. The new rateLimiter.ts looks right; the edit to login.ts wires it in cleanly.
5. Verify against a real signal. She runs the test suite plus a new test the plan added for the 429 case. The 429 test passes, but the linter flags an unused import the agent left behind. She accepts rateLimiter.ts and login.ts, rejects the third file's stray change, and fixes the import herself.
6. Commit small. She commits "add IP rate limiting to login (5/15min, 429 + Retry-After)" as one reviewable, revertable step.

The whole change took one plan, one execution, and a focused review. Because the plan was a Markdown artifact she edited first, the agent never went near userRoutes.ts, and because the diff was per-file, she kept the two good files and dropped the noise. Maya carries into the pitfalls below, where the same task shows how each shortcut quietly breaks.

Each trap feels like progress in the moment, which is exactly why it costs you later.

• Skipping the plan on a multi-file change. Going straight to Agent on a fuzzy request lets the agent decide the scope for you. The fix is Plan Mode for anything beyond a single obvious file, and editing its to-dos to cut work you did not ask for, as Maya did with userRoutes.ts.
• Trusting retrieval blindly. The index is a guess, and it misses files that are renamed, new, or only reachable through dynamic imports. When a change depends on a specific file, attach it with @Files rather than hoping search finds it.
• The stale .cursorrules file. The legacy single .cursorrules file is superseded by .cursor/rules/: once .mdc rules exist they take precedence over it, so a team that half-migrated watches the agent break conventions it thinks are still enforced. Move them into scoped .mdc files under .cursor/rules/.
• Accepting the whole diff at once. A big "Accept all" is how a bad edit slips in next to nine good ones. Read per file and accept per file; reject anything that guesses at intent.
• Fighting drift with more prompts. When a turn goes sideways, stacking follow-up instructions usually compounds the mess. Restore the checkpoint and refine the plan, which Cursor explicitly recommends as faster and cleaner than iterating mid-turn.

Two genuine edge cases sit underneath the rules. Rule selection is itself a guess. An Agent Requested rule only loads if the agent judges its description relevant, so a vague description means the rule silently does not apply. For conventions that must always hold, set alwaysApply: true or scope them with a precise glob rather than relying on the description.

The large-diff review trap is a 2026 reality. The agent can generate more change than a human can carefully review, and Cursor's own guidance warns that the faster the agent works, the more your review process matters. A 400-line agent diff that looks reasonable can still rest on an assumption you never checked. Keep turns small, prefer several scoped plans over one sweeping one, and treat the diff size as a signal to slow down. That habit only gets harder when a whole team shares the repo, which is where scale comes in.

A solo developer can keep the levers in their head. The moment a team shares the repo, the levers have to become versioned artifacts, or they quietly stop happening and the agent's habits diverge per person.

The durable artifact is the rules directory. Version .cursor/rules/*.mdc with the repo so every developer's agent reads the same conventions, scoped to the right files by glob. Keep each rule tight and add one only when you notice the agent repeating the same mistake, which is the discipline Cursor recommends over writing a giant rule file up front. For conventions that should also apply in other AI tools, a plain AGENTS.md at the root works across Cursor and Claude Code alike, and Cursor now reads nested AGENTS.md files so a subdirectory can carry its own instructions.

Plans become a team artifact too. When a feature begins with Plan Mode, Saving to workspace under .cursor/plans/ turns the plan into reviewable documentation: a teammate can read the approach before any code lands, and a future agent resuming the work inherits the context. This is the same plan-first habit that Cursor credits for better generated code, made shareable.

Review is where a team feels the load. Priya, a lead on Maya's team, sets two norms. First, keep agent PRs small, ideally under 400 lines, because review capacity, not code volume, is now the bottleneck on AI-assisted work. Second, the PR description records that the agent wrote the change, the plan it followed, and the prompt, so a reviewer reads the diff knowing it came from a predictor and can ask "what assumption is this resting on?" rather than "does this look fine?".

The durable principle to keep, whatever the team size: Cursor moves fast precisely because it predicts, so your job is to hold the three levers steady. Supply the context, agree the plan, review the diff. Start with one small thing this week. Move your conventions out of a stale config file and into one scoped .mdc rule, and watch how much less the agent has to guess.