diff --git a/packages/agents/content/skills/_data/naming-conventions.md b/packages/agents/content/skills/_data/naming-conventions.md new file mode 100644 index 00000000..0d3a07d4 --- /dev/null +++ b/packages/agents/content/skills/_data/naming-conventions.md @@ -0,0 +1,33 @@ +# Naming conventions + +## No abbreviations + +Use full words. Abbreviations save keystrokes but cost comprehension. + +- ✅ `position`, `request`, `response`, `configuration`, `message` +- ❌ `pos`, `req`, `res`, `config`, `msg` + +**Exception:** trivial predicate callbacks where the variable is used once and the type is obvious: `.map(c => c.trim())`, `.filter(n => n > 0)`. + +## Unit-of-measure suffixes + +Numeric variables must include the unit as a suffix. Abbreviations are fine when clearly understandable. + +- ✅ `durationMs`, `timeoutMs`, `delaySec`, `CELL_HEIGHT_PX`, `fontSizeRem` +- ❌ `duration`, `timeout`, `delay`, `CELL_HEIGHT`, `fontSize` + +## Verb-led function names + +Functions start with a transitive verb that describes the action. + +- ✅ `fetchResults`, `buildPayload`, `resolveColor`, `parseCommitTitle` +- ❌ `results`, `payload`, `color`, `commitTitle` + +Common verbs: `build`, `create`, `compute`, `fetch`, `find`, `get`, `load`, `parse`, `resolve`, `validate`. + +## Boolean naming + +Booleans start with `is`, `has`, `should`, or `does` (with conjugations: `was`, `are`, `have`, `did`). + +- ✅ `isVisible`, `hasChildren`, `shouldRetry`, `doesExist`, `wasProcessed` +- ❌ `visible`, `children`, `retry`, `exists`, `processed` diff --git a/packages/agents/content/skills/code-patterns/SKILL.md b/packages/agents/content/skills/code-patterns/SKILL.md index df85f92b..41744168 100644 --- a/packages/agents/content/skills/code-patterns/SKILL.md +++ b/packages/agents/content/skills/code-patterns/SKILL.md @@ -34,6 +34,10 @@ Rules for how code is structured, organized, and documented. - Complex objects documented by TypeScript interfaces don't need additional JSDoc - Only document params when the name alone doesn't convey purpose or constraints +## Naming + +Follow the naming rules in `_data/naming-conventions.md`: no abbreviations, unit-of-measure suffixes on numerics, verb-led function names, boolean prefixes (`is`, `has`, `should`, `does`). + ## Testing patterns ### Test structure diff --git a/packages/agents/content/subagents/orchestrated-coder.md b/packages/agents/content/subagents/orchestrated-coder.md index 14dbb8c3..24e36101 100644 --- a/packages/agents/content/subagents/orchestrated-coder.md +++ b/packages/agents/content/subagents/orchestrated-coder.md @@ -5,6 +5,7 @@ tools: [Read, Write, Edit, Grep, Glob, Bash] maxTurns: 80 skills: - anti-patterns + - code-patterns - commit - common-mistakes ---