claude-code - 💡(How to fix) Fix [BUG] System prompt rule 'Never write multi-paragraph docstrings... one short line max' breaks language-idiomatic API documentation [1 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

The Claude Code built-in system prompt contains the rule "Never write multi-paragraph docstrings or multi-line comment blocks - one short line max" (in the "Text output" section, under "In code"). Applied as written, this rule directly contradicts the documentation conventions of most major languages with structured doc systems: Go, Python (PEP 257), Java (Javadoc), C# (XML doc comments), Rust (rustdoc), and TypeScript (TSDoc). When Claude generates exported-API code in these languages and follows the rule, the resulting doc comments fail normal language idioms and code-review standards.

The Go case is especially sharp because the language's tooling actively enforces paragraph structure. gofmt normalizes godoc paragraphs (single blank // lines between them). The official Go Doc Comments specification at https://go.dev/doc/comment uses io.Copy's two-paragraph godoc as a canonical example. Language server gopls flags missing or non-conforming doc comments on exported declarations. A Go file with one-line-max godocs on every exported function is non-idiomatic by tooling standards, not just style preference.

The rule's intent is sound (preventing AI-generated narration that restates what code does), but the absolute "one short line max" formulation overshoots that intent and breaks language-idiomatic API documentation.

What Should Happen?

The rule should target what it actually means to prevent: AI narration that paraphrases what the code already says, and sprawling comment blocks on trivial declarations. It should not block language-idiomatic doc comments on exported APIs.

A possible reformulation: "Default to no comments. When a doc comment is warranted (for example, an exported declaration in a typed language with a documentation system), follow the language's idiomatic doc convention. Do not add commentary that restates what the code already says, and do not write multi-paragraph blocks for trivial declarations." This preserves the original anti-verbosity intent without breaking language standards.

Error Messages/Logs

N/A. This is a prompt-quality issue, not a runtime error. The symptom is silently substandard doc comments in generated Go, Python, Java, Rust, or TypeScript code.

Steps to Reproduce

1. Open a Go project (or Python, Java, Rust, TypeScript) in Claude Code with no project-level overrides.
2. Ask Claude to add a non-trivial exported function to a public package.
3. Observe that Claude produces either no doc comment or a one-line doc comment, even when the function is complex enough that idiomatic API docs would be multi-paragraph.
4. For Go specifically, compare against any function in the standard library (io.Copy, net/http.Handler, encoding/json.Marshal). The stdlib uses identifier-prefixed multi-paragraph godocs as the norm.

To confirm the rule is the cause, add an override in CLAUDE.md: "Godoc comments follow https://go.dev/doc/comment, including multi-paragraph structure when warranted." Re-prompt for the same function. Claude now produces idiomatic multi-paragraph godocs, confirming that the built-in rule was the constraint.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.119 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

iTerm2

Additional Information

The rule appears in the "Text output (does not apply to tool calls)" section of the system prompt, in the "In code:" sub-bullet. Full text:

 ▎ In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks - one short line max. Don't create planning, decision, or analysis
 ▎ documents unless the user asks for them - work from conversation context, not intermediate files.

The "default to no comments" portion is sound and aligns with the "Doing tasks" section's "only add a comment when the WHY is non-obvious" rule. The "one short line max" hard cap is the part that breaks down for typed-language API documentation.

References:

• Go Doc Comments specification: https://go.dev/doc/comment
• Python PEP 257: https://peps.python.org/pep-0257/
• Rust documentation conventions: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html

Workaround in use: a machine-level ~/.claude/CLAUDE.md override that scopes the one-line-max rule to non-godoc and non-docstring comments, and points to each language's idiomatic doc spec. This works locally, but every Claude Code user generating code in these languages would need the same override. Defaulting to substandard docs is a poor floor.