Build your first AI-assisted feature

Building a first AI-assisted feature in Cursor means running a complete Plan-Build-Review cycle: Plan mode drafts an implementation plan from requirements, Composer 2.5 Agent mode executes it task by task with auto-run enabled, and Bugbot or Agent Review flags potential issues before a human reviews the diff. The example used throughout this guide is a rate-limiter middleware, small enough to finish quickly while exercising multiple layers of the codebase.

This guide is for developers building their first multi-file feature in Cursor. You will navigate from requirements to passing tests using Plan mode, Agent mode, and automated test execution. For end-to-end lifecycle orchestration across your team, see Build.

Feature build outcomes

• Implement a multi-file feature with Cursor Agent mode from start to finish.
• Switch between Plan mode and Agent mode at appropriate milestones.
• Verify that project rules, MCP servers, and context strategies work together.
• Establish a repeatable workflow for future feature development.

Choose your feature

Select an initial feature that satisfies the following criteria:

Requirement	Why it matters
Multi-file (3-8 files)	Tests the agent’s ability to coordinate changes across your project.
Clear acceptance criteria	Provides you and the model with a verifiable definition of completion.
Existing codebase integration	Validates that your project rules and context indexing produce accurate code.
Non-critical path	Allows you to iterate and experiment without production risk.

Suitable examples include an API endpoint with request validation, a settings panel, a webhook handler, or a notification preferences dialog. Avoid full authentication rewrites or production database migrations as an initial exercise.

The complete workflow

This walkthrough builds an in-memory rate limiter middleware for an API. The scope touches middleware routing, configuration parsing, unit tests, and error handling.

Phase 1: Plan

To start planning, switch to Plan mode by pressing Shift+Tab in the agent input, or select Plan from the mode picker with Cmd+..

Prompt to plan your feature

I need to add rate limiting middleware to our API. Requirements:

- Limit requests by IP address.
- Configurable window (default 15 minutes) and max requests (default 100).
- Return 429 Too Many Requests with a Retry-After header when exceeded.
- Store counters in memory for now (Redis later).
- Skip rate limiting for health check endpoints.
- Include unit tests.

Review our existing middleware patterns and propose an implementation plan.
Ask me clarifying questions before generating the plan.

In Plan mode, Cursor performs the following actions:

1. Searches your codebase for existing middleware patterns and routing conventions.
2. Identifies your web framework and error formatting utilities.
3. Checks for existing rate limiting libraries or conflicting middleware.
4. Generates an implementation plan specifying file locations, interfaces, and task ordering.

Review the proposed plan. If it targets an incorrect directory or violates a project convention, instruct the agent to adjust the plan before generating code.

Phase 2: Build

When you approve the plan, switch to Agent mode (Shift+Tab or Cmd+.). Execute the plan sequentially using the following steps:

1. Create the rate limiter module

   Implement the rate limiter middleware based on the plan.
   Start with the core logic: the sliding window counter and the
   middleware function. Follow the patterns in our existing middleware.
   @src/middleware/

   The agent creates the middleware file matching your repository conventions specified in .cursor/rules/.

2. Add configuration parameters

   Add configuration for the rate limiter. Read from environment
   variables with sensible defaults. Follow how our other middleware
   reads configuration.

   The agent inspects your existing environment configuration and applies matching patterns.

3. Wire into the application router

   Add the rate limiter middleware to our API route handler. Apply it
   to all routes except /health and /ready.
   @src/app.ts

   The @ reference directs the agent to the exact file requiring integration.

4. Write unit and integration tests

   Write unit tests for the rate limiter middleware. Test:
   - Requests under the limit pass through
   - Requests over the limit get 429
   - The Retry-After header is correct
   - Health check endpoints bypass the limiter
   - The counter resets after the window expires
   
   Run the tests after writing them and fix any failures.

   With auto-run enabled, the agent executes tests, inspects error output, fixes implementation discrepancies, and reruns the suite until all tests pass.

5. Verify the full build

   Run the full test suite and type check to verify no regressions were introduced.

Phase 3: Review

After code generation finishes, use Cursor’s review tools:

1. Click Review in the agent panel.
2. Click Find Issues to analyze proposed edits with Bugbot.
3. Inspect the self-review suggestions and verify edge-case coverage.

Inspect the Git diff directly in your editor. Check for:

• Hardcoded constants that should read from environment variables.
• Missing error handling if store operations throw exceptions.
• Uncovered edge cases in concurrent requests.
• Style violations not covered by existing project rules.

When you discover an uncaught convention violation, update .cursor/rules/ so future agent sessions follow the rule automatically.

Execution trace

The following sequence illustrates a standard build session:

[Plan Mode] Agent proposes putting rate limiter in src/lib/
You respond: "Our middleware goes in src/middleware/ per our conventions."
Agent updates the plan.

[Agent Mode] Agent creates src/middleware/rate-limiter.ts
Agent uses existing middleware patterns from .cursor/rules/.
Agent creates src/middleware/rate-limiter.test.ts
Agent runs tests; two fail due to incorrect timer mocks.
Agent fixes mock timers and reruns; all tests pass.

[Agent Mode] Agent edits src/app.ts to mount the middleware.
You notice the middleware was applied to all routes including health checks.
You respond: "Exclude health check endpoints as defined in the plan."
Agent adds endpoint bypass logic.

[Agent Mode] Agent runs full test suite; one unrelated flaky test fails.
Agent reads the failure stack trace and identifies the test as pre-existing.
You verify the flaky test is unrelated to your rate limiter.

Result: 5 files modified, 3 new files created, all test suites green.

Patterns for every feature

Pre-flight check

Before starting feature implementation, verify:

• Project rules in .cursor/rules/ are committed and current.
• Cursor indexing is complete (verify with @codebase How is this project structured?).
• Terminal auto-run is enabled for tests and linters.
• The appropriate model is selected (Claude Fable 5 or Opus 5 for complex multi-file logic; Sonnet 5 for standard implementations; see the model selection guide).

Commit strategy

Commit changes incrementally after each successful phase:

# After the core module is working
git add src/middleware/rate-limiter.ts
git commit -m "Add rate limiter middleware core logic"

# After tests pass
git add src/middleware/rate-limiter.test.ts
git commit -m "Add rate limiter tests"

# After integration
git add src/app.ts
git commit -m "Wire rate limiter into API routes"

Incremental commits provide clean rollback points alongside Cursor checkpoints.

Post-feature rule update

After completing a feature, evaluate whether the agent made mistakes that a rule could prevent. If so, add a rule to .cursor/rules/:

Prompt for post-feature retrospective

Review the changes we made for the rate limiter feature.
Identify any convention deviations or manual corrections required during the build.
Suggest updates to our rules in .cursor/rules/ to prevent these issues in the future.

Scale up for large features

For features that span days or touch numerous services, structure work across multiple conversations:

Feature size	Planning time	Conversation length	Commit frequency
Small (1-3 files)	2 minutes	Single conversation	End of feature
Medium (5-10 files)	10 minutes	2-3 conversations	Per component
Large (15+ files)	30+ minutes	Multiple dedicated conversations	Per task

For large features, save the implementation plan to .cursor/plans/ and reference it at the start of each task.

Troubleshoot build failures

• Agent modifies incorrect files: Include specific @file references in your prompt to constrain the edit scope.
• Code violates project patterns: Add concrete code examples to .cursor/rules/*.mdc.
• Tests pass but behavior is incorrect: Inspect assertions manually. Ask the agent: “Do these tests verify the acceptance criteria from the plan?”
• Agent gets stuck in a retry loop: Press Escape, revert to the last clean checkpoint, and provide a prompt with tighter constraints.
• Build fails after edits: Run the build command and instruct the agent: “The build failed with the following error. Resolve the type errors without altering test expectations.”

Confirm that the feature works

To verify the completed feature:

1. Run your unit test suite:

   npm test -- src/middleware/rate-limiter.test.ts

   Confirm that all test cases pass.

2. Run type checking and linting:

   npm run typecheck && npm run lint

   Confirm that zero errors are reported.

3. Run a local verification request against your development server:

   curl -i http://localhost:3000/api/test

   Verify that response headers include rate limit metadata and return status 429 when exceeding the configured limit.

Next steps

AI-Native SDLC: Stage 3 - Build & Execution Master Composer 2.5 Plan Mode, worktree isolation, and automated validation in Cursor

AI-Native SDLC: Stage 5 - Deploy & Review Integrate Cursor Bugbot and automated review gates into your deployment workflow

Error Handling and Recovery Learn checkpoint recovery and debugging strategies when code generation fails