{
  "$schema": "https://promptfoo.tech/schemas/workflow-template.json",
  "name": "Cursor: The Plan-File Refactor Pattern for Large Changes",
  "slug": "cursor-refactor-with-plan-file",
  "platform": "Cursor",
  "category": "coding",
  "difficulty": "Intermediate",
  "tags": [
    "cursor",
    "coding",
    "refactor",
    "ai-agents"
  ],
  "summary": "Stop letting Cursor sprawl across 40 files. This pattern uses a versioned plan.md to keep long refactors on the rails.",
  "overview": "Cursor's agent mode is fantastic for scoped edits and dangerous for wide refactors — it happily rewrites 40 files when you meant 4. The plan-file pattern gates every change through a versioned markdown plan you review before code moves. It's the difference between a shippable refactor and a 3-hour cleanup PR.",
  "variables": {},
  "steps": [
    {
      "order": 1,
      "name": "Write the intent paragraph",
      "description": "One paragraph, in your voice, describing what changes and why. This becomes the top of plan.md and the PR description."
    },
    {
      "order": 2,
      "name": "Ask for a plan, not code",
      "description": "Prompt: 'Draft a plan.md that lists every file to change and the intent per file. Do not write code yet.' Cursor obeys explicit refusals."
    },
    {
      "order": 3,
      "name": "Prune ruthlessly",
      "description": "Delete any file where the intent is 'update to match' — that's an implicit dependency you should verify separately, not a real change."
    },
    {
      "order": 4,
      "name": "Add acceptance criteria per section",
      "description": "Each plan section gets a 'done when' line. Cursor uses these as its stop condition, which prevents over-editing."
    },
    {
      "order": 5,
      "name": "Execute one section at a time",
      "description": "Prompt: 'Execute Section 2 only.' Review the diff. Only then approve Section 3. Never let Cursor batch-execute the full plan."
    },
    {
      "order": 6,
      "name": "Commit the plan",
      "description": "Include plan.md in the PR. Future you (and your reviewers) will thank you."
    }
  ],
  "howItWorks": [
    "You write a one-paragraph description of the refactor and ask Cursor to draft a plan.md, not code.",
    "The plan lists every file to touch, the intent per file, and the acceptance test.",
    "You edit the plan aggressively — deleting scope, tightening intent, adding tests.",
    "Cursor executes one plan section at a time; you approve each diff before moving on.",
    "The plan file stays in the PR as documentation of intent."
  ],
  "benefits": [
    "Prevents scope creep — you see the sprawl before Cursor writes it.",
    "Makes review painless — reviewers read the plan, then verify each section.",
    "Turns AI edits into auditable history."
  ],
  "useCases": [
    "Renaming a core abstraction across a codebase.",
    "Migrating from one library to another (e.g., moment → date-fns).",
    "Splitting a god-file into focused modules."
  ],
  "example": "plan.md excerpt: '### 3. src/api/users.ts\\nIntent: Replace direct DB calls with the new UserRepo.\\nDone when: All three route handlers use userRepo.get/create/update and tests pass unchanged.'",
  "faqs": [
    {
      "q": "What if Cursor edits files outside the plan?",
      "a": "Reject the diff and re-prompt with 'Only edit files listed in plan.md Section N.' If it happens twice, switch models."
    },
    {
      "q": "Does this work for greenfield code?",
      "a": "It's overkill for greenfield. Use it for refactors, migrations, and any change touching >5 existing files."
    },
    {
      "q": "Can I use this with Claude Code or Copilot Chat?",
      "a": "Yes, the pattern is model-agnostic. Any agent that respects explicit stop conditions works."
    }
  ],
  "source": "https://promptfoo.tech/workflows/cursor-refactor-with-plan-file",
  "updated": "2026-06-05",
  "license": "CC-BY-4.0"
}