Cursor Advanced Composer

Advanced patterns for Cursor Composer including agent orchestration, complex multi-file refactoring, architecture migrations, and quality-control workflows.

Agent Mode Deep Dive

In Agent mode, Composer autonomously chains tool calls: reading files, searching the codebase, running terminal commands, and writing code. It operates in a loop until the task is complete or it hits the 25-tool-call limit.

Agent Tool Capabilities

Tool	What it does	Approval needed?
Read file	Reads any file in workspace	No
Search codebase	Semantic + text search	No
Write file	Creates or overwrites files	Shows diff first
Edit file	Modifies sections of files	Shows diff first
Run terminal command	Executes shell commands	Yes (click Allow)
List directory	Browses folder structure	No

Controlling Agent Behavior

Give the agent constraints in your prompt:

Migrate all React class components in src/components/ to functional
components with hooks.

Constraints:
- Do NOT modify test files
- Preserve all existing prop types
- Replace lifecycle methods with useEffect equivalents
- Keep the same file names and export structure
- Run `npm test` after each file to verify

Checkpoint Pattern

For large refactors, use explicit checkpoints:

Phase 1: Create the new database schema types in src/types/schema-v2.ts.
         Show me the types before proceeding.

Phase 2: Update the repository layer to use the new types.
         Run tests after each repository file change.

Phase 3: Update the API routes to use the new repository methods.

Phase 4: Update the frontend components to match the new API response shapes.

Stop after each phase and show me a summary of changes.

The agent pauses after 25 tool calls automatically. Click "Continue" to allow more.

Parallel Agent Workflows

Run up to 8 Composer agents simultaneously, each in its own tab.

Use Case: Parallel Feature Development

# Agent 1 (Tab: "Auth")
Implement JWT authentication:
- src/middleware/auth.ts
- src/services/token.service.ts
- src/api/auth/login/route.ts
- src/api/auth/refresh/route.ts

# Agent 2 (Tab: "Products")
Implement product catalog:
- prisma/schema additions
- src/api/products/route.ts
- src/services/product.service.ts

# Agent 3 (Tab: "Tests")
Write integration tests for the existing user API:
- tests/integration/users.test.ts

Each agent has its own context and conversation history. They can modify the same codebase simultaneously, but be careful with overlapping files.

Conflict Resolution Between Agents

If two agents modify the same file, the second write overwrites the first. Mitigate this by:

• Assigning non-overlapping file scopes to each agent
• Running agents sequentially for shared files
• Using git to cherry-pick the best changes

Complex Refactoring Patterns

Pattern: Extract and Replace

Extract a pattern into a shared utility, then replace all occurrences:

@src/api/

I see repeated error handling in every API route:
try { ... } catch (err) { if (err instanceof ZodError) ... }

Step 1: Create src/utils/api-handler.ts with a withValidation()
wrapper that handles the try/catch + Zod pattern.

Step 2: Update ALL route files in src/api/ to use withValidation()
instead of manual try/catch.

Show me api-handler.ts first, then refactor the routes.

Pattern: Interface-First Migration

Define the target interface, then migrate implementations:

@src/services/

Step 1: Create src/interfaces/repository.ts with a generic
Repository<T> interface:
  - findById(id: string): Promise<T | null>
  - findMany(filter: Filter<T>): Promise<T[]>
  - create(data: CreateInput<T>): Promise<T>
  - update(id: string, data: UpdateInput<T>): Promise<T>
  - delete(id: string): Promise<void>

Step 2: Refactor UserService to implement Repository<User>.
Step 3: Refactor ProductService to implement Repository<Product>.
Step 4: Update API routes to use the Repository interface type.

Pattern: Test-Driven Refactoring

Write tests first, then refactor with confidence:

@src/services/payment.service.ts

Step 1: Write comprehensive tests for the current PaymentService
behavior. Cover all public methods and edge cases.
Run `npm test` to verify they pass.

Step 2: Refactor PaymentService to use the Strategy pattern for
different payment providers (Stripe, PayPal, manual).
Run `npm test` after each change to ensure nothing breaks.

Multi-Codebase Orchestration

For monorepos or multi-root workspaces:

@packages/shared/src/types/
@packages/api/src/routes/
@packages/web/src/hooks/

Add a "notifications" feature across all packages:
1. shared: NotificationType enum, Notification interface
2. api: GET /notifications, POST /notifications/mark-read endpoints
3. web: useNotifications hook, NotificationBell component

Use the shared types in both api and web packages.
Import from @myorg/shared (the workspace alias).

Quality Control Workflows

Pre-Apply Review Checklist

Before clicking "Apply All":

1. Read every diff -- do not blindly apply multi-file changes
2. Check imports -- Composer sometimes generates wrong import paths
3. Verify types -- ensure type annotations are correct, not any
4. Look for hallucinations -- methods or modules that do not exist
5. Run build -- `Cmd+`` > run your build command after applying

Post-Apply Validation

# In Composer or terminal:
npm run build       # Catches import errors, type mismatches
npm run lint        # Catches style violations
npm run test        # Catches behavior regressions

Rollback Strategy

If applied changes break the build:

# Undo all uncommitted changes
git checkout .

# Or selectively undo specific files
git checkout -- src/api/products/route.ts

Always commit working code before starting a Composer session.

Advanced Prompting Techniques

System-Level Instructions via Rules

Create a Composer-specific rule:

# .cursor/rules/composer-standards.mdc
---
description: "Standards for Composer-generated code"
globs: ""
alwaysApply: true
---
When generating code via Composer:
- Always include JSDoc comments on exported functions
- Always add error handling (never let functions throw unhandled)
- Generate corresponding test files for new modules
- Use named exports, never default exports
- Import types with `import type` syntax

Iterative Refinement

After first pass:

The generated product.service.ts looks good but:
1. Add pagination support to findMany (page, limit params)
2. Add a findByCategory method
3. Use transactions for createWithItems

Composer retains conversation context, so follow-up instructions build on previous output.

Enterprise Considerations

• Compliance: Review generated code for license compliance before committing
• Security: Composer may generate code with SQL injection or XSS vulnerabilities -- always audit
• Cost: Agent mode with reasoning models (o1, Opus) can consume thousands of tokens per session
• Audit trail: Commit Composer output with descriptive messages for code review traceability

Resources

• Composer Overview
• Agent Mode Documentation
• Cursor 2.0 Agent Architecture