Skip to main content

Cursor Workflow Guide

A structured development workflow adapted from the Claude Code + Speckit method, optimized for Cursor IDE.

Overview​

This workflow provides a systematic approach to feature development that:

  • Preserves context across development sessions
  • Reduces decision fatigue
  • Maintains consistency across features
  • Enables parallel development
  • Improves code review efficiency

The Two-Layer Architecture​

Layer 1: Project Context (CURSOR.md)​

What: The project's constitution - architecture, patterns, quality standards, and major design decisions.

When: Created once, updated only when major things change (architecture shifts, new tech stack additions, etc.)

Purpose: Single source of truth that Cursor automatically reads to maintain context.

Layer 2: Feature Specs (specs/)​

What: Tactical documentation for each feature - requirements, plans, and tasks.

When: Created for each new feature that warrants structured planning.

Purpose: Captures feature-specific context and guides implementation.

The 5-Step Workflow​

Step 1: Specify​

Create a feature specification that documents requirements and acceptance criteria.

How:

  1. Create a new numbered folder in specs/: specs/XXX-feature-name/
  2. Copy specs/templates/spec-template.md to specs/XXX-feature-name/spec.md
  3. Fill in the specification with:
    • User stories
    • Functional requirements
    • Acceptance criteria
    • Technical considerations

Prompt for Cursor:

Create a feature spec for: [Brief description of feature]

Example:

Create a feature spec for: User can reset password via email link

Step 2: Clarify​

Identify and resolve ambiguities in the specification.

How:

  1. Review the spec.md file
  2. Identify unclear requirements
  3. Ask questions or make decisions
  4. Update spec.md with clarifications

Prompt for Cursor:

Review specs/XXX-feature-name/spec.md and identify any ambiguities or questions that need clarification.

Common Clarifications:

  • Validation rules (client-side vs server-side)
  • Error handling behavior
  • Edge cases
  • Integration points
  • Performance requirements

Step 3: Plan​

Generate an implementation plan that aligns with project architecture.

How:

  1. Cursor reads both CURSOR.md and spec.md
  2. Creates plan.md following project patterns
  3. Documents implementation phases
  4. Makes technical decisions
  5. Identifies risks

Prompt for Cursor:

Generate an implementation plan for specs/XXX-feature-name/spec.md using the context from CURSOR.md.
The plan should follow our established architecture patterns and include implementation phases.

Step 4: Tasks​

Break down the plan into dependency-ordered tasks.

How:

  1. Cursor reads plan.md
  2. Creates tasks.md with ordered task list
  3. Identifies dependencies
  4. Marks parallel work opportunities

Prompt for Cursor:

Break down specs/XXX-feature-name/plan.md into dependency-ordered tasks.
Create tasks.md with clear dependencies and identify tasks that can be done in parallel.

Step 5: Implement​

Execute the tasks following project patterns and quality standards.

How:

  1. Cursor reads tasks.md, plan.md, spec.md, and CURSOR.md
  2. Implements tasks in order (or parallel where possible)
  3. Follows patterns from CURSOR.md
  4. Maintains code quality standards

Prompt for Cursor:

Implement the tasks from specs/XXX-feature-name/tasks.md.
Follow the patterns and conventions in CURSOR.md.
Reference spec.md for requirements and plan.md for architecture decisions.

Directory Structure​

flowpos-workspace/
├── CURSOR.md                          # Project context (read automatically by Cursor)
├── .cursorrules                       # Cursor behavior rules
├── specs/                             # Feature development specs
│   ├── templates/                     # Reusable templates
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   └── tasks-template.md
│   └── 001-feature-name/              # Numbered feature folders
│       ├── spec.md                    # Requirements
│       ├── plan.md                    # Implementation plan
│       ├── tasks.md                   # Dependency-ordered tasks
│       └── implementation.md          # (Optional) Notes during implementation
└── docs/                              # Reference documentation
    └── cursor-workflow-guide.md       # This file

When to Use This Workflow​

Use the Full Workflow For​

  • ✅ New features
  • ✅ Significant refactoring
  • ✅ Complex integrations
  • ✅ Architecture changes
  • ✅ Multi-developer features

Skip or Simplify For​

  • ❌ Small bug fixes
  • ❌ Trivial changes
  • ❌ Single-line fixes
  • ❌ Documentation-only updates

Guideline: If it takes less than 30 minutes to implement and review, you probably don't need the full workflow. Use your judgment.

Integration with Existing Documentation​

specs/ vs docs/​

specs/ (Feature Development):

  • Active development workflow
  • Feature-specific context
  • Implementation planning
  • Task tracking

docs/ (Reference Documentation):

  • Historical documentation
  • API references
  • Architecture deep-dives
  • User guides
  • Integration guides

Relationship:

  • specs/ guides active development
  • docs/ serves as reference and historical record
  • Some content may migrate from specs/ to docs/ after feature completion

Existing Feature Documentation​

Existing features (like FEL, PDF templates, etc.) have documentation in docs/. This is fine! The workflow is:

  • Forward-looking: New features can use the workflow
  • Optional: Existing documentation doesn't need migration
  • Complementary: Both structures serve different purposes

Maintaining CURSOR.md​

When to Update CURSOR.md​

Update only when major things change:

  • Major architecture shifts (e.g., monolith to microservices)
  • New technology additions (e.g., adding Redis)
  • Established conventions that affect all future development
  • Important design decisions impacting multiple features
  • Updated quality requirements (e.g., raising test coverage)

When NOT to Update CURSOR.md​

Don't update for:

  • Feature-specific decisions (use spec.md/plan.md instead)
  • Temporary changes
  • Experimental approaches
  • Small improvements

Rule of thumb: If it affects how you'll build the next 10 features, update CURSOR.md. Otherwise, document it in the feature spec.

Parallel Development​

The workflow supports parallel feature development:

specs/
├── 001-feature-a/
│   ├── spec.md
│   ├── plan.md
│   └── tasks.md
├── 002-feature-b/
│   ├── spec.md
│   ├── plan.md
│   └── tasks.md
└── 003-feature-c/
    ├── spec.md
    ├── plan.md
    └── tasks.md

Each feature has isolated specs. The only shared reference is CURSOR.md, which rarely changes. This enables:

  • Multiple developers working on different features
  • Cleaner code reviews (one feature = one spec folder)
  • Independent feature planning

Troubleshooting​

Cursor doesn't seem to read CURSOR.md​

  • Ensure CURSOR.md is at project root
  • Check that file name is exactly CURSOR.md (case-sensitive)
  • Cursor should automatically include it in context

Plan doesn't match project patterns​

  • CURSOR.md might be outdated - update it
  • Regenerate the plan after updating CURSOR.md
  • Explicitly reference CURSOR.md in your prompt

Tasks are too vague​

  • The plan might lack detail - edit plan.md to add more specifics
  • Regenerate tasks.md after refining the plan
  • Add more context about expected implementation approach

Don't know where to start​

  • Check existing features in specs/ for examples
  • Start with the spec template - even incomplete is better than nothing
  • Use the workflow prompts provided above

Feature conflicts with existing code​

  • Check CURSOR.md for architecture patterns
  • Review similar features in codebase
  • Update spec.md to document integration approach
  • Consider if CURSOR.md needs updating

Best Practices​

  1. Start Simple: Don't over-specify. Start with basic requirements and clarify as needed.

  2. Iterate on Specs: Specs are living documents. Update them as you learn more.

  3. Use Templates: Start with templates but customize as needed for your feature.

  4. Document Decisions: Use plan.md to document why you chose specific approaches.

  5. Update Status: Keep task status current in tasks.md for visibility.

  6. Reference Context: Always reference CURSOR.md when making architecture decisions.

  7. Preserve History: Don't delete specs/ folders - they serve as historical record.

Quick Reference​

Starting a New Feature​

1. mkdir specs/XXX-feature-name
2. cp specs/templates/spec-template.md specs/XXX-feature-name/spec.md
3. Fill in spec.md
4. Ask Cursor: "Generate implementation plan..."
5. Ask Cursor: "Break down into tasks..."
6. Ask Cursor: "Implement tasks..."

Key Prompts​

  • Specify: Create a feature spec for: [description]
  • Clarify: Review specs/XXX/spec.md and identify ambiguities
  • Plan: Generate implementation plan using CURSOR.md context
  • Tasks: Break plan.md into dependency-ordered tasks
  • Implement: Implement tasks.md following CURSOR.md patterns

Key Files​

  • CURSOR.md - Project context (read automatically)
  • .cursorrules - Cursor behavior rules
  • specs/templates/ - Starting point for new features
  • docs/cursor-workflow-guide.md - This guide

Examples​

Example 1: Password Reset Feature​

Spec: specs/010-password-reset/spec.md

  • User story: User can reset password via email
  • Requirements: Email validation, secure token, expiration
  • Acceptance: Email sent, token works, expires after 1 hour

Plan: specs/010-password-reset/plan.md

  • Phase 1: Backend token generation
  • Phase 2: Email service integration
  • Phase 3: Frontend reset form
  • Phase 4: Testing

Tasks: specs/010-password-reset/tasks.md

  • Task 1: Add password_reset_tokens table (no dependencies)
  • Task 2: Create token generation service (depends on Task 1)
  • Task 3: Email sending integration (depends on Task 2)
  • Task 4: Frontend form (parallel with Task 2)
  • Task 5: Integration and testing (depends on Task 3, Task 4)

Example 2: API Rate Limiting​

Spec: Documents rate limiting requirements, thresholds, error responses

Plan: Documents middleware approach, Redis integration, configuration

Tasks:

  1. Install rate limiting library
  2. Configure Redis connection
  3. Create middleware
  4. Add to routes
  5. Test with various scenarios

Getting Started​

  1. Read CURSOR.md - Understand project context
  2. Review this guide - Understand the workflow
  3. Try with a small feature - Get familiar with the process
  4. Refine as you go - Adjust templates and process to fit your needs

Support​

For questions or improvements:

  • Check existing specs for examples
  • Review CURSOR.md for patterns
  • Update templates based on your needs
  • Share learnings with the team

Last Updated: 2025-01-27 Version: 1.0