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/ + .ai/skills/. 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
`.claude/skills/*`	Adaptadores Claude de workflows y skills de calidad
`.cursor/rules/tikxander.mdc`	Cursor / Windsurf
`.github/copilot-instructions.md`	GitHub Copilot
`GEMINI.md`	Gemini CLI
`.ai/skills/*`	Pack de calidad: building-games, design-ui, game-asset-*, etc.

Skills de calidad de juego (desde el scaffold)

Cada proyecto trae un catálogo en .ai/skills/ (índice: .ai/skills/README.md):

Skill	Para qué
`building-games`	Loop, juice, física, cámara 3D, perf, géneros
`controls`	WASD / volante / vuelo (solo si hay teclado; A=izquierda)
`design-ui`	HUD y overlays DOM legibles en stream
`game-asset-core` (+ animation, tilesets, character, ui-icons)	Arte engine-ready
`generate2dsprite` / `generate2dmap` / `video2dsprite`	Pipelines 2D
`imagine`	Prompt-craft de imágenes
`threejs`	API Three (template three)

Reglas cortas complementarias: .ai/rules/calidad-juego.md, .ai/rules/hud-ui.md, .ai/rules/assets.md. No se empaquetan auth de app, Neon ni multiplayer P2P: en TikXander el multiplayer son los viewers del live vía el SDK.

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.

La publicación en el portal corre el build, así que estas reglas se respetan antes de que tu juego/widget salga al catálogo.