docs: rewrite the CLAUDE.md comment rule with explicit exceptions

[devin-ai-integration]

TLDR

Problem this solves:

• Blanket no-comments rule read as banning needed ones
• Agents skipped blame entries, suppressions, and TODOs
• Rule never said why comments are discouraged

How it solves it:

• Lists the three cases where comments are allowed
• Names AI slop as the thing being kept out
• Explains the rule as a DRY and tech debt concern

User Flow

Docs-only change to the agent guidelines, so there's no end user flow

Relevant issues

Linear ticket

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Tests aren't applicable here: the only change is prose in CLAUDE.md

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Prose-only edit to CLAUDE.md, nothing to run or capture

Type

📖 Documentation

Changes

CLAUDE.md now opens with the comment rule spelled out as a short list of allowed cases: concise explanations of genuinely complex business logic, comments tools read and act on (.git-blame-ignore-revs entries, lint or type checker suppressions like # mutable-ok for truly unavoidable violations), and TODO or FIXME markers that carry a strong, concise reason or link a follow-up issue. It closes with the reasoning, that the rule exists to keep out the excessive and verbose comments AI writes, and that comments duplicate logic in a second place and make code harder to change, so clear code beats explaining unclear code

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

Link to Devin session: https://app.devin.ai/sessions/9e264d2b82534afcb7be4d562cfca696
Requested by: @mateo-berri

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[greptile-apps]

Greptile Summary

This PR rewrites the repository’s agent guidance on code comments, replacing the blanket prohibition with explicit exceptions and rationale

• Permits concise comments for genuinely complex business logic
• Permits machine-significant comments used by tooling
• Permits TODO and FIXME markers when backed by a strong reason or follow-up issue

Confidence Score: 5/5

The PR appears safe to merge

No blocking failure remains

Important Files Changed

Filename	Overview
CLAUDE.md	Clarifies the comment policy and documents narrowly described exceptions without introducing an eligible follow-up defect

_{Reviews (5): Last reviewed commit: "chore: mention AI slop reason" | Re-trigger Greptile}

[devin-ai-integration]

@greptileai

[devin-ai-integration]

@greptileai

[mateo-berri]

@greptileai

[mateo-berri]

LGTM

[devin-ai-integration]

@greptileai

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!