Claudisms

CLAUDE.md

@@ -8,7 +8,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - Lint: `npm run lint` (auto-fix), `npm run lint-check` (check only)
 - Type Check: `npm run ts-check`
 - Test: `npm run test` (all), `npm run test-min` (minimal)
-- Test Single File: `npx vitest <path/to/test>`
+- Test Single File: `npm run test -- --run base-compiler-tests.ts`
+- Test Specific Pattern: `npm run test -- -t "should handle execution failures"`
 - Cypress Tests: `npm run cypress`
 - Pre-commit Check: `make pre-commit` or `npm run check`
 
@@ -46,6 +47,16 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
   // Initialises the thing
   initialiseThing();
   ```
+- Avoid redundant function header comments that merely repeat the function name. For example:
+  ```
+  /**
+   * Sets up compiler change handling
+   */
+  function setupCompilerChangeHandling() {...}
+  ```
+  In this case, the function name already clearly states what it does.
+- Comments should provide additional context or explain "why" something is done, not just restate "what" is being done.
+- Only add function header comments when they provide meaningful information beyond what the function name and signature convey.
 - Use British English spellings for things like "initialise" and "colour", but only in new code. It's a preference not a hard requirement
 
 ## Testing Guidelines