code-conventions

Code Conventions (Universal)

Applies to ALL languages and frameworks. Kit-specific rules extend this in code-conventions-{kit}.md.

Generic conventions (summary)

SOLID; self-documenting names (is/has/can/should booleans, verb functions); one responsibility per file, ≤200 lines, guard clauses over nesting, composition over inheritance, immutability by default; no magic numbers / empty catch / merged-TODO; stdlib→external→internal import order; test public behavior with independent, descriptively-named tests. Full enumerated lists: docs/code-conventions.md.

Data-Driven Over Hardcoded

NEVER hardcode mappings (command→skill / role / agent, keyword→module) in hooks or scripts — read them from registry files at runtime so new skills/agents/modules auto-discover with no code change. Test: deleting a static map should break nothing, because the data comes from files. If it breaks, you’re hardcoding.

No Duplicated Logic

Search shared modules (telemetry-utils.cjs, lib/) before writing a utility; a pattern appearing in 2+ files is extracted immediately, not “later”. Every .claude/ path resolution uses resolveClaudeDir() — no inline path.join(cwd, '.claude'). Guard null/undefined where data crosses system boundaries.

No Derived Fields — SSOT for Data

NEVER store a value computable from other columns. If C = f(A, B) and A/B are stored, compute C at the query/use site.
Exception — materialized for performance only: profiling proves a real bottleneck AND source columns rarely change AND it’s kept in sync via trigger/constraint/CI AND the formula is documented inline.

Modular Boundaries — Seam Where It Earns Its Keep

Decompose by feature/vertical slice, not by layer; draw a seam only when it passes the seam-worth test — hides more complexity than its interface adds, ≥3 real uses OR a stable domain/third-party edge, only name/type coupling crosses it. Parallelism is a benefit of a good seam, never a reason to draw one.
Modularize the tests with the feature — own suite, scoped to that module. Test: deleting a module should delete its tests with it.
Full seam-worth test, DAG oracle, calibration guard, anti-patterns: docs/code-conventions.md.

Living Document

If unsure about a convention not covered here, ask the user and update this file.