claude-code-arcane 2.9.5 → 2.9.6

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [2.9.6](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.5...v2.9.6) (2026-09-07)
+
+
+### Bug Fixes
+
+* **rules:** make code-comments the only authority on comments ([99bb84e](https://github.com/SebastianLuser/claude-code-arcane/commit/99bb84e7612630ae67d4942b378ccd1881d4cf64))
+
 ## [2.9.5](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.4...v2.9.5) (2026-09-07)
 
 

package/docs/coding-standards.md

@@ -55,10 +55,9 @@ Si podés hacerlo con la stdlib de Python, la escotilla no aplica.
 
 ## Comentarios
 
-- **Escribí el porqué, no el qué.** El código ya dice qué hace.
-- **Doc comments para APIs públicas.** Las privadas no los necesitan.
-- **TODOs con owner y fecha:** `// TODO(@alice, 2026-05-01): descripción`
-- **Anti-pattern:** comentarios que explican el obvio (`// increment counter` sobre `counter++`)
+La regla vive en `.claude/rules/code-comments.md` y es la única autoridad.
+No dupliques criterios acá: dos listas sobre comentarios siempre terminan
+contradiciéndose, y gana la permisiva.
 
 ---
 
@@ -145,17 +144,6 @@ Antes de marcar trabajo como completo:
 
 ---
 
-## Comments / Docs Anti-Patterns
+## Comments / Docs
 
-**NO escribir:**
-- Comentarios que describen WHAT (el código ya dice)
-- Comentarios referenciando el task/PR actual ("added for JIRA-123")
-- Docstrings multi-párrafo en funciones simples
-- Comentarios `// removed X` para código borrado
-- `// used by Y` (el tooling lo dice mejor)
-
-**SÍ escribir comentarios cuando:**
-- Explican el WHY que no es obvio
-- Documentan workaround de un bug específico (con link al bug)
-- Marcan invariantes o preconditions no-obvios
-- APIs públicas consumidas por terceros
+Ver `.claude/rules/code-comments.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.9.5",
+  "version": "2.9.6",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {

package/rules/code-comments.md

@@ -50,13 +50,19 @@ Comments are written in **English**, whatever language the conversation is in.
 
 ## Write
 
-- **The WHY that the code cannot show.** A constant that looks arbitrary, an ordering that
-  matters, a deliberate break from the surrounding pattern.
+**The default is no comment.** The code says what it does and the commit says why it changed.
+A new comment has to earn its place; it is never the neutral choice.
+
+The whole list of exceptions:
+
+- **Doc comments on public APIs** consumed from outside the module, one line. Private ones
+  need none.
 - **Workarounds**, with a link to the upstream bug.
-- **Non-obvious invariants or preconditions** a caller has to respect.
-- **Doc comments on public APIs** consumed from outside the module. Private ones need none.
 - **`TODO(@owner, YYYY-MM-DD): description`.** Never a bare `TODO`.
 
+A comment shaped as a comparison with what used to be there — "X and not Y", "no longer X",
+"now uses X" — is session narration wearing a technical disguise. It belongs in the commit.
+
 ## Shape
 
 One line, unless the reason honestly needs two. A comment that needs a paragraph to explain

package/rules/data-files.md

@@ -15,7 +15,7 @@ paths:
 - All JSON / YAML / TOML files must parse cleanly — malformed config blocks the build
 - File naming: lowercase with hyphens or underscores, following `[domain]-[name].[ext]` pattern
 - Every schema-bearing file must have a documented schema (JSON Schema, OpenAPI, Zod, Pydantic — whatever the stack uses)
-- Numeric values with business meaning must include a comment or companion doc explaining unit and intent (`timeout_ms`, not bare `timeout`)
+- Numeric values with business meaning carry the unit in the key (`timeout_ms`, not bare `timeout`)
 - Use consistent key naming within a file: camelCase for JSON, snake_case for YAML if that's the project convention — don't mix
 - No orphaned entries — every record must be referenced by code, another config, or explicitly marked as a default/example
 - Version config files when making breaking schema changes (`v1/`, `v2/` or explicit `schema_version` field)

package/rules/gamedev/engine-code.md

@@ -9,7 +9,7 @@ paths:
 - All engine APIs must be thread-safe OR explicitly documented as single-thread-only
 - Profile before AND after every optimization — document the measured numbers
 - Engine code must NEVER depend on gameplay code (strict dependency direction: engine <- gameplay)
-- Every public API must have usage examples in its doc comment
+- Public API doc comments stay to one line (see `code-comments`); usage examples belong in the docs, not the source
 - Changes to public interfaces require a deprecation period and migration guide
 - Use RAII / deterministic cleanup for all resources
 - All engine systems must support graceful degradation

package/rules/gamedev/shader-code.md

@@ -18,7 +18,7 @@ visual quality, performance, and cross-platform compatibility.
 ## Code Quality
 - All uniforms/parameters must have descriptive names and appropriate hints
 - Group related parameters (Unity: `[Header]`, Unreal: Category)
-- Comment non-obvious calculations (especially math-heavy sections)
+- Name non-obvious calculations rather than commenting them; comments follow `code-comments`
 - No magic numbers — use named constants or documented uniform values
 
 ## Performance Requirements