Engineering Handbook

Apariencia

AGENTS.md — Sistema de Decisión Central, Auto-Ruteo y Motor de Auditoría Autónoma ​

Este documento es la fuente de verdad operativa del handbook. Antes de planear, escribir código o entregar una solución, lee este archivo, identifica el dominio de la tarea, consulta el estándar correcto y aplica las reglas obligatorias.

Regla de oro ​

  1. No escribas código todavía.
  2. Clasifica el problema por dominio: base de datos, backend, frontend, seguridad, devops o producto.
  3. Abre y lee el estándar específico antes de implementar.
  4. Aplica las reglas marcadas como REQUIRED sin omitir validaciones.
  5. Verifica la entrega con el checklist corto antes de cerrar la tarea.

Gate de activación antes de implementar ​

Antes de declarar una funcionalidad lista para producción, la IA debe revisar:

  1. Engineering-OS/32-Operating-Gate.md para perfil, riesgo y evidencia.
  2. Engineering-OS/34-Policy-Profiles.md para confirmar el perfil aplicable.
  3. Engineering-OS/33-Feature-Completeness-Engine.md para completar la matriz de cobertura.
  4. Engineering-OS/35-Rule-Registry.md y Engineering-OS/36-Validation-Pipeline.md para validar reglas y pipeline.

Si la tarea expone una laguna del handbook, detén la implementación, documenta el gap, investiga con la jerarquía de confianza y genera un borrador antes de avanzar.

Mapa rápido de decisión ​

Usa este mapa para encontrar el estándar correcto:

Reglas inquebrantables críticas ​

IDReglaNota
DB-001No usar SELECT *Especificar columnas explícitas
DB-002Toda FK debe tener índice secundarioEvitar cuellos de botella
DB-008No usar float/double para dineroUsar bigint o centavos
S-001Todo payload debe validarse con ZodFrontend y backend
S-005No usar CORS wildcard en entornos autenticadosSeguridad primero
FE-001No usar any en TypeScriptUsar unknown y estrechar tipos
FE-005Todo componente async debe manejar Loading, Empty, Error y SuccessEstados UI obligatorios
MONEY-001Los precios no se definen en el frontendEl backend resuelve monto y priceId
AUTH-003Magic links con TTL máximo de 15 min y un solo usoSeguridad de acceso
AUTH-004Invitaciones de equipo con TTL 48h, token revocable y rate-limitExcepción controlada
SEC-001CSP estricta en todas las respuestas HTTPEvitar XSS y ejecución insegura
SEC-002Cero secretos en bundles de cliente (Vite/APK/Tauri)APIs privadas siempre por backend proxy
TENANT-001RLS es la fuente de verdad para aislamiento multi-tenantNo bypass de capa
TEST-001Bugs P0/P1 y seguridad exigen test de regresiónPrueba automatizada obligatoria antes de cerrar fix

Lo que una IA nunca debe hacer ​

  • Inventar librerías, patrones o configuraciones que no pertenezcan al stack oficial.
  • Usar any en TypeScript o desactivar strict mode.
  • Usar SELECT * o crear FK sin índice secundario.
  • Silenciar errores con try/catch vacíos o devolver 200 OK falsos.
  • Enviar PII o datos sensibles a modelos externos sin anonimización.
  • Basar decisiones en blogs personales o tutoriales como fuente principal.

Lo que una IA siempre debe hacer ​

  • Consultar este archivo antes de actuar.
  • Leer el estándar relevante antes de implementar.
  • Aplicar las reglas REQUIRED del dominio.
  • Estandarizar respuestas API con ok() y fail().
  • Usar React Query para fetching y evitar useEffect descontrolado para mutaciones.
  • Mantener naming consistente: snake_case en DB y camelCase en TypeScript.

Checklist corto de entrega ​

  • [ ] Consulté el estándar correcto para el dominio.
  • [ ] Apliqué las reglas REQUIRED y no omití validaciones.
  • [ ] El código cumple con TypeScript estricto y sin any indebido.
  • [ ] Los datos de entrada están validados con Zod.
  • [ ] Si el componente es async, maneja Loading, Empty, Error y Success.
  • [ ] Las respuestas API siguen el envelope estándar.
  • [ ] Incluí pruebas para el flujo exitoso y los casos de error.
  • [ ] Si hubo cambios de base de datos, preparé migración y rollback.

Jerarquía de confianza ​

Cuando no exista una guía en el handbook, la investigación debe seguir este orden de prioridad:

  1. Handbook propio.
  2. Especificaciones oficiales y estándares formales.
  3. Documentación oficial de la tecnología.
  4. Marcos de seguridad y estándares reconocidos.
  5. Fuentes de comunidad, solo como apoyo secundario.

Evita usar blogs personales, Medium o tutoriales como única fuente.

Auditoría y calidad del handbook ​

Si una tarea modifica documentación del handbook, debe verificar el estado del repositorio con:

bash
npm run lint

El lint valida patrones bloqueantes como SELECT *, any, CORS wildcard, JWT en localStorage, CSP inseguro y HTML crudo en correos.

Cuando falte cobertura, emite una estructura formal de missing_document y, si aplica, un draft_document con impacto, fuentes y reglas afectadas antes de avanzar.

261 documentos indexados · generado desde INDEX.json

Engineering Handbook — uso interno