tomevault-io Cursor Composer Workflows
Master Cursor Composer (Cmd+I / Ctrl+I) for multi-file code generation, scaffolding, and coordinated refactoring. Composer is the primary tool for changes that span multiple files.
Composer Interface
┌─────────────────────────────────────────────────────────┐
│ Composer [Model ▾] │
│─────────────────────────────────────────────────────────│
│ Context: [src/api/] [prisma/schema.prisma] │
│─────────────────────────────────────────────────────────│
│ Create a CRUD API for products with: │
│ - Prisma model with id, name, price, category │
│ - API routes (GET list, GET by id, POST, PUT, DELETE) │
│ - Zod validation schemas │
│ - Unit tests with vitest │
│─────────────────────────────────────────────────────────│
│ ┌─ Changes ──────────────────────────────────────────┐ │
│ │ ✅ prisma/schema.prisma (+12 lines) │ │
│ │ ✅ src/api/products/route.ts (new file) │ │
│ │ ✅ src/api/products/[id]/route.ts (new file) │ │
│ │ ✅ src/schemas/product.ts (new file) │ │
│ │ ✅ tests/api/products.test.ts (new file) │ │
│ └────────────────────────────────────────────────────┘ │
│ [Apply All] [Review Changes] [Reject] │
└─────────────────────────────────────────────────────────┘
Core Workflow Patterns
1. Feature Scaffolding
Generate a complete feature across multiple files:
@src/api/users/route.ts @prisma/schema.prisma
Create a complete "orders" feature following the same patterns as users:
1. Prisma model: Order (id, userId, items, total, status, createdAt)
2. OrderItem model: (id, orderId, productId, quantity, price)
3. API routes: GET /api/orders, GET /api/orders/[id], POST /api/orders
4. Zod validation schemas matching the Prisma models
5. Service layer with createOrder, getOrders, getOrderById
Composer reads the referenced files to replicate the existing pattern.
2. Cross-File Refactoring
Rename, restructure, or migrate patterns across the codebase:
@src/services/ @src/api/
Refactor all service functions to use a Result type instead of throwing errors.
Current pattern:
async function getUser(id: string): Promise<User> { throw new NotFoundError(); }
Target pattern:
async function getUser(id: string): Promise<Result<User, NotFoundError>> { ... }
Update all callers in the API routes to handle the Result type.
3. Test Generation
Generate tests that match existing test patterns:
@tests/api/users.test.ts @src/api/products/route.ts
Generate vitest tests for the products API following the same patterns
as users.test.ts. Cover:
- GET /api/products returns list with pagination
- GET /api/products/[id] returns 404 for missing product
- POST /api/products validates required fields
- POST /api/products returns 201 with created product
Use the same mock setup and assertion patterns.
4. Migration / Upgrade
Apply systematic changes across many files:
@src/components/
Migrate all components from CSS Modules to Tailwind CSS:
- Replace className={styles.container} with className="..."
- Map existing CSS properties to Tailwind utilities
- Remove the .module.css import and file
- Preserve responsive breakpoints and dark mode support
Agent Mode
Composer can operate in Agent mode, which autonomously executes multi-step tasks:
- Reads and searches files without explicit @-mentions
- Runs terminal commands (with your approval)
- Chains multiple tool calls (up to 25 before pausing)
- Makes decisions about which files to modify
Agent mode activates by default in Cursor 2.0. It is best for open-ended tasks where you describe the goal but not every step.
Parallel Agents
Run up to 8 agents simultaneously, each in its own Composer tab. Useful for:
- Working on unrelated features in parallel
- Exploring different implementation approaches
- Running tests in one agent while coding in another
Diff Review and Application
Before applying changes, Composer shows a complete diff for each file:
// prisma/schema.prisma
+ model Order {
+ id String @id @default(cuid())
+ userId String
+ user User @relation(fields: [userId], references: [id])
+ items OrderItem[]
+ total Int
+ status OrderStatus @default(PENDING)
+ createdAt DateTime @default(now())
+ }
+
+ enum OrderStatus {
+ PENDING
+ CONFIRMED
+ SHIPPED
+ DELIVERED
+ CANCELLED
+ }
Review workflow:
- Click each file in the Changes panel to see its diff
- Accept individual files or
Apply All - After applying, run your build/tests before committing
- If something is wrong,
Cmd+Zundoes the last applied change
Composer Prompting Best Practices
Be Specific About File Structure
# BAD
Create a blog feature
# GOOD
Create a blog feature with these files:
- src/api/posts/route.ts (GET list with pagination, POST create)
- src/api/posts/[slug]/route.ts (GET by slug, PUT update, DELETE)
- src/types/post.ts (Post interface, CreatePostInput, UpdatePostInput)
- src/services/post.service.ts (PostService class with Prisma operations)
Reference Existing Patterns
# BAD
Add authentication middleware
# GOOD
@src/middleware/rateLimit.ts
Add authentication middleware in src/middleware/auth.ts following
the same middleware pattern: export a function that returns NextResponse,
use the same error response format, add the same type annotations.
Incremental Over Monolithic
Instead of one massive prompt, break into steps:
- "Create the Prisma models and run prisma generate"
- "Create the service layer with CRUD operations"
- "Create the API routes that use the service"
- "Add validation schemas and wire them into the routes"
- "Generate tests for the service and routes"
Each step can reference the output of the previous step.
Enterprise Considerations
- Code review before apply: Always review diffs. Composer can hallucinate imports or use wrong patterns.
- Version control: Commit before running Composer on existing code. Easy rollback with
git checkout . - Team standards: Use
.cursor/rules/to encode patterns so Composer follows team conventions - Cost awareness: Composer uses premium model tokens. Complex multi-file prompts consume significant context.
Resources
Converted and distributed by TomeVault — claim your Tome and manage your conversions.