Skip to content

The open alternative to Salesforce, designed for AI.

Add comment-sparingly rules to CLAUDE.md (#28075)

Paul Rastoin76f03a9904ed
diff --git a/CLAUDE.md b/CLAUDE.md
index c13194f3027..0dd231f6187 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,6 +19,16 @@ Where this repo differs from your defaults:
- Import icons from `twenty-ui/icon`, never directly from `@tabler/icons-react`; action and status concepts should use their action or status icons.
- Test behavior, not implementation: query by user-visible text/roles, `@testing-library/user-event` for interactions.
+## Comment sparingly
+
+Most code is self-explanatory and a comment on it is just noise — cognitive overhead to read and maintenance debt to keep accurate. Only comment code that is genuinely unintuitive or complex: a non-obvious why , a workaround, a subtle invariant, a deliberate deviation from the obvious approach. Do not narrate what the code does — the code already says that. When a comment truly earns its place, keep it as terse as possible. This overrides matching the surrounding file's comment density. Write lean even in a verbose file.
+
+Two or three lines, and a hard ceiling of five. "Terse" is not relative: much of this repo predates the rule and carries paragraph-length comments, so a file you are editing is not evidence of the standard — it is usually the thing the rule exists to stop spreading. If the why will not fit in five lines, the explanation belongs in a module docstring, a README or an ADR, and the comment is one line pointing there.
+
+The same ceiling applies to a comment's neighbours: do not restate one fact in the Dockerfile, the manifest and the code that reads it. Put it once, where a reader hits it first, and let the others be silent.
+
+Docstrings carry the what and the design; they are not exempt from terseness, but they are the right home for anything a comment is too small to hold.
+
## Commands
```bash