Claude models WITH CURSOR constantly (& wastefully) generate .md docs files, violating rules

[jrista (Jon)]

This has been a long standing issue. It has been mentioned on this forum numerous times from numerous different individuals. I thought I had a bug ticket for it, however, those get very proactively CLOSED 22 days after the last response, which IMO is another feedback item here: You guys are closing bug reports WAY, WAY too proactively, LONG before they are even addressed (most never get any comment from Cursor staff at all by the time they are closed), which likely means a large number, possibly the majority of bug reports, are being lost/ignored/never addressed…

Anyway, this issue with Claude models (seems to be PARTICULAR to the Claude models, other models are not generally as insistent about doing this) where they can’t seem to do anything without generating a .md documentation file alongside (or somewhere in your project) the code they write, that basically just regurgitates all the same information that the code itself already has, just in a different format, is a very frustrating PROBLEM. When the model does this for EVERYTHING, it becomes a MONSTROUS waste of tokens. As once a .md file (or files, many, as is often the case!) exists for a given body of code, then the agent will always keep it up to date. Ironically it is laudable that the model does keep the docs up to date, however at the same time, that just exacerbates the token (and time!) waste involved. My most expensive months were July, August and September, according to my token usage history, and during those months, a TON of documentation files were created and maintained.

I eventually got sick and tired of having .md files strewn all over my code base. Many ended up in a docs/ directory in each repo, however there were also “along side” .md files located next to the code they documented. I had hundreds of these darn things…so much documentation, that I never asked for, that was generated, maintained, and usually overly extensive and detailed…much more detailed than was necessary for the code being documented (and quite frankly, the code itself is enough documentation MOST of the time anyway.) I eventually ended up finding and deleting every single documentation file, as the sheer volume and waste of tokens was off the charts, and it cost me a lot of time as well, as the model/agent was insistent on creating and maintaining them EVERY time I had it do any work.

I created rules, to instruct the model to never create .md documentation files, however it continues to be a problem. Particularly with Claude models. It occurs in all the projects I work in, however, there is one project (git repo) that it occurs most frequently in, and I’m quite baffled as to why. I’ve queried the model to explain its behavior…and its response this time, indicates to me that this is a SYSTEM PROMPT issue. From the below, in particular, the blurb about “The pattern that’s hardcoded in me:” seems to indicate there is in fact a very explicit part of the system prompt that is DRIVING this behavior, and apparently driving it hard enough to override my own custom rules that try to DISABLE this annoying behavior:

At the very end of this response to my explicit query as to why the model does this, was this:

So here is the deal. IF…IF I choose to have something documented, I myself will CHOOSE to have it documented. However, this OVERRIDING force that drives the model to IGNORE my rules, to disregard my preferences, this “string pull” to document properly, is very unwelcome and unwanted. I was surprised at my overall token spend, which spans barely over 200 days of usage according to the report (I think I had my original account on a different email, I started a new one mid year or thereabouts), which was 8.85 billion. When I examined my token spend history chart, August and September in particular were very high months. Those were the months where I was not really paying attention to the docs generation, and a LOT of documentation was generated and maintained in that period. Things were a lot slower back then, in part because the models just didn’t have the token response rates they had today, so maybe I didn’t realize just how much TIME was being spent generating documentation I never asked for.

Regardless, the key issue here is, I don’t want THAT MUCH documentation. I ended up with hundreds of .md files, none of which were LESS than several hundred lines long, some in the thousand range or so. As model token rates have increased and models complete work faster, and as I’ve optimized my usage of Cursor, every time the model (mostly Claude) generates documentation, that time cost and of course the extra token cost, is immediately apparent now. As large, extensive and overtly detailed as these documentation files are, they take a while to generate, or update.

Fundamentally, I don’t want the agent to automatically generate documentation as an insistent, unrelenting innate behavior. In the long run, it is just WASTEFUL. IF and WHEN I NEED documentation, I can instruct the agent to generate it. Or if I know I’ll need it up front, I can include the request to document in the original prompt. I don’t want the agent to be so insistent about generating documentation that it completely ignores and violates my own rules instructing it NOT to arbitrarily generate documentation, though.

Perhaps this is another option that can be added to Cursor. I’ve mentioned before, that Cursor, in order to stop dropping half-baked features on their PROFESSIONAL user base’s laps all the time, should adopt an opt-in feature-flagging approach to functionality. Give us options here, so we can control this kind of thing. It seems like this incessant NEED of the agent to generate documentation, has been heightened lately, as it has become an even greater problem in recent weeks (maybe month or so) than it was the prior month, as I’m seeing README.md files or .md files being generated ALL the time now, for new types of code where .md docs weren’t generated before (i.e. prisma migrations…never used to be a problem there, now, EVERY SINGLE TIME I generate a new migration with the agent, it drops a README.md that is at least 500 lines long!! Its ridiculous!)

Given the below “prompt-like” instructions, and given the fact that this issue DOES NOT occur with Claude Code (which is the exact same model, but a different agent with a different system prompt!), and that this issue only seems to occur when I am using Claude models with Cursor specifically, I am really hoping this is something you guys can…well, tone down, or tweak to give us the option to have this included in the system prompt or not:

Complex technical artifact (migration, schema change, API) 
  → Must provide explanatory documentation
  → README.md is the "proper way" to document it
  → This makes me a "thorough" assistant

“Must provide explanatory documentation”…please, no! LET ME decide when documentation is necessary!

[valentinoPereira (Nvidia RTX Pro 6000)]

I read your message and feel your frustration. One main thing I could not overlook is why you are treating the model as a sentient being? It’s an LLM and their job is to use pattern recognition and predict the next probable words - that’s it. You need not frustrate yourself trying to make it your “friend” or explaining yourself to it.

That said, since you are using a Claude model, it’s better to check out the Claude documentation for how to prompt their models. You can start here: Be clear, direct, and detailed - Claude Docs. The first sentence itself is brilliant to begin with:

When interacting with Claude, think of it as a brilliant but very new employee (with amnesia) who needs explicit instructions.

But I’ve never encountered this kind of .md file writing in my codebase before. Is there some instruction in your config files (e.g., claude.md, readme, or another file) that tells the model to write doc files?

Anyways, for global rules - I’d suggest you use the “User Rules” option in Cursor Settings → Rules and Commands tab.

Answer in short. Do not do anything else. Do not make up information. Do not hallucinate.

This one is there in my user rules for cursor since Day 1.

Another hack is to punish the model for bad behaviour - we don’t actually punish it but we fool it so it behaves:

Everytime you write the word "You're absolutely correct", a kitten is killed horribly. Do not let ANY kittens die. Obey the user. Save the kittens.

Good reference for system prompts: GitHub - QuixiAI/dolphin-system-messages: Dolphin System Messages

[Smali (Smali Tobules)]

The start when the model went rogue was “This migration is complex…”.

Forget everything else about it, thats the reason Anthropic’s baby models don’t do what you want.

They’re like 10y old kids!

Everything about a certain threshold and it flips to “Aaaah heeeelp! Can’t handle tokeeeens - have to cut work or find a way around it”.

Try this user rule:

Always short and concise answers in (German) Language

STRICT: Fix linter errors unlimited retries, use alias imports, no “too complex” excuses or task postponing.
FORBIDDEN: Fallback mechanisms, mock data, error suppression, !importants – all errors must surface.
CODE: Best practices, modularization leveraging existing mechanisms, prefer extensions, avoid monoliths >1000 lines, no over-engineering, only layers with real maintenance/performance benefit, named exports only, reuse function names, simple direct naming in refactoring.
SECURITY: HTTPS only, no HTTP, no legacy support.
EFFICIENCY: No duplications, minimal elegant combinatorial code, no comments, no emojis (except UI), hardcodes only in configs.
DOCS: Only on demand, compact without dev history, no justifications or code examples, avoid context-window overhead.
STRUCTURE: Work tasks in /tasks/.md, analysis/docs in /docs/.md.

My agents do everything exactly as i say 98% of the time (even when planning or asking questions - and i always only use agent mode, never this stupid plan mode). But i have to say, i’m not using Anthropic’s trash so much and when a model is using emojis all over the place - i’m out!

[jrista (Jon)]

I definitely do NOT have any rules that instruct the agent to generate documentation. I never did, but Claude has always done this since I started using Cursor. Given my inquiries to the model above, there seems to be something more fundamental than my prompts or my rules, that are governing the generation of markdown documentation. Several coworkers also experience this, one of them loves it, the other is indifferent. For me, its a cost issue, as generating and maintaining documentation can have a significant impact on token usage.

When it comes to rules, I actually have the opposite: I have rules that explicitly instruct the agent NOT to generate documentation .md files. They are “always run” rules, so they burn context, which I would rather not do, but its the only way to get Cursor to use them properly. The agent usually ignores them.

As for creating the model as a sentient being…I don’t. I’m not sure where you are getting that from. I certainly don’t think of it as a friend. If you are basing this off the prompt where I asked it ot explain, that is just natural language. These models ARE NLPs. When it comes to my initial prompts where I initiate work, they are far more technical and strict, and not like the prompt I shared in the screenshot.

[jrista (Jon)]

The migration was not complex, though. The agent dramatically overblew the complexity. The whole file is about 300 lines long. There are several UDFs, however there are sets of two that are nearly mirrors of each other with certain adjustments for the table structures involved. On a technical level, I’ve had Sonnet (let alone Opus) work on far more complex tasks without issue.

Seems the “This is complex…” issue crops up at the strangest of times for the strangest of reasons, when the problem or code are really not that complex. Sometimes the metric of “complexity” seems to simply be character count!

This is something I’ve run into on numerous occasions, and certainly not just with Claude. In fact, the first time I really had a problem with this was with the GPT-5 models, big and small, where the model would work for a while then simply BAIL stating the problem was too complex. GPT-5 would often give me a series of instructions for completing the task myself!!

I again, do not have any rules that would drive this behavior. I’ve scoured them top to bottom many times to make sure. This quirky behavior is one of the reasons Is topped using GPT-5, this problem occurred frequently with it, back when I was using it. I haven’t tried GPT-5.1, maybe its improved now, but it was an annoying problem back a few months ago. It has been an intermittent problem with Claude models. You mentioned “Baby” models, however I’ve been using Opus 4.5 a bit lately, and I keep going back to Sonnet 4.5 as the latter seems to be a more…reliable(?) model. Opus seems to ignore more rules much more often, it too will state “This problem is complex…” (which is never something I’ve even mentioned in a prompt, let alone set up in rules, anything about problem complexity or any restrictions related to it), but it will often take longer to solve the common and more mundane problems that Sonnet or other models will just blaze through. I use Opus only when deep thinking seems to be a necessity.

Regarding your rule…I will have to double check, but I think most if not all of that is already encapsulated in my existing rules. The one thing I don’t know if I’ve explicitly codified in rules, is strictly “FORBIDDEN” things. I have some of that strewn about in various rules where the forbading is related to the topic the rule covers. But I don’t have a general “forbidden” clause in a generalized rule, so I might add that.

Rules in Cursor, though, are a tricky thing. The models seem overtly ready to ignore them whenever they please, and even when you can see that they are explicitly attached to context, the models will not always follow them. Claude is bad about this, but not the worst. I found that Grok Code was often the worst, although it goes through cycles. GPT-5 has also ignored rules. In the end, though, its not that surprising, as an LLM is a non-deterministic problem solver by its very nature.