cursor-advanced-composer

# 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:

```bash
# 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:

```yaml
# .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](https://docs.cursor.com/composer/overview)
- [Agent Mode Documentation](https://docs.cursor.com/agent)
- [Cursor 2.0 Agent Architecture](https://cursor.com/blog)