Build your first AI-assisted feature

A first AI-assisted feature in Cursor is a small, complete loop: acceptance criteria are written first, Plan Mode turns them into a reviewed plan, the agent builds one step at a time with a commit after each, and tests mapped to each criterion prove the result. The feature is done when that evidence passes, not when the agent reports success.

Documentation freshness

Covers: the Cursor 3.x line; the current release on 2026-10-12 is Cursor 3.24 (2026-10-09, Cursor’s release notes). Cursor’s help says Cmd+I (Ctrl+I on Windows and Linux) opens the Agent panel and Shift+Tab cycles through the agent modes, the docs name the run modes Auto-review, Allowlist and Run Everything, and checkpoints are stored locally, separate from Git, and restoring one reverts files only (all checked 2026-10-12). Plan Mode and Bugbot were first verified against cursor.com on 28 August 2026. This page relies on git for every rollback.

This tutorial is for a developer who has installed Cursor, written a few project rules, and now wants to ship something real. You ask the agent for rate limiting, it edits nine files in one response, the tests it wrote pass, and you have no idea whether /health is still reachable behind a load balancer. The workflow below keeps each step small enough to check and makes the checking mechanical.

What you get from your first feature build

• A feature-sized task picked by four criteria, so the first run teaches you something without risking production.
• Acceptance criteria written before any code, which become both the plan’s contract and the test list.
• Five copy-paste prompts: plan, build one step, wire in, prove the tests, and a retrospective that updates your rules.
• A verification routine (criterion-to-test map, a deliberate break per test, git status --short --untracked-files=all and git diff --stat, a live request) that replaces reading the whole diff.
• Recovery steps for the six ways a first feature usually goes wrong.

Which feature should you build first?

Pick a task that exercises the agent without betting anything on it.

Criterion	Why it matters for a first run
Touches 3–8 files	Enough to see whether the agent coordinates changes and follows your conventions; small enough to check each step.
Acceptance criteria you can write in five lines	Criteria give the plan a contract and the tests an oracle. Vague tasks produce confident, untestable code.
Integrates with existing code	Shows whether your rules and the codebase index steer the agent toward your patterns.
Off the critical path	A mistake costs you a revert, not an incident.

Good first features: an API endpoint with request validation, a webhook handler, a settings panel, a notification-preferences dialog. Leave authentication rewrites and production database migrations for later, when you have a verification routine you trust.

The example on this page is an in-memory rate-limiting middleware for a Node.js API written in TypeScript, with Express and Vitest. It touches middleware, configuration, routing, and tests, and it hides two classic traps (client IP behind a proxy, and timers in tests) that show why evidence beats reading.

Prepare the repository before the agent starts

1. Start from a clean tree on its own branch. In a terminal:

   git status --short        # must print nothing; commit or stash first
   git switch -c feat/rate-limiter

2. Confirm the gates run from one command each, and note them for the prompts. For this example: npx vitest run, npm run typecheck, and npm run lint. If your project has no single test or type-check command, fix that first; see making a codebase agent-ready.

3. Check that your project rules are committed and describe where middleware lives and how configuration is read. The agent follows what the rules say, so a missing convention shows up as a wrong file location later.

4. Decide which commands the agent may run without asking. If your workspace’s run mode (Auto-review or Allowlist, set under Settings > Agents > Approvals & Execution) lets you pre-approve commands, pre-approve only your test, type-check, and lint commands; otherwise approve them as they come. Keep approval on for everything else. Essential configuration covers the agent settings.

5. Ask the agent one orientation question in a new chat, and compare the answer with what you know: “Where do the HTTP middleware functions in this repository live, and how do they read configuration?” A wrong answer means the index or the rules need attention before you build.

Write the acceptance criteria first

Criteria are the one artifact you must read closely, because everything after them is checked against them. Number them so the plan, the tests, and the review can refer to them. See writing acceptance criteria an agent cannot misread for the full method.

AC1  Requests are counted per client IP. Behind our proxy the client IP comes
     from req.ip with Express "trust proxy" set to 1, never from a raw header.
AC2  Window and limit come from RATE_LIMIT_WINDOW_MS (default 900000) and
     RATE_LIMIT_MAX (default 100).
AC3  Request number MAX+1 inside the window gets 429 with a JSON error body in
     our standard error format and a Retry-After header in whole seconds.
AC4  GET /health and GET /ready are never limited.
AC5  Counters reset when the window ends (fixed window).
AC6  Counters live in memory. Each instance counts separately; this is accepted
     until the Redis store ships.

AC6 is a limitation written down on purpose. A reviewer who knows it is accepted will not waste time on it, and the next person will not mistake it for a bug.

Plan the feature in Plan Mode

Switch the agent to Plan Mode (Shift+Tab cycles through the modes), which creates an implementation plan before it writes any code. Paste the criteria into the prompt so the plan is built against them.

Copy-paste prompt: plan the rate limiter

Plan rate-limiting middleware for our Express API. Do not write code yet.

Acceptance criteria:
AC1 Count requests per client IP using req.ip with "trust proxy" set to 1.
AC2 RATE_LIMIT_WINDOW_MS (default 900000) and RATE_LIMIT_MAX (default 100).
AC3 Request MAX+1 in the window returns 429, our standard JSON error body,
    and Retry-After in whole seconds.
AC4 GET /health and GET /ready are never limited.
AC5 Fixed window; counters reset when the window ends.
AC6 In-memory store only, one counter map per process.

Before planning, find our existing middleware, how middleware reads config,
and our error-response helper. Tell me which files you looked at.
Ask me up to three clarifying questions if a criterion is ambiguous.

The plan must list: every file to create or change, the order of the steps,
and for each step the acceptance criteria it satisfies and the test that proves it.

Review the plan against a short checklist before you let it build:

• Every criterion AC1–AC6 maps to at least one step and one named test.
• New files sit where your existing middleware sits, and the plan reuses your error helper instead of inventing one.
• No new dependency appears unless you asked for one. An unexpected package is a question to answer now, not after it is installed; see dependency checks for agent changes.
• Tests use fake timers (vi.useFakeTimers()) for AC5 instead of real waiting.

Correct the plan in the same chat (“Middleware goes in src/middleware/, not src/lib/”) until the checklist passes. A correction here costs one sentence; the same correction after the build costs a rewrite.

Build the feature one step at a time

Leave Plan Mode by switching the chat back to Agent mode, as building in Agent mode shows, and execute the plan step by step. Switching modes starts a fresh context window (Cursor’s help, checked 2026-10-12), so save the accepted plan to a file before you switch and attach it with @ in the first build prompt. One step per prompt keeps each change small enough to check with git status --short --untracked-files=all, which lists modified files and every new, untracked file (marked ??), and gives you a commit to return to. git diff --stat is not enough here: it ignores files the agent created. Keep --untracked-files=all (short form -uall): without it, a new directory collapses to a single dir/ line and hides the files inside it.

1. Build the core module and its unit tests together. Tests written in the same step as the code lock in the criteria while they are fresh.

   Copy-paste prompt: build one plan step

   Implement step 1 of the plan: the rate-limiter middleware in
   src/middleware/rate-limiter.ts and its tests in
   src/middleware/rate-limiter.test.ts. Cover AC1, AC3 and AC5 only.
   Follow the structure of the existing middleware in @src/middleware/.
   
   Use Vitest fake timers for the window reset. Do not touch any other file.
   Run `npx vitest run src/middleware/rate-limiter.test.ts` and show me the output.
   If a test fails twice for the same reason, stop and tell me what you observed.

   Then check the scope and commit:

   git status --short --untracked-files=all   # expect only the two files from the prompt
   git add -A && git commit -m "feat: rate limiter core (AC1, AC3, AC5)"

2. Add configuration. Ask for AC2 in its own prompt: “Implement plan step 2: read RATE_LIMIT_WINDOW_MS and RATE_LIMIT_MAX the way our other middleware reads config, with the defaults from AC2, and add tests for the defaults and for an override.” Check git status --short --untracked-files=all, then commit.

3. Wire the middleware into the app. This step touches shared code, so name the file and the exclusions explicitly.

   Copy-paste prompt: wire in the middleware

   Implement plan step 3. Mount the rate limiter in @src/app.ts for all routes
   except GET /health and GET /ready (AC4). Set "trust proxy" to 1 if it is not
   already set, and tell me if it was.
   
   Add an integration test with supertest that sends MAX+1 requests to one
   API route and asserts 429 plus Retry-After, and sends MAX+1 requests to
   /health and asserts 200 every time.
   
   Run the full suite with `npx vitest run`, then `npm run typecheck` and
   `npm run lint`. Show me the three outputs.

   Commit when all three gates pass.

If the agent edits or creates a file you did not name, do not argue with it in the same chat. Go back to the last commit: git reset --hard reverts changes to tracked files, and git clean -fd deletes the untracked files the agent created. git restore . alone is not enough: it reverts tracked files but silently leaves every new file the agent created in place. Preview that deletion with git clean -nd first, because it also removes any untracked file of your own. Then repeat the prompt with the file list and an explicit “Do not touch any other file.”

git clean -nd                        # preview: lists the untracked files to delete
git reset --hard && git clean -fd    # back to the last commit

Prove the feature works without reading every line

Passing tests the agent wrote prove only that the code agrees with the tests. You need to know that the tests would catch a wrong implementation. The next prompt makes the agent demonstrate that for each criterion; this is a small, manual form of mutation testing. For the concept behind it, see how strong is your test oracle.

Copy-paste prompt: prove each criterion has a test that can fail

For each acceptance criterion AC1–AC5, name the test that proves it.
Then, one criterion at a time:
1. Break the implementation in the smallest way that violates the criterion
   (for AC4, remove the /health exclusion; for AC3, drop the Retry-After header).
2. Run `npx vitest run` and confirm that the named test fails.
3. Restore the implementation exactly and confirm the suite passes again.

Do not edit any test file during this task. Report a table:
criterion | test name | failed when broken (yes/no) | restored and green (yes/no).
Finish with `git status --short`, which must show no changes.

A “no” in the table is a real finding: either the criterion has no test or the test cannot fail. Ask for a test that fails when broken, and rerun the table. Then collect the rest of the evidence yourself:

1. Confirm the whole change is the size you expect:

   git diff --stat main...HEAD

   Any file outside middleware, config, src/app.ts, and tests needs a reason.

2. Confirm no test was weakened. Search the branch diff for skipped or deleted assertions:

   git diff main...HEAD -- '*.test.ts' | grep -E '^-.*expect\(|^\+.*\.(skip|only)\('

   An empty result is what you want. The protect-the-oracle guide explains how to enforce this outside the chat.

3. Hit the running server. Set RATE_LIMIT_MAX=3 in your local environment, then start (or restart) your development server so it reads the new value. In another terminal, run the following, replacing /api/items with any limited route:

   for i in 1 2 3 4; do curl -s -o /dev/null -w "%{http_code} " http://localhost:3000/api/items; done; echo
   curl -si http://localhost:3000/api/items | grep -i retry-after
   curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/health

   Expect 200 200 200 429, a Retry-After header, and 200 from /health.

4. Open the pull request with the criteria table in its description. If your team runs Bugbot, it reviews the pull request for bugs, security issues, and code quality problems; treat its findings as input to the reviewer, not as the gate.

The reviewer, you or a teammate, signs off on three things: the criteria, the criterion-to-test table, and the scope from git diff --stat. Reading code is reserved for the parts that the evidence cannot cover, such as the IP-extraction logic in AC1, which carries security weight. Reading evidence instead of code explains where that line sits as your routine matures.

What goes wrong on a first feature, and how to recover

Symptom	Likely cause	Recovery
The plan puts files in the wrong directory or invents a helper you already have	Rules do not state the convention, or the agent did not look	Correct it in Plan Mode before building, then add the convention to a project rule
One prompt edits files you never mentioned	Scope was implied, not stated	Preview with git clean -nd, then git reset --hard && git clean -fd to return to the last commit; repeat with @ references to the exact files and “Do not touch any other file”
Tests pass, but the live curl check fails	Tests mock the thing that broke (often req.ip or the router)	Ask for an integration test through the real app with supertest, then rerun the break-each-criterion prompt
The agent loops on the same failing test	The chat holds several failed attempts that pull the next one toward them	Stop the agent, return to the last commit with git reset --hard && git clean -fd (preview with git clean -nd), and start a new chat with your own diagnosis; see error recovery in Cursor
The agent “fixes” a failing test by changing its expectation	Nothing forbade editing tests	Revert the test file; add “Do not modify test files” to the prompt and check with the grep from the proof step. To enforce it mechanically, add it to a project rule or block writes to *.test.ts with a Cursor hook during build steps; see protect the oracle
A new package appears in package.json	The plan did not rule out dependencies	Revert it unless you approve it, then verify the name and publisher before reinstalling

Turn the corrections into rules

Every correction you typed during this feature is a rule the next session should already know. Run a short retrospective before you close the chat.

Copy-paste prompt: post-feature retrospective

Review this chat and the commits on this branch for the rate-limiter feature.
List every place where I corrected you: file locations, helpers you missed,
test patterns, scope violations.

For each correction, propose one project rule of at most three lines that
would have prevented it. Show the proposed rules only; do not create or edit
any file until I approve them.

Accept only rules that would have prevented a real correction. A rule file grown from vague advice costs context on every request and changes nothing.

How the workflow scales to larger features

The same loop works for bigger features with three changes. Split the criteria into slices that each end in a passing test, and run one chat per slice so each starts with a clean context. Save the approved plan as a Markdown file in the repository and reference it with @ at the start of each chat, because a plan held only in chat history is gone when the chat ends. Commit per plan step, not per slice, so a bad step never takes good work with it.

When the slices are independent, Cursor can run agents in parallel, each in its own worktree, from the Agents Window (for manual worktrees, see checkpoints and branching); do that only after the single-agent loop above feels routine. For the team-level version of this workflow, see the Build stage of the lifecycle.

Where to go after your first Cursor feature

Error recovery in Cursor Roll back with git, stop fix loops, and decide when to fix forward.

Test-driven development with Cursor Write the failing test first and let the agent make it pass.

The evidence bundle Package tests, scope, and checks into one manifest a reviewer can sign off.

Collaboration in Cursor Share rules, plans, and review habits with the rest of your team.

Using another agent as well? The same loop in the terminal is on the Claude Code development workflow page, and in Codex on your first Codex task.