Skip to content

code-quality-cocos

Binding rule. code-conventions-cocos.md governs naming and style; this governs structure and pattern choice. Auto-loaded, so it binds every session.

SSOT: architecture doctrine (SOLID, module boundaries, class roles, anti-patterns) lives in the project’s docs/system-design.md § “Code Structure Rules (Mandatory)”. This rule does not restate it.

  1. docs/system-design.md governs. An absent or stale design doc is a blocking finding: author or correct it before planning structural work (Phase 0 of t1k-cocos-base-architecture-patterns).
  2. The pattern triggers below are mandatory. A change that introduces a listed violation is incomplete, not merely imperfect.
  3. Annotation moves with the code: any symbol you add, or whose signature you change, carries its TSDoc /** */ in the same change, never a follow-up pass. Tooling: docs/code-quality-cocos.md.
If you seeYou must apply
instantiate()/new Node() in a loop or per-spawnObject pooling (ObjectPoolManager)
2+ booleans encoding “what is happening now”FSM (StateManager)
A module reaching into another directlySignalBus (named-method subscribe)
A class with 3+ unrelated change reasonsComponent split (SRP)
A method over ~60 lines, or mixing 2+ receiver groupsFunction decomposition (t1k-cocos-playable-primitive-decompose)
Global mutable state reached from 3+ sitesService singleton (private static _instance)
Copying/rewriting a small standalone methodRun t1k-cocos-base-stdlib-contribute
Raw input listener or new Input/Touch ServiceInputService + InputSignals via SignalBus; UI buttons via cc.Button CLICK only, docs § InputService Mandate

Why each row fires, and the pattern’s how-to: docs/code-quality-cocos.md.

Enabling extraction is required refactor work, not optional cleanup. A subsystem blocking a @playablelabs/* package swap needs the SRP split that exposes that seam; record it so the reuse scan re-runs against it.

docs/system-design.md (SSOT) · refactor ordering, annotation tooling: docs/code-quality-cocos.md.