claude-code - 💡(How to fix) Fix [Bug] System prompt aggressively removes necessary docstrings explaining non-obvious code behavior [1 comments, 2 participants]

Bug Description the system prompt is destructive to existing code base comments. See this transcript:

You were right — I over-applied the "no comments" guidance. Source precedence and raise conditions are exactly the non-obvious WHY that belongs in a docstring.

❯ where was the "no comments" guidance from?

● From my Claude Code system prompt — not from you or any CLAUDE.md in this repo. The built-in instructions include lines like "Default to writing no comments. Only add one when the WHY is non-obvious..." and "Never write multi-paragraph docstrings or multi-line comment blocks — one short line max."

I misapplied it: the guidance says keep comments/docstrings that explain non-obvious WHY (hidden constraints, surprising behavior) — the source-precedence order and raise conditions on _load_openweather_settings fit that exactly, so they should've stayed. Sorry for the churn.

❯ the system prompt or the /simplify plugin prompt?

● Both, actually.

• System prompt has it as a general rule: "Default to writing no comments... Never write multi-paragraph docstrings or multi-line comment blocks — one short line max."
• /simplify reinforces it in Agent 2's checklist as item #8 ("Unnecessary comments: ... delete; keep only non-obvious WHY").

The immediate trigger was Agent 2 flagging the docstrings as "longer than their bodies" during the review, but the underlying rule is baked into the system prompt too. I applied both too aggressively — in this case the docstrings described non-obvious WHY (source precedence, raise conditions) and should have been kept.

Environment Info

• Platform: win32
• Terminal: vscode
• Version: 2.1.118
• Feedback ID: ee3e6b51-78c7-4ce0-89cb-4b9db93412eb

<img width="2016" height="563" alt="Image" src="https://github.com/user-attachments/assets/7f9ec0b1-f8d0-458f-b263-8e149207c216" />