i asked cursor to clean up a utility file. expected it to extract some constants, tighten up formatting. opened the file later and all the comments were gone.
went through the diff and cursor had stripped out comments about a deprecation timeline, a legal review warning, compliance notes, step-by-step explanations for a complicated auth flow. it kept a few JSDoc blocks and called it a day.
i tested it
took a file with 41 comment lines — JSDoc, inline explanations, JIRA references, compliance notes, etc. ran “clean up this code” three times.
only ~20% of comments survived. the model consistently killed JIRA references, date stamps, step-by-step explanations… anything it decided was “redundant.”
tried “refactor this code” instead — figured the phrasing might matter. ~28% survival. slightly better but not meaningfully different. both prompts treated comments as noise.
the fix
added a single .mdc rule:
---
description: preserve comments during code modifications
alwaysApply: true
---
Always preserve all existing code comments during refactoring, cleanup, and optimization.
same file, same “clean up this code” prompt, 3 more runs. 41 out of 41 comments survived every time. one run the model actually extracted magic numbers into named constants on top of preserving everything — it explicitly said “per your preserve-comments rule” in its response.
why this happens
without the rule, cursor treats “clean up” as “remove anything that looks like clutter.” and to an AI processing tokens, your compliance note IS clutter. it’s optimizing for what it thinks you want: cleaner, shorter code. the problem is “cleaner” and “well-documented” are sometimes opposites, and the model picks clean every time unless you tell it otherwise.
the diff just shows deleted lines. comments disappear and nobody notices until someone needs to understand why the code does what it does.
if you want the rule file, i keep it in a collection of tested .mdc rules on github. i also have cursor-lint checking that .mdc files don’t have broken frontmatter or missing alwaysApply — silent rule failures are their own kind of hell.