Skip to content

Commit 47cf864

Browse files
authored
docs: add root CLAUDE.md rule reducing AI-ism jargon (#23114)
## Summary Adds a `<jargon>` section to root `CLAUDE.md` discouraging recurring Claude/Codex AI-isms — *load bearing*, *seam*, *north star*, *sharpening*, and reflexive agreement openers like *"You're absolutely right"* — with concrete substitutes for each. ## Why These phrases read as filler / inflated weight and are contagious — they leak into PR descriptions and Slack replies once they appear. Plain English (*important*, *interface*, *goal*, *adding detail*) communicates better. Raised in #team-engineering after multiple complaints. ## Notes - Inserted as a single tagged section to match the existing root `CLAUDE.md` style (and pass the `<editorial_test>` gate — each item maps to a specific recurring offense). - Rebased onto fresh `origin/next` after the original PR base was an old commit.
2 parents 20fd178 + 78da34c commit 47cf864

1 file changed

Lines changed: 10 additions & 0 deletions

File tree

CLAUDE.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,16 @@ Do not explain *what* the code does — well-named identifiers cover that. Comme
107107
Do not reference the current task, PR, caller, or author (`// used by X`, `// fix for issue #123`, `// AI-generated`), and do not add banner-style section comments (`// ===== HELPERS =====`). Both rot the moment the surrounding code is moved.
108108
</writing_comments>
109109

110+
<jargon>
111+
Avoid recurring AI-isms in chat replies, PR descriptions, commit messages, code comments, and docs. Substitutes:
112+
113+
- **"load bearing"***important*, *critical*, *required*, or describe the actual dependency (e.g. "the scheduler relies on this invariant").
114+
- **"seam"** (for an interaction point or boundary) → *interface*, *boundary*, *call site*, *integration point*.
115+
- **"north star"***goal*, *main goal*, *objective*.
116+
- **"sharpening"** (for adding detail or refining wording) → *clarifying*, *adding detail*, *tightening*, *refining*.
117+
- **"You're absolutely right"** and effusive agreement openers (*"Great catch!"*, *"Excellent point!"*) → never lead a reply with these. A short acknowledgement (*"Right — …"*, *"Agreed."*) is fine, and a closing *"you're right"* at the end of a long reply is acceptable when warranted. Lead with substance, not validation.
118+
</jargon>
119+
110120
<attribution>
111121
Attribute work to the git author, not to Claude. Do not add `Co-Authored-By: Claude` trailers or `Generated with Claude Code` in PR descriptions. The git author (from `git config user.name`) is the author of record.
112122
</attribution>

0 commit comments

Comments
 (0)