Build Your First AI-Assisted Feature

You have Cursor configured, your rules written, your MCP servers running, and your context management skills sharp. The theory is done. Now it is time to prove the setup works by building something real. This walkthrough takes you through a complete feature build — from requirements to passing tests — using every pattern from the previous sections. By the end, you will have a concrete mental model for how AI-assisted development actually feels in practice.

What You’ll Walk Away With

• A complete feature built with Cursor’s Agent mode from start to finish
• Experience switching between Plan mode and Agent mode at the right moments
• Confidence that your project rules, MCP servers, and context strategies work together
• A repeatable workflow you can apply to every feature going forward

Choosing Your Feature

The best first feature has these characteristics:

Requirement	Why It Matters
Multi-file (3-8 files)	Tests the agent’s ability to coordinate changes across your project
Has clear acceptance criteria	Gives you and the agent a definition of “done”
Touches your real codebase	Validates that your rules and context produce correct output
Is not mission-critical	You can experiment without production risk

Good examples: a new API endpoint with validation, a settings page, a webhook handler, a notification preferences UI. Bad examples: a full authentication rewrite, a database migration on production data.

The Complete Workflow

We will build a rate limiter middleware for an Express/Hono/Next.js API. This is small enough to complete in 15 minutes but touches multiple layers: middleware, configuration, tests, and error handling.

Phase 1: Plan (5 minutes)

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

Copy-paste prompt to start planning 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 any clarifying questions before generating the plan.

The agent in Plan mode will:

1. Search your codebase for existing middleware patterns
2. Ask you about your framework (Express, Hono, Next.js, etc.)
3. Check if you already have a rate limiter or similar middleware
4. Generate a plan with file locations, interfaces, and implementation order

Review the plan. If it proposes creating files in the wrong directory, or using a pattern that does not match your project, tell it. The plan is cheap to change — code is expensive to rewrite.

Phase 2: Build (8 minutes)

Once the plan looks right, switch to Agent mode (Shift+Tab again or Cmd+.). Now work through the plan task by task.

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 project’s conventions because your project rules specify the patterns.

2. Add configuration

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

   The agent finds your existing config patterns and follows them.

3. Wire it into the application

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

   The @ reference tells the agent exactly which file to modify.

4. Write 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 writes the tests, executes them, sees failures, fixes the implementation, and reruns until everything passes. You watch the diff view and intervene only if it goes off track.

5. Verify the build

   Run the full test suite and type check to make sure we haven't
   broken anything else. Fix any issues.

Phase 3: Review (2 minutes)

After the agent finishes, use Cursor’s review feature:

1. Click Review in the agent panel
2. Select Find Issues to run a dedicated review pass
3. The agent analyzes its own changes and flags potential problems

Also review the diff yourself. Look for:

• Hardcoded values that should be configurable
• Missing error handling (what if the counter store throws?)
• Test coverage gaps (are edge cases covered?)
• Convention violations (anything your rules should have caught but did not)

If you find a convention violation, this is the signal to update your project rules. Fix the code and add the rule so the next feature gets it right automatically.

What Actually Happens During the Build

Here is the real flow, including the detours:

[Plan Mode] Agent proposes putting rate limiter in src/lib/
You say: "No, our middleware goes in src/middleware/ per our conventions"
Agent adjusts the plan.

[Agent Mode] Agent creates src/middleware/rate-limiter.ts
It uses your existing middleware pattern from the rules.
Agent creates src/middleware/rate-limiter.test.ts
Runs tests -- 2 fail because the mock timer is wrong.
Agent fixes the mock and reruns -- all pass.

[Agent Mode] Agent edits src/app.ts to add the middleware.
You notice it applied to ALL routes including health check.
You say: "The health check should be excluded, the plan said that."
Agent adds the exclusion logic.

[Agent Mode] Agent runs full test suite -- one unrelated test fails.
Agent reads the failure, sees it is a flaky test, reports it.
You confirm it is pre-existing, not caused by your changes.

Done. 5 files changed, 3 new files, all tests pass.

This is realistic. The agent does not get everything perfect on the first try, especially for the first feature. But each iteration takes seconds, not minutes. And the mistakes become rarer as your project rules improve.

Note

Do not expect perfection on the first pass. Expect rapid iteration. The value of AI-assisted development is not that the AI gets it right immediately — it is that the cycle from mistake to fix is measured in seconds, not hours.

Patterns to Apply to Every Feature

The Pre-Flight Check

Before starting any feature, verify:

• Your project rules are committed and up to date
• The agent can see your project (test with “How is this project structured?”)
• Auto-run is enabled for tests and builds
• You have selected the right model (Opus 4.6 for complex, Sonnet 4.5 for simple)

The Commit Strategy

Commit 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"

This gives you git-based rollback points in addition to Cursor’s checkpoints. If the agent breaks something during integration, you can roll back to the working core module.

The Post-Feature Rule Update

After every feature, ask yourself: “Did the agent make any mistakes that a rule could prevent next time?” If yes, update .cursor/rules/ and commit the change alongside your feature code.

Copy-paste prompt for a post-feature retrospective

Review the changes we just made for the rate limiter feature.
Were there any mistakes or deviations from our project conventions?
If so, suggest updates to our Cursor project rules in .cursor/rules/
that would prevent these in the future.

Scaling Up: What Changes for Larger Features

For features that take days instead of minutes, the workflow scales by adding more planning and more frequent context resets:

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	Many conversations	Per task

For large features, save your plan to .cursor/plans/ and reference it in every new conversation. Each conversation handles one task from the plan.

When This Breaks

Agent keeps modifying the wrong files: Your prompt is too vague. Use @ references to specify exactly which files to modify.

Generated code does not follow your patterns: Your project rules are missing or too vague. Add specific examples to your rules.

Tests pass but the feature does not work: The tests are testing the wrong thing. Review the test assertions manually. Ask the agent: “Are these tests actually verifying the requirements from the plan?”

The agent goes off the rails and will not recover: Press Escape, restore the checkpoint, start a new conversation, and give it a more specific prompt.

Build breaks after the agent’s changes: Run tsc or your build command. Tell the agent: “The build broke after your changes. Fix all errors.” With auto-run enabled, it will iterate until the build passes.

What’s Next

Error Handling and Recovery Debugging patterns, checkpoint recovery, and strategies for when the AI generates broken code.