Designed for Claude Code, also compatible with Codex and OpenClaw
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.
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":
Read every diff -- do not blindly apply multi-file changes
Check imports -- Composer sometimes generates wrong import paths
Verify types -- ensure type annotations are correct, not any
Look for hallucinations -- methods or modules that do not exist
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:-AlwaysincludeJSDoccommentsonexportedfunctions-Alwaysadderrorhandling(neverletfunctionsthrowunhandled)-Generatecorrespondingtestfilesfornewmodules-Usenamedexports,neverdefaultexports-Importtypeswith`importtype`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
