Cursor Agent Mode: How to Let Claude Build Entire Features Without Babysitting It

At some point, every developer has experienced the copy-paste loop: ask the AI, copy the code, paste it in, run it, watch it break, ask again. It gets old fast. Cursor’s Agent Mode is designed to end that cycle. Instead of handing you code to paste, the agent reads your codebase, plans the changes, edits multiple files, runs your tests, and iterates — all on its own. You describe the outcome, not the steps.

Cursor Agent Mode is a fully autonomous coding environment where the AI perceives the entire codebase, plans multi-step changes, executes them across multiple files, and iterates based on test results, without waiting for step-by-step instructions. That’s a meaningful shift from autocomplete. Agent Mode receives a goal, reads the codebase, plans, executes terminal commands, edits multiple files, runs tests, and iterates autonomously. The question isn’t whether it can do this — it’s how to structure the work so it does it well.

This tutorial walks through the complete workflow: activating Agent Mode, choosing the right mode for each task, writing prompts that actually produce shippable code, using test-driven development as a verification layer, and managing parallel agents so you’re not stuck watching a spinner. You’ll also get the subagent setup and cloud agent workflow that most developers miss entirely.

Requirements Before You Start

Cursor pricing in 2026 spans five tiers: Hobby at $0, Pro at $20 per month, Pro+ at $60 per month, Ultra at $200 per month, and Teams at $40 per user per month. Agent Mode’s full feature set, including Cloud Agents and extended agent limits, requires at minimum the Pro plan. Pro includes unlimited Tab completions, extended Agent limits, Cloud Agents, access to all frontier models, MCPs, skills, and hooks, plus a $20 monthly credit pool for premium model requests. For most developers coding daily, Pro is the right starting point. Start on Pro, observe two complete billing cycles, and move up only when accepted work is repeatedly blocked by included usage.

You’ll also need a project with at least a basic test setup — Agent Mode produces dramatically better results when it has tests to run against. More on that in the TDD section below.

Step 1 — Open Agent Mode and Understand the Four Modes

Open Agent with Cmd/Ctrl + I and cycle between Agent, Ask, Plan, and Debug modes with Shift + Tab. That’s it for activation. The harder part is knowing which mode to reach for.

Cursor gives you four distinct operating modes, and picking the wrong one is genuinely the most common source of wasted agent runs. Agent Mode is the default: autonomous execution that edits files and runs commands, used for building features and refactoring. Ask Mode is read-only: it searches the codebase and answers questions without touching anything, used for understanding code before changing it. Plan Mode creates an implementation plan before any coding starts and asks clarifying questions, used for complex features that need design first. Debug Mode investigates bugs systematically, generates hypotheses, and adds logs, used for hard bugs that need investigation.

The practical mental model: start in Ask to understand, move to Plan for anything touching more than three or four files, hand off to Agent for execution, and reach for Debug when a bug makes no sense. The problem is using Agent Mode for a task that should have started in Plan Mode, moved through Ask Mode for investigation, and only then been handed to Agent for execution. Skipping this sequence is how you end up staring at a diff that touched 14 files — half of them wrong.

Pro tip ✅

Before any feature that touches your auth layer, database schema, or shared utilities, run Ask Mode first with a codebase investigation prompt. The minute you spend there saves the twenty minutes you’d spend reverting Agent’s confident but wrong assumptions.

Step 2 — Write Goal-Level Prompts, Not Step-Level Instructions

The quality of your prompt is the single biggest lever you have over Agent output. The key shift is moving from describing steps to describing outcomes. Agent Mode figures out which files to read and what changes to make — your job is to define what “done” looks like clearly enough that it can verify its own work.

Here are concrete prompts structured for different task types. Copy and adapt them directly.

Feature build from scratch:

Add a user notification preferences page at /settings/notifications. Users should be able to toggle email, push, and in-app notifications independently. Persist settings to the existing user_preferences table. Add a new column notifications_config (JSON) if it doesn't exist. Write unit tests for the preference update logic and an integration test for the API endpoint. Do not modify any existing authentication middleware.

Notice the constraints at the end. Telling the agent what NOT to touch is as important as telling it what to build. Without that boundary, agents have a habit of helpfully refactoring things you didn’t ask them to touch.

Refactor existing code:

Refactor the fetchUserData() function in src/api/users.ts to use our standard ApiClient wrapper instead of raw fetch(). Match the pattern used in src/api/products.ts. Preserve all existing error handling behavior. Run the existing tests after refactoring to confirm nothing regressed.

Bug fix with verification:

The cart total calculation in src/store/cartSlice.ts is applying the discount code twice when a user removes and re-adds an item. Find the root cause, fix it, and add a test that reproduces the double-application bug before the fix and passes after. Do not change the discount validation logic in src/utils/discounts.ts.

Test generation for existing code:

Write comprehensive tests for the PaymentProcessor class in src/services/payment.ts. Cover: successful payment flow, declined card handling, network timeout, and duplicate transaction detection. Use Jest and the existing test patterns in src/__tests__/. Mock all external API calls.

Multi-file API endpoint:

Add a POST /api/v1/exports endpoint that generates a CSV export of the user's transaction history for a date range. Include: route definition in src/routes/exports.ts, controller in src/controllers/ExportController.ts, service logic in src/services/ExportService.ts, and tests for each layer. Follow the existing layered architecture pattern visible in the orders feature. Rate-limit to 5 requests per hour per user using the existing RateLimiter middleware.

Pro tip ✅

Always end feature prompts with a verification instruction: “Run the test suite after completing changes and fix any failures before finishing.” Without this, the agent considers itself done when the code looks right. With it, it loops on failures automatically.

Step 3 — Use Test-Driven Development as Your Verification Layer

The single most effective way to get Agent Mode to produce production-quality code is to give it a test to pass. For test-driven development with AI, reverse the workflow: write a failing test that describes the behavior you want, then ask Agent to implement a function that makes that test pass without modifying the test. This approach keeps implementations focused on actual requirements rather than hypothetical scenarios, and the test provides a precise specification that Cursor uses to generate accurate code.

The TDD prompt pattern is simple and reliable. First, write the test yourself (this is the only step you do manually):

// In src/__tests__/subscriptionService.test.ts
describe('SubscriptionService.downgrade', () => {
  it('should prorate the refund to the remaining billing period', () => {
    const service = new SubscriptionService();
    const result = service.downgrade({
      currentPlan: 'pro',
      newPlan: 'basic',
      billingCycleStart: new Date('2026-07-01'),
      downgradeDate: new Date('2026-07-15'),
    });
    expect(result.prorationAmount).toBeCloseTo(10.00, 2);
    expect(result.effectiveDate).toEqual(new Date('2026-07-15'));
  });
});

Then open Agent Mode and use this prompt:

The test in src/__tests__/subscriptionService.test.ts describes a downgrade() method for SubscriptionService. The test currently fails because the method doesn't exist. Implement the SubscriptionService class in src/services/SubscriptionService.ts with a downgrade() method that makes this test pass. Do not modify the test file. Run the test after implementing and fix any failures.

The agent now has a concrete, machine-verifiable success criterion. It can run the test, see the result, and iterate without asking you whether the output “looks right.”

Warning ⚠️

Always confirm the test fails before handing it to Agent Mode. If the test passes before any implementation exists, you’ve either already built the feature or the test is wrong. An agent handed a passing test will happily mark the task done without writing a single line of production code.

Step 4 — Manage Changes with Diff View and Checkpoints

Agent Mode applies edits as it works, and every change shows up as a reviewable diff before you commit. This is not just a safety feature — it’s how you catch the agent’s confident but subtly wrong architectural decisions before they compound.

Beyond the diff view, Cursor creates automatic checkpoints during agent sessions. According to Cursor’s official documentation, checkpoints save snapshots of your codebase during an Agent session, automatically created before significant changes and capturing the state of all modified files. If the agent goes off the rails mid-task — confidently refactoring a shared utility you needed left alone — you hover over any previous message and click “Restore Checkpoint” to roll back entirely.

Let Agent Mode handle full features, not just snippets: the agent performs best when given a complete task with a clear outcome rather than small fragmented requests. Use Checkpoints as your safety net.

Pro tip ✅

Before running any agent task that touches more than a handful of files, make a manual checkpoint or commit your current state to git. Automatic checkpoints are reliable, but a clean git commit gives you a named restore point that’s easier to reason about than a timestamp in the agent history.

Step 5 — Set Up Subagents for Parallel Workflows

Once you’re comfortable with single-agent runs, subagents are where the real productivity jump happens. Since Cursor 2.0, agents run inside isolated git worktrees, meaning each agent instance has its own branch and file system. As of v2.4 (January 2026), Cursor introduced subagents: independent child agents spun up to handle discrete subtasks in parallel, each with its own context window.

The mental model: your main agent is the tech lead. It plans, coordinates, and makes decisions. Subagents are the specialists it delegates to. Each one is focused, each one running in parallel, each one reporting back.

You create custom subagents by adding markdown files to your project. You can create subagents manually by adding markdown files to `.cursor/agents/` (project) or `~/.cursor/agents/` (user). Here’s a practical security-reviewer subagent to add to any project:

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities. Use after implementing any authentication, authorization, data validation, or external API integration.
model: inherit
readonly: true
---

Review the provided code changes for security issues. Check for:
1. SQL injection or NoSQL injection vectors
2. Hardcoded secrets, API keys, or credentials
3. Missing input validation or sanitization
4. Broken authentication or authorization logic
5. Insecure direct object references (IDOR)
6. Missing rate limiting on sensitive endpoints

Report findings as: CRITICAL, HIGH, MEDIUM, LOW with a one-line description and the specific file/line.
Do not make code changes. Report only.

Cursor comes with three subagents built-in: Explore to analyze your codebase, Bash to run CLI commands, and Browser to fetch and retrieve results from the internet. Custom subagents extend this. Keep them focused: start with 2-3 focused subagents and add more only when you have clear, distinct use cases.

Note 💡

Subagents have isolated context windows, which means intermediate reasoning stays out of the main conversation. This keeps your primary agent’s context window clean for the actual implementation work rather than cluttered with research tangents.

Step 6 — Use Cloud Agents for Long-Running or Background Tasks

Cloud Agents let you run many agents at once without requiring your laptop to stay connected. You can manage cloud agents from the Cursor editor and access them from anywhere using cursor.com/agents.

Cloud agents work well for tasks you’d otherwise add to a todo list: bug fixes that came up while working on something else. Start cloud agents from cursor.com/agents, the Cursor editor, or from your phone. Check on sessions from the web or mobile while you’re away from your desk. Cloud agents run in remote sandboxes, so you can close your laptop and check results later.

The workflow for complex features is: iterate locally with Plan Mode to nail down the approach, then hand off to a Cloud Agent for implementation while you move to the next task. For more complex features, using cloud agents to take over once you have a detailed plan in place works well. Cursor’s Plan Mode supports sending plans to be implemented in the cloud. You can iterate with a model locally to create a plan, then move on to the next task while a cloud agent implements the changes.

Here’s the prompt to kick off a cloud agent for a well-scoped task:

Implement the user export feature according to the plan saved in .cursor/plans/user-export.md. The acceptance criteria are:
1. All tests in src/__tests__/exports/ pass
2. The endpoint returns a valid CSV for the sample fixture in src/__fixtures__/user-transactions.json
3. Rate limiting is enforced — verify with the rate limit test
4. No changes to files outside src/routes/exports.ts, src/controllers/, src/services/ExportService.ts, and the test directory

Push changes to the feature/user-export branch when complete.

Avoid 🚫

Don’t run parallel cloud agents on overlapping files. If two features both touch your database schema or a shared utility, run them sequentially or split the shared work into a separate task that completes first.

Step 7 — Configure Your Project Rules for Consistent Output

Without project-level rules, Agent Mode codes like a competent contractor who just walked in the door and has never seen your codebase before. With them, it codes like someone who’s been on the project for months. Cursor provides two main ways to customize agent behavior: Rules for static context that applies to every conversation, and Skills for dynamic capabilities the agent can use when relevant.

Add a `.cursor/rules/conventions.mdc` file with your project’s key patterns. Here’s a practical starting template:

---
description: Project coding conventions
alwaysApply: true
---

# Project Conventions

## Architecture
- All API routes live in src/routes/, controllers in src/controllers/, services in src/services/
- Services handle business logic; controllers handle only request/response
- Never put database queries directly in controllers

## Code Style
- TypeScript strict mode — no `any` types without a comment explaining why
- All async functions must handle errors explicitly — no unhandled promise rejections
- Use the ApiClient wrapper in src/utils/ApiClient.ts for all external HTTP calls

## Testing
- Test files in src/__tests__/ mirroring the source structure
- Use Jest — no other test frameworks
- Mock all external services; never make real API calls in tests
- Run `pnpm test` to execute the full suite

## Naming
- Database table names: snake_case
- TypeScript interfaces: PascalCase with I prefix (IUserPreferences)
- React components: PascalCase, one component per file

What to Check Before Merging Agent-Generated Code

Agent Mode is not a replacement for code review — it’s a replacement for the typing. Before any agent-generated feature goes to production, run through this checklist mentally:

First, verify the tests actually cover edge cases and not just the happy path. Agents tend to write optimistic tests. Add a few failure scenarios yourself. Second, check that the agent respected your architectural boundaries — it’s common for it to add a utility function directly in a controller when your convention requires a service layer. Third, scan for any hardcoded values that should be environment variables. The security-reviewer subagent above catches most of these, but a quick grep for obvious strings is fast insurance.

The 20-40% productivity gains teams are reporting are real, but they come from disciplined use of the right feature at the right time — not from handing the entire codebase to an AI and hoping for the best. The discipline is the workflow: Ask first, Plan for complexity, Agent for execution, tests as the verification layer.

Pro tip ✅

After any significant agent session, run your full linter and type checker before looking at the diff. Cursor’s agent harness orchestrates components for each model it supports and tunes instructions for every frontier model based on internal evals and external benchmarks. Different models respond differently to the same prompts. Linter output gives the agent concrete, actionable feedback it can fix on its own — much better than you manually pointing out every style violation.

You’re Not Replacing Yourself, You’re Promoting Yourself

The developers getting the most out of Cursor Agent Mode are not the ones who hand it vague tasks and accept whatever comes back. They’re the ones who treat the agent like a capable junior engineer: give it a clear spec, a way to verify its own work, guardrails on what not to touch, and a rollback mechanism for when it goes sideways. The core shift is that senior developers plan first, then hand the agent a concrete, scoped goal rather than typing code themselves. That’s the actual workflow. Everything in this tutorial is scaffolding around that one principle.

Start with a single well-scoped task using the TDD pattern. Review the diff carefully the first few times to calibrate your trust. Add your project rules file early — it’s a one-time setup that pays dividends on every session after. Then, once you’ve seen a few agent runs that actually match what you wanted, start stacking: parallel subagents, cloud handoffs, Plan Mode for the complex stuff. The ceiling on what you can ship in a day moves significantly.

Frequently Asked Questions

Does Cursor Agent Mode work with any programming language?

Agent Mode works with any language supported by the underlying models, which covers all major languages well. Results are strongest with TypeScript, Python, Go, and Rust, where frontier model training data is densest. For less common legacy languages, expect to do more manual review of agent output before merging.

What’s the difference between local Agent Mode and Cloud Agents?

Cloud agents run from cursor.com/agents, mobile, Slack, GitHub, and Linear, all appearing in the unified Agents Window sidebar. You can start a task on your phone and pick it up in the IDE, or hand a local session off to the cloud mid-task. Local agents require your machine to stay on; cloud agents run in remote sandboxes independently.

How do I roll back if the agent breaks something?

Cursor automatically creates checkpoints before significant changes during any agent session. Hover over any previous message in the agent chat and click “Restore Checkpoint” to roll the modified files back to that state. For extra safety, commit to git before large agent runs so you have a named restore point.

How much does running Agent Mode heavily actually cost on the Pro plan?

When Cursor picks the model for you in Auto mode, usage is included at no extra cost. Manually selecting frontier models like Claude Sonnet or Opus draws from your $20 monthly credit pool. When the pool runs out, you switch to Auto for the rest of the month or pay overages at API rates with no penalty markup. Heavy agent users who manually select Opus for every task often exhaust Pro credits mid-month and need Pro+ at $60/month.

Promptyze

Promptyze covers generative AI in plain English — hands-on reviews, tutorials and daily news, fact-checked and hype-free.

See Full Bio