Estructura del proyecto y forma de trabajar

Cada proyecto que scaffoldeás con create-tikxander-game viene con reglas claras desde el minuto cero para que tu asistente de IA (cualquier modelo) trabaje ordenado y no se vaya por las ramas. Estas reglas son parte del proyecto: viven en AGENTS.md y en .ai/rules/, y el build las verifica.

Reglas de estructura

Ningún archivo supera 500 líneas (ideal < 300). Si un archivo crece, se divide. El build corre scripts/check-structure.mjs (zero-dep) y falla si te pasás — así un archivo gigante nunca llega a publicarse.
Un archivo, una responsabilidad, con nombre descriptivo.
El código de src/ se organiza en carpetas de concern con prefijo _:

Carpeta	Qué va acá
`src/_models/`	Tipos e interfaces (estado, payloads, config)
`src/_enum/`	Enums / uniones de estado (fases, tipos de item)
`src/_const/`	Constantes y defaults (colores, umbrales, dimensiones)
`src/_services/`	Lógica pura sin DOM (puntajes, ranking, física, IO del SDK)
`src/_hooks/`	Helpers de estado/animación reutilizables
`src/_components/`	Piezas de render / DOM reutilizables

En un juego, src/main.ts hace el bootstrap del SDK y src/tikxander-bridge.ts es el punto de entrada de tu lógica (delegá en _entities/ y _systems/ si crece). En un widget, tu lógica vive en las 3 funciones de createWidget() en src/main.ts (o extraídas a src/_logic/), y los estilos en src/style.css.

_hooks/_components son idiomáticos de frameworks con hooks; en un juego canvas mapean a "helpers de estado/animación" y "piezas de render". Mantené los nombres para tener un solo modelo mental ordenado.

Forma de trabajar: planificá antes de codear (SDD ligero)

Para una feature no trivial (toca varias piezas, hay decisiones de diseño, o no cabe en una frase), tu proyecto trae una carpeta _specs/ con una plantilla:

Copiá _specs/_plantilla/ a _specs/NNN-<slug>/.
Llená los 4 archivos: context (por qué) → spec (qué técnico) → plan (pasos) → task (Definition of Done medible).
Mostrale el plan a tu humano y esperá el OK antes de implementar.

Un cambio trivial (un color, un texto) no necesita spec: hacelo directo.

Preguntá hasta tener todo claro

La regla más importante para que la IA no invente: antes de escribir código, reformulá lo que entendiste y hacé todas tus preguntas juntas (mecánica, qué evento dispara qué, defaults, qué configura el streamer, tamaño del overlay). Si algo no está claro, preguntá — no asumas.

Model-agnostic: una fuente de verdad, adaptadores finos

Las reglas viven una sola vez en AGENTS.md + .ai/rules/. Los archivos de cada asistente son adaptadores mínimos que apuntan ahí, así funciona con cualquier IA sin duplicar contenido:

Archivo	Herramienta
`AGENTS.md`	Fuente de verdad (Codex, Grok, Jules, Zed…)
`CLAUDE.md`	Claude Code (`@import` a `AGENTS.md` + `.ai/rules/`) + hook de 500 líneas
`.cursor/rules/tikxander.mdc`	Cursor / Windsurf
`.github/copilot-instructions.md`	GitHub Copilot
`GEMINI.md`	Gemini CLI

Qué verifica el `build`

npm run build   # node scripts/check-structure.mjs && tsc --noEmit && vite build

check-structure.mjs → ningún archivo > 500 líneas; carpetas de src/ válidas.
tsc --noEmit → tipos.
vite build → bundle.