From 3c954eedbb60904017fd319d776760fb9955f24f Mon Sep 17 00:00:00 2001 From: Jason Naylor Date: Tue, 28 Jul 2026 08:33:26 -0700 Subject: [PATCH 1/2] Add comment-rules skill for TypeScript authoring Guides doc/inline comments toward why-focused brevity; tracks .claude/skills/ so repo skills are versioned. --- .claude/skills/comment-rules/SKILL.md | 35 +++++++++++++++++++++++++++ .gitignore | 3 ++- 2 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/comment-rules/SKILL.md diff --git a/.claude/skills/comment-rules/SKILL.md b/.claude/skills/comment-rules/SKILL.md new file mode 100644 index 00000000..ecb30c3b --- /dev/null +++ b/.claude/skills/comment-rules/SKILL.md @@ -0,0 +1,35 @@ +--- +name: comment-rules +description: Rules for writing and editing comments in TypeScript. Use whenever adding or modifying doc comments or inline comments in .ts/.tsx files in this repo. +--- + +# Comment Rules + +Priorities when writing comments: accuracy first, then brevity. A comment must earn its place - if it restates what the signature and types already say, delete it. + +## Doc comments + +State **what a thing is for and why it exists**. Never explain **how** it works - the code shows that. + +A doc comment must stand alone: someone hovering over the symbol, who will not read the body, should understand its purpose from the comment. + +Required vs optional: + +- Exported methods, classes, interfaces, types, and constants: give a short summary. +- Private/internal symbols: comment only when the purpose is non-obvious. Skip trivial getters, thin wrappers, and self-evident helpers. + +Module-level comments are worthwhile only when the module is a consumed API surface. Do not add file-header banners. + +## Params and returns + +Omit `@param` and `@returns` unless they add information the signature and type do not already convey - units, nullability meaning, ownership, side effects, or constraints. Never write `@param name - the name`. + +## References to other code + +Do not mention other code by name in prose. Reference other code only when necessary for the reader to understand the symbol - not for completeness. The only permitted reference is a **type**, and only when naming it genuinely aids understanding. Write it with TSDoc `{@link}` so generated docs render a link: + +`{@link SomeType}` + +## Inline comments + +Use sparingly. Warranted only when the reasoning is not clear from the code, or when a bugfix introduces a non-obvious change. Keep them short, and always about the code they sit next to. diff --git a/.gitignore b/.gitignore index 1281ba3c..5d3b794e 100644 --- a/.gitignore +++ b/.gitignore @@ -34,7 +34,8 @@ temp-build # #endregion # AI files -.claude +.claude/* +!.claude/skills/ # Playwright output e2e-tests/.cdp-* From 542985b32fa01519472831374e94aab603fd40b5 Mon Sep 17 00:00:00 2001 From: Jason Naylor Date: Tue, 28 Jul 2026 11:39:27 -0700 Subject: [PATCH 2/2] Consolidate all comment rules into comment-rules skill Migrate JSDoc rules from AGENTS.md into the skill; require all params documented if any is; use ASCII only. --- .claude/skills/comment-rules/SKILL.md | 12 ++++++++++-- AGENTS.md | 11 +---------- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/.claude/skills/comment-rules/SKILL.md b/.claude/skills/comment-rules/SKILL.md index ecb30c3b..25d5ac7e 100644 --- a/.claude/skills/comment-rules/SKILL.md +++ b/.claude/skills/comment-rules/SKILL.md @@ -20,9 +20,17 @@ Required vs optional: Module-level comments are worthwhile only when the module is a consumed API surface. Do not add file-header banners. -## Params and returns +These rules do not apply to unnamed inline callbacks passed directly to framework APIs (e.g. `describe()`, `test()`) - the test-title string serves as the documentation. -Omit `@param` and `@returns` unless they add information the signature and type do not already convey - units, nullability meaning, ownership, side effects, or constraints. Never write `@param name - the name`. +## Params, returns, and throws + +Omit `@param` and `@returns` unless they add information the signature and type do not already convey - units, nullability meaning, ownership, side effects, or constraints. Never write `@param name - the name`. An exception: if any single method parameter deserves a comment, document all the parameters of that method. + +Include `@throws` for every error condition the caller must handle; omit it when the function never throws. + +## Type declarations + +Interfaces, type aliases, and enums follow the same doc-comment rules. Document each field or member whose purpose is not self-evident from its name and type, individually rather than in the type-level summary. ## References to other code diff --git a/AGENTS.md b/AGENTS.md index 318d1119..7883a308 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -155,16 +155,7 @@ The ESLint rule `no-type-assertion/no-type-assertion` is enforced. **Never use ` ## Documentation -Every named function and method — exported or internal — must have a JSDoc block with: - -- A summary sentence describing what the function does and why it exists (non-obvious behavior only; don't restate the name). -- `@param` for every parameter. -- `@returns` describing the return value (omit only for `void`/`Promise`). -- `@throws` for every error condition the caller must handle; omit if the function never throws. - -This function rule does not apply to unnamed inline callbacks passed directly to framework APIs (e.g., `describe()`, `test()`) — in those cases the test-title string serves as the documentation. - -Type declarations (interfaces, type aliases, enums) must have a JSDoc summary on the type itself and on each field or member whose purpose is not self-evident from its name and type. We document each field individually rather than describing the fields in the type-level summary. +All comment and JSDoc rules for TypeScript live in [.claude/skills/comment-rules/SKILL.md](.claude/skills/comment-rules/SKILL.md). All agents must follow it when writing or editing comments. ## Spelling