cursor in the wild

A full-repo refactor is using Cursor's Agent or Composer to make coordinated changes across many files in an existing codebase. Unlike greenfield generation where the AI writes from scratch, this requires the agent to understand the existing code, its dependencies, and its conventions before changing anything. The challenge is not generating code. It is generating the right changes in the right order without breaking what already works.

Cursor uses semantic indexing with embeddings stored in a vector database. It processes your files and builds a representation of your code's structure, imports, and relationships. Updates use Merkle trees so only changed files are re-indexed. For repositories over 100,000 files, use a .cursorignore file to exclude build artifacts, node_modules, and other non-source directories to keep the index focused and fast.

MDC (Markdown Configuration) files live in .cursor/rules/ and provide persistent project context to Cursor. Each file has YAML frontmatter with a description (what the rule does), globs (file patterns where it triggers), and alwaysApply (whether it loads on every interaction). They replaced the legacy monolithic .cursorrules file. Break rules into focused files by concern: one for your tech stack, one for coding patterns, one for deployment, one for safety boundaries.

Composer (specifically Composer 2.5 as of mid-2026) is optimized for multi-file edits where you need to see diffs immediately. Agent mode is for autonomous multi-step tasks that involve terminal commands, codebase search, and iterative execution. Use Composer when you know what changes you want and need to review each diff. Use Agent mode when the task requires exploration, testing, and multiple tool calls. Both can modify multiple files, but Agent mode has a wider blast radius.

Scope the task to a specific directory or set of files. Use @-mentions to provide only relevant files. State explicitly what is out of scope in your prompt. Set up rules files that define boundaries (directories the agent should not modify, patterns it should follow). Review every proposed diff before accepting. Stage commits after each bounded change so you can bisect later if something breaks.

Four main failure modes: stale index after file moves or renames (the agent references old paths), hallucinated imports (the agent invents modules that do not exist), silent behavioral drift in untested code paths (the code compiles and tests pass but semantics changed), and code reversion bugs where accepted changes are silently undone by auto-formatting or sync conflicts. Each requires a specific mitigation strategy.

The DDS Shopify theme refactor discipline uses pull-edit-push: pull the current file from the live MAIN theme as source of truth, make targeted edits using unique section or lane names as anchors (never positional matches), deploy to a staging theme first, verify rendered output against MAIN rather than trusting the tool's self-report, then promote to MAIN with a length-parity assertion. A rollback commit is always available.

Do not review 40 files at once. Stage commits after each logical slice (one feature, one module, one migration step). Review each slice independently. For each file, check: did the change match the intent, are imports valid, are there hardcoded values that should reference config, did the agent remove something it should not have. Use git bisect if something broke between slices. Treat Agent output like a junior developer's pull request: review every line.

Four categories: project architecture (tech stack, directory structure, key dependencies), coding patterns (naming conventions, component structure, state management patterns), safety boundaries (directories the agent should not modify, commands it should not run, files that require manual approval), and deployment constraints (environment variables, build steps, test requirements). Keep always-on rules under 500 lines. Use globs to scope rules to relevant files.

Four steps: inventory (list every file affected and its role), dependency map (which files import from which, what breaks if this file changes), ordered change plan (sequence changes so each step compiles and tests pass independently), execution in reviewable slices (implement one slice, commit, review, repeat). Write the plan as a document the agent can reference. Without a plan, the agent makes changes in an arbitrary order that often requires backtracking.

A .cursorignore file tells Cursor which files and directories to exclude from indexing. It uses the same glob syntax as .gitignore. Add build artifacts, node_modules, dist directories, log files, and any directories with sensitive data. This keeps the index focused on source code, reduces indexing time, and prevents the agent from wasting context on irrelevant files.

As of July 2026, Cursor offers tiered pricing: Hobby (free, limited usage), Pro ($20/month, full access to semantic search and frontier models), Pro+ ($60/month, for heavy daily agent use), Ultra ($200/month, maximum capacity), and Teams ($40/user/month, with admin controls and pooled usage). Annual billing typically provides a 20% discount. The free tier is sufficient for testing but not for sustained refactoring work.

Yes, with caveats. Cursor indexes Liquid files and can generate valid Liquid syntax. But Shopify sections have specific constraints: CSS must be scoped to a section ID, JavaScript must be in an IIFE, JSON schema blocks must parse, and Liquid tags inside code blocks need raw/endraw wrapping. Put these constraints in a rules file so the agent follows them automatically. Always deploy to a staging theme and verify rendered output before promoting to the live theme.

This is why staged commits matter. If you committed after each slice, run git bisect to find the exact commit that introduced the break. Revert to the last good commit and re-do the broken slice with a more constrained prompt. If you did not stage commits, you are reading through the entire diff manually. The discipline is: one slice, one commit, verify, next slice. It feels slower but it is faster than debugging a 40-file diff with no checkpoints.

Nothing. This masterclass is 100 percent free. No signup, no email, no paywall, no certificate requirement. It is part of the DDS Vibe Academy, a free AI coding curriculum built by Robert McCullock at Design Delight Studio.