Reglas para asistentes de IA¶
tai-api rules install # instala/actualiza las de la versión que tienes
tai-api rules install --force # sobrescribe también lo editado a mano
tai-api rules check # ¿coinciden? Sale con código != 0 si no (para CI)
tai-api rules diff # en qué se diferencian
Instala en el repositorio la documentación que un asistente de IA necesita para trabajar con la API: cómo funciona tai-api —la API generada, la autenticación, el cliente TypeScript, los comandos, los errores— y una parte derivada de tu proyecto: tus endpoints con sus filtros y permisos, tus realms con sus roles, qué tablas tienen filtrado por fila, cómo está configurada la sesión.
mi-proyecto/ ← la raíz del repositorio (la que tiene el .git)
├── .claude/
│ └── rules/
│ └── _platform/
│ ├── tai-sql/ ← tai-sql rules install
│ └── tai-api/ ← tai-api rules install
├── database/
└── api/
| Fichero | Qué cuenta |
|---|---|
api.md |
La API generada: rutas, filtros, escritura, agregaciones y respuestas |
autenticacion.md |
Los dos modos, la sesión, los permisos y el filtrado por fila |
cliente-ts.md |
El cliente TypeScript y el proxy /api |
comandos.md |
El proyecto: qué es de quién, comandos, configuración, extender y desplegar |
errores.md |
Qué falla, qué significa y qué hacer, incluidos los fallos que no dan error |
proyecto.md |
Tu proyecto: autenticación, sesión, realms, roles, RLS y frontend |
endpoints-<schema>.md |
Tus endpoints, uno por schema generado |
Van a la raíz del repositorio, junto a las de tai-sql: el asistente carga al arrancar el
.claude/rules/ de la raíz, y el de una subcarpeta solo cuando lee un fichero de dentro. Sin
repositorio, van al proyecto de tai-api.
Instala también las de tai-sql
Las de tai-api cuentan la capa HTTP; el schema, push, los DAOs y sus errores están en las de
tai-sql. tai-api rules install avisa si faltan: tai-sql rules install.
_platform/ no se edita
Lo pisa la siguiente instalación. Sin --force, un fichero editado a mano se respeta y se
avisa. Las reglas propias del equipo van fuera de _platform/.
Por qué existe¶
Un asistente que no sabe cómo funciona tai-api edita los endpoints generados, escribe a mano un
cliente para el frontend, guarda el token en localStorage o no sabe que el filtrado por fila no
valida las altas. Las reglas son la respuesta escrita a eso, y viajan con el paquete: describen
la versión que tienes instalada, y tu API tal como es.
Se instalan siempre a mano¶
Ningún otro comando escribe ahí. Lo que sí hace tai-api generate es avisar al terminar si se
han quedado atrás —sobre todo las derivadas, que cambian con el schema y con rbac/<realm>.py—.
En CI:
Las derivadas no llevan rutas absolutas ni nada del entorno de quien las generó: son iguales en
cualquier máquina, así que check no falla por correr en otra. Sí necesita poder cargar los
schemas, así que el CI tiene que definir las variables que declara su datasource() (sin
conectarse a nada).