Advanced Workflows

Agent is Cursor's dedicated multi-file editing interface. While Chat can discuss code and Agent can execute tasks autonomously, Agent gives you a collaborative space specifically designed for creating and editing multiple files in coordination.

Opening Agent:

Agent vs Chat vs Agent — when to use which:

Agent Normal mode workflow:

1. Open Agent mode (Cmd+I / Ctrl+I)
2. Describe what you want across multiple files
3. Agent shows proposed changes as diffs for each file
4. You review and accept/reject each file's changes individually
5. Changes are applied only when you accept them

Example: Generating a complete feature

Agent prompt:
"Create a notification system with these files:
1. src/types/notification.ts — Notification type with id, message, type (success/error/info), timestamp
2. src/stores/notificationStore.ts — Zustand store with add, remove, and clearAll actions
3. src/components/NotificationToast.tsx — Individual toast component with auto-dismiss
4. src/components/NotificationContainer.tsx — Container that renders all active toasts
5. src/hooks/useNotification.ts — Hook that provides show/dismiss helpers

Follow patterns in existing store files and components."

Agent generates all 5 files, showing you each one. You can:

• Accept all at once
• Accept some, reject others
• Modify the prompt and regenerate specific files

Example: Coordinated API + Frontend changes

"Add a 'favourites' feature:
1. Add a Favourite model to prisma/schema.prisma (userId, postId, createdAt)
2. Create src/app/api/favourites/route.ts with GET (list user's favourites) and POST (add favourite)
3. Create src/app/api/favourites/[id]/route.ts with DELETE (remove favourite)
4. Create src/hooks/useFavourites.ts with React Query hooks for the endpoints
5. Add a FavouriteButton component to src/components/posts/FavouriteButton.tsx
6. Update src/components/posts/PostCard.tsx to include the FavouriteButton

Use optimistic updates in the mutation hooks."

Tips for effective Agent prompts:

• Number your files — the AI follows numbered lists more precisely
• Specify file paths explicitly — don't make the AI guess locations
• Reference existing files — "Follow the pattern in X" is powerful
• Include relationships — explain how the files interact
• Set constraints — "Maximum 50 lines per file" or "No external dependencies"

Advanced refactoring goes beyond renaming variables. These patterns restructure your codebase while preserving behaviour — exactly where AI assistance provides massive value.

Pattern 1: Extract and decompose

Breaking a large file into logical modules:

Agent/Agent prompt:
"Refactor src/services/orderService.ts (currently 600 lines) into separate concerns:

1. src/services/orders/orderValidation.ts — Extract all validation functions
2. src/services/orders/orderCalculation.ts — Extract pricing and tax calculations  
3. src/services/orders/orderNotification.ts — Extract email and notification logic
4. src/services/orders/orderRepository.ts — Extract database operations
5. src/services/orders/index.ts — Re-export everything for backward compatibility

Requirements:
- Preserve all existing function signatures (no breaking changes)
- The index.ts must export everything the original file exported
- Move types to src/services/orders/types.ts
- Update all imports across the codebase that reference the old path
- Run tests after to verify nothing breaks"

Pattern 2: Design pattern migration

Converting from one pattern to another across the codebase:

"Migrate our data fetching from the custom useAPI hook pattern to React Query:

Current pattern (in multiple files):
  const { data, loading, error } = useAPI('/api/users')

New pattern:
  const { data, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: () => apiClient.get('/api/users')
  })

Files to migrate:
- src/features/users/UserList.tsx
- src/features/users/UserProfile.tsx
- src/features/posts/PostList.tsx
- src/features/posts/PostDetail.tsx

Also create the queryKey constants in src/lib/queryKeys.ts.
Keep the old useAPI hook for now (other files still use it) but add a deprecation comment."

Pattern 3: Type system upgrade

Strengthening types across the codebase:

"Replace all 'any' types in src/features/ with proper TypeScript types:

1. Find all usages of 'any' in .ts and .tsx files under src/features/
2. For each usage, infer the correct type from how the value is used
3. If the correct type doesn't exist, create it in the nearest types.ts file
4. If a type is shared across features, place it in src/types/

Do NOT change any runtime behaviour. This is purely a type-safety improvement.
If you genuinely cannot determine the type, use 'unknown' with a TODO comment."

Pattern 4: API version migration

When your backend API changes:

"Our API is migrating from v1 to v2. Changes:
- Response wrapper changed: { data: T } → { result: T, meta: { timestamp, requestId } }
- Pagination changed: { page, perPage } → { cursor, limit }
- Auth header changed: X-Auth-Token → Authorization: Bearer <token>

Update all API client code in src/lib/api/ and all hooks in src/hooks/queries/ to use v2.
Create an adapter in src/lib/api/v2Adapter.ts that maps v1 responses to v2 format
for any endpoints that haven't been migrated on the backend yet."

Pattern 5: Component library migration

Migrating from one UI library to another:

"Migrate from Material UI to shadcn/ui in src/components/:

Phase 1 (this task): Migrate these basic components:
- Button: MUI <Button> → shadcn <Button>
- Input: MUI <TextField> → shadcn <Input> with <Label>
- Dialog: MUI <Dialog> → shadcn <Dialog>
- Card: MUI <Card> → shadcn <Card>

For each component:
1. Install the shadcn component if not already present
2. Update the import and usage
3. Map MUI props to shadcn equivalents (variant, size, color)
4. Preserve all existing functionality and accessibility
5. Update any associated tests"

Safety practices for complex refactoring:

1. Commit before starting — always have a clean rollback point
2. Refactor in phases — don't try to change everything at once
3. Run tests between phases — catch issues early
4. Review diffs carefully — AI refactoring can silently change behaviour
5. Keep a refactoring log — document what changed and why

AI can augment your code review process — both when reviewing others' code and when preparing your own code for review.

Pre-review: AI-checking your own code

Before opening a PR, ask the AI to review your changes:

Review these changes for:
1. Potential bugs or logic errors
2. Missing error handling
3. Performance concerns
4. Security issues (input validation, data exposure)
5. Deviations from our project conventions

@src/features/orders/OrderForm.tsx
@src/hooks/useCreateOrder.ts
@src/app/api/orders/route.ts

Reviewing others' code with AI assistance:

When reviewing a PR:

1. Checkout the branch locally
2. Open the changed files
3. For each file, select the changes and ask specific questions:

@src/services/paymentService.ts

This code was added in a PR. Review it for:
- Race conditions (this handles concurrent payment processing)
- Error recovery (what happens if the payment gateway times out?)
- Is the retry logic correct? Could it charge the customer twice?

AI review checklist prompts:

Create reusable review prompts for different types of changes:

For API changes:

Review this API endpoint for:
- Input validation completeness
- Proper HTTP status codes
- Error response format consistency
- Authentication/authorization checks
- Rate limiting considerations
- Response payload — is anything exposed that shouldn't be?

For React component changes:

Review this component for:
- Unnecessary re-renders (missing memoization)
- Memory leaks (cleanup in useEffect)
- Accessibility (aria attributes, keyboard navigation)
- Loading and error states
- Edge cases (empty data, very long strings, null values)

For database/schema changes:

Review this database change for:
- Migration safety (can this be rolled back?)
- Index implications (new queries need new indexes?)
- Data integrity (foreign keys, constraints)
- Performance with large datasets
- Backward compatibility with existing code

The AI review workflow:

1. Read the PR description (understand intent)
2. Ask AI to summarise: "What does this PR change at a high level?"
3. Ask AI for risk assessment: "What could go wrong with these changes?"
4. Deep dive on specific files: "Is there a bug in this function?"
5. Verify edge cases: "What happens when [unusual input]?"
6. Check consistency: "Does this follow our established patterns?"

Limitations of AI code review:

• Cannot run the code — it reasons about logic, not runtime behaviour
• May miss business logic errors (doesn't know your domain rules)
• Can produce false positives ("this might have a bug" when it's fine)
• Doesn't replace human review for architectural decisions

Cursor's AI features become even more powerful when a team aligns on shared practices, rules, and workflows.

Shared .cursor/rules for team consistency:

As covered in Lesson 6, the .cursor/rules file ensures everyone's AI generates consistent code. For team collaboration, extend this with:

## Team Conventions (for AI)
- When creating new files, add a file header: // Feature: [name] | Owner: [team]
- API endpoints must be documented with OpenAPI JSDoc annotations
- All exported functions need unit tests in a co-located .test.ts file
- PR descriptions should follow our template in .github/PULL_REQUEST_TEMPLATE.md

Shared prompt templates:

Create a prompts/ directory in your project with reusable AI prompts:

prompts/
├── new-feature.md        # Template for scaffolding features
├── new-api-endpoint.md   # Template for API routes
├── refactor-component.md # Template for component refactoring
└── review-checklist.md   # Template for AI-assisted review

Example prompts/new-feature.md:

# New Feature Prompt Template

Copy this into Agent and fill in the blanks:

---
Create a complete [FEATURE_NAME] feature:

1. Types: src/features/[feature]/types.ts
2. Store: src/features/[feature]/store.ts (Zustand)
3. API hooks: src/features/[feature]/hooks/
4. Components: src/features/[feature]/components/
5. Page: src/app/(main)/[feature]/page.tsx

Follow patterns in src/features/users/ for structure.
Include loading states, error handling, and optimistic updates.
---

Consistent AI model usage:

If your team is on Cursor Business:

• Align on which AI model to use for different tasks
• Share model-specific tips (e.g., "Model X is better for refactoring, Model Y for generation")
• Standardise agent mode settings across the team

Collaborative debugging with AI context:

When a teammate asks for help:

1. They share the relevant file references and error
2. You open the same files and reproduce the context
3. Both can ask the AI with the same context — comparing answers
4. Or: they share their Chat conversation (copy-paste) so you can see the AI's reasoning

Knowledge sharing through .cursor/rules evolution:

Establish a process:

1. Developer discovers a useful AI instruction (e.g., "The AI keeps using moment.js — I'll add a rule")
2. They add it to .cursor/rules in a PR
3. Team reviews and approves
4. Everyone benefits immediately

Pair programming with AI:

When pair programming with Cursor:

• One person drives (types prompts, reviews output)
• One person navigates (checks logic, catches issues, suggests refinements)
• The AI is the "third programmer" — fast at generating, needs human oversight
• Switch roles regularly — both should practice prompting

After learning all the individual features, the final skill is combining them into a workflow that matches your specific development style and project needs.

The daily development loop:

Morning:
1. Pull latest changes
2. Review any open PRs (AI-assisted review)
3. Check issue tracker for today's task

Feature work:
4. Plan the approach in Chat ("How should I structure X?")
5. Scaffold with Agent/Agent (multi-file generation)
6. Refine with Cmd+K (inline edits for details)
7. Debug with AI (errors → Chat → fix → iterate)
8. Test (run tests, ask AI to explain/fix failures)

Wrap-up:
9. Self-review with AI (pre-PR quality check)
10. Commit with AI message
11. Open PR

Workflow by task type:

Bug fix workflow:

1. Read the bug report
2. Search codebase for relevant code (Cmd+Shift+F)
3. Open relevant files (3-5 files)
4. Ask Chat: "Given this error and these files, where's the bug?"
5. Apply fix with Cmd+K
6. Ask Chat: "Write a regression test for this bug"
7. Run tests, commit, PR

New feature workflow:

1. Discuss architecture in Chat
2. Scaffold files with Agent
3. Implement core logic (Agent or manual)
4. Add tests (Agent: "add tests for the new feature following our patterns")
5. Polish UI (Cmd+K for style tweaks)
6. Self-review (AI + manual)
7. Commit, PR

Refactoring workflow:

1. Identify scope (which files, what pattern change)
2. Commit current state (safety net)
3. Agent task for batch 1 of changes
4. Run tests → fix failures
5. Commit batch 1
6. Agent task for batch 2
7. Run tests → fix failures
8. Commit batch 2
9. Final review of all changes
10. PR

Customising your keyboard shortcuts:

If you find yourself using certain AI features constantly, consider custom shortcuts:

Measuring your improvement:

Track these metrics over time:

• Time from "start feature" to "PR open" (should decrease)
• Number of PR review comments about style (should decrease with .cursor/rules)
• Number of bugs caught before merge (should increase with AI review)
• Personal confidence with unfamiliar code (should increase)

When NOT to use AI:

AI is not always the answer. Skip it for:

• Trivial changes you can type faster than prompt (renaming a local variable)
• Decisions requiring deep domain knowledge the AI lacks
• Security-critical code that needs manual expert review
• When you need to deeply understand the code (reading > generating for learning)

Let's walk through a complete advanced workflow that combines multiple features from this course.

Scenario: You need to add a "saved searches" feature to your e-commerce application. Users can save search filters and re-apply them later.

Step 1: Plan (Chat)

Chat: "I need to add a 'saved searches' feature. Users save search filters
(category, price range, sort order, keywords) and can re-apply them.
We use Next.js 14, Prisma, React Query, and Zustand.

What's the best architecture for this? How many files do I need?"

AI provides an architecture plan with file list.

Step 2: Scaffold (Agent)

Agent: "Create the saved searches feature with these files:
1. prisma/migrations/add_saved_searches.sql — add SavedSearch model
2. src/features/saved-searches/types.ts — TypeScript types
3. src/features/saved-searches/store.ts — Zustand store for UI state
4. src/app/api/saved-searches/route.ts — GET (list) and POST (create)
5. src/app/api/saved-searches/[id]/route.ts — PUT (update) and DELETE
6. src/features/saved-searches/hooks/useSavedSearches.ts — React Query hooks
7. src/features/saved-searches/components/SavedSearchList.tsx — list component
8. src/features/saved-searches/components/SaveSearchButton.tsx — save button

Follow patterns in src/features/wishlists/ for structure and conventions."

Review all generated files, accept or modify.

Step 3: Refine (Cmd+K inline edits)

Open SavedSearchList.tsx and select the empty state:

Cmd+K: "Add an empty state with an illustration and 'No saved searches yet.
Save your first search to quickly re-apply filters.' message."

Open SaveSearchButton.tsx and select the handler:

Cmd+K: "Add validation — don't allow saving if no filters are active.
Show a tooltip explaining why the button is disabled."

Step 4: Test (Agent)

Agent: "Create comprehensive tests for the saved searches feature:
1. Unit tests for the API routes (mock Prisma)
2. Unit tests for the React Query hooks (mock fetch)
3. Component tests for SavedSearchList and SaveSearchButton
4. Follow patterns in src/features/wishlists/__tests__/

Run the tests after creating them and fix any failures."

Step 5: Review (Chat)

Chat: "Review the saved searches feature I just built.
Check for:
- Security (can users access other users' saved searches?)
- Performance (are there N+1 query issues?)
- Edge cases (what if a saved search references a deleted category?)
- Accessibility (keyboard navigation, screen reader support)

@src/features/saved-searches/
@src/app/api/saved-searches/"

Address any issues the AI identifies.

Step 6: Commit and PR

# Terminal
git add -A
# Use AI-generated commit message
git commit -m "feat: add saved searches feature..."
git push -u origin feature/saved-searches

Total time with Cursor: 45-60 minutes for a complete feature with tests and review. Without AI assistance: 3-4 hours for the same scope.

The multiplier comes from:

• Agent generating boilerplate correctly on the first try
• Agent writing tests that actually work
• AI catching security and performance issues before review
• Inline edits adding polish without context-switching