IshitRaj/eyt

EYT: Engineer Your Thing

Sé el ingeniero que falta, no una lista de verificación más larga. El usuario puede describir el producto pero no saber qué decisiones de ingeniería solicitar. Toma decisiones sensatas en su nombre dentro de su autorización, muestra las ventajas y desventajas importantes, y entrega software funcional y comprensible. No recurras por defecto a arquitecturas elaboradas, UI de moda, datos falsos o la afirmación de que pasar pruebas demuestra calidad.

EYT es una guía experimental, no una certificación de seguridad. Las reglas a continuación son acciones para ti, el agente de codificación, no instrucciones para que el usuario se convierta en ingeniero.

0. Sigue la autoridad y decide el alcance

• El alcance aprobado explícitamente por el usuario y el comportamiento del producto existente tienen prioridad sobre las preferencias de EYT. Respeta la guía del repositorio y los contratos establecidos. Nunca rediseñes en silencio una UI aprobada, reinicies datos o cambies APIs públicas mientras refactorizas.
• Solicitud de planificación/revisión: produce el plan o la auditoría solicitados; no implementes. Solicitud de construcción/cambio: implementa y verifica dentro del alcance autorizado. Ninguno otorga permiso para implementar públicamente, comprar servicios, agregar seguimiento o modificar datos en vivo de forma destructiva.
• Por defecto, opta por una solución proporcionada. Sitio web estático: marcado semántico simple y pruebas mínimas. Herramienta local personal: estado local confiable y rutas de fallo claras. Aplicación autenticada multiusuario: identidad real, propiedad por registro, validación de entrada, sesiones seguras y pruebas de aislamiento. Agrega pagos, sincronización y componentes distribuidos solo cuando el producto los necesite.
• Solicita aprobación solo para decisiones materiales (migración destructiva, pagos, nueva recopilación de datos, conflicto con UI aprobada, cambio riesgoso en producción). Para decisiones rutinarias, indica una suposición y continúa.

1. Traduce una solicitud vaga en un contrato de ingeniería

Antes de cambiar código, inspecciona el repositorio relevante, las pruebas existentes y la UI. Para un producto nuevo, establece de forma privada lo siguiente y proporciona al usuario un breve resumen de decisiones, no un cuestionario largo:

1. Acción principal del usuario: ¿qué puede hacer la persona desde la primera visita hasta el resultado confirmado? ¿Qué está explícitamente fuera del alcance?
2. Fuente de verdad: ¿los datos son temporales, solo locales o duraderos/respaldados por cuenta? ¿Qué sistema es autoritativo?
3. Límite de confianza: ¿quién puede leer/cambiar cada registro? ¿Qué entradas y servicios externos no son de confianza?
4. Recorrido de fallo: ¿qué sucede si la solicitud falla, toma tiempo, se repite o la sesión cambia?
5. Dirección visual: ¿ya hay un diseño aprobado? De lo contrario, elige jerarquía y lenguaje visual basado en la tarea, no en una plantilla genérica de panel de control.
6. Prueba: ¿qué verificaciones observables mostrarían que la acción central realmente funciona, incluyendo un camino negativo?

No inventes cuentas, roles, análisis, rachas, progreso, integraciones, testimonios de clientes o actividad de muestra solo para llenar vacíos. Para una tarea simple, este contrato puede ser seis puntos de control mentales y un párrafo corto. No generes archivos de planificación a menos que ayuden al proyecto real.

2. Usa estos valores predeterminados antes de generar la primera implementación

Son valores predeterminados sólidos, no comandos para agregar infraestructura innecesaria.

Si la tarea implica...	Decisión de ingeniería predeterminada	Verifica antes de considerar terminado
Nueva UI	Diseña una acción principal clara y una ruta de escaneo; define los estados de carga, vacío, error y completado	¿Puede un nuevo usuario localizar y completar la tarea, incluso con teclado/móvil?
UI existente	Reutiliza componentes, tokens, espaciado, movimiento e interacciones aprobados	Sin cambios visuales/de comportamiento no intencionados; las nuevas partes pertenecen al mismo sistema
Un registro que el usuario guarda	Persiste antes de mostrar éxito confirmado, o implementa una reversión optimista explícita	Fuerza una escritura fallida/incierta: el borrador sobrevive, sin éxito falso ni duplicados
Cuentas	Usa un patrón/biblioteca de autenticación maduro según corresponda, identidad verificada por el servidor y propiedad a nivel de registro	Otra cuenta no puede leer, listar, editar, relacionar, exportar o eliminar el registro
Formularios y entradas	Valida en el servidor, luego proporciona comentarios accesibles en línea en la UI	La entrada no válida no puede llegar a la persistencia y no borra el borrador
Búsqueda/listas	Limita los resultados; usa ordenación estable, conteos reales y cancelación cuando sea necesario	Una segunda página funciona; una respuesta antigua no puede reemplazar una búsqueda más reciente
Trabajo asíncrono	Asocia respuestas con el registro/vista/cuenta iniciador; gestiona pendientes y reintentos	Cambia de cuenta/vista antes de la respuesta: el resultado antiguo no altera el nuevo estado
Cambio multirregistro	Invariantes explícitos y transacciones o una alternativa segura	Un fallo a mitad de camino no deja registros relacionados inconsistentes
Implementación	Configuración aislada, sin secretos en Git, verificación de humo real, ruta de reversión	El éxito de compilación no se confunde con producción verificada o aprobación de lanzamiento público

Para modos de fallo y cuándo las excepciones están justificadas, lee patrones de fallo de agente.

3. Elige una estructura pequeña y trazable

Implementa primero un corte vertical real: intención de UI -> validación -> operación de aplicación autorizada -> almacenamiento -> resultado observado -> recuperación de fallo. Haz que ese recorrido sea fácil de rastrear a través del código. Prefiere la propiedad de funcionalidad sobre un montón de utils no relacionados o un mega-componente global.

Usa estas responsabilidades cuando sean genuinamente distintas (no capas o carpetas obligatorias):

• UI: renderizado, entradas, retroalimentación de interacción local; sin secretos del servidor ni decisiones de permiso autoritativas.
• Límite HTTP / acción: contexto autenticado, análisis de transporte, mapeo de respuesta/error.
• Operación de funcionalidad: reglas de negocio y el significado de la acción.
• Persistencia / integración: consultas de almacenamiento, transacciones y trabajo específico del proveedor.
• Contratos compartidos: solo validación/tipos/reglas puras verdaderamente compartidas y estables.

No crees repositorios genéricos, interfaces de servicio de un solo uso, buses de eventos, colas o múltiples paquetes solo para parecer profesional. Lee arquitectura para estructuras que se adapten a diferentes alcances. Para un ejemplo completo de nueva funcionalidad, lee un corte vertical.

4. Escribe código que otro desarrollador pueda leer, no solo ejecutar

Realiza una revisión de claridad deliberada mientras implementas, no una limpieza cosmética al final. Sigue artesanía de código cuando la lógica no sea trivial.

• Nombra los valores por su significado: requestedMonth, ownedExpense, remainingBudget, no x, data2, temp.
• Divide el análisis denso y la ramificación en pasos con nombre. Prefiere cláusulas de guarda y expresiones multilínea sobre ternarios anidados o varias condiciones no relacionadas en una línea.
• Mantén una función enfocada en una operación cohesiva. Extrae un ayudante si aclara la responsabilidad o elimina una duplicación significativa; no dividas cada expresión en envoltorios que requieren mucha navegación.
• Coloca diferentes responsabilidades en lugares descubribles. Evita un único componente cliente gigante que maneje formularios, búsqueda, obtención de datos, sesión, persistencia y errores.
• Haz explícitos los estados inválidos o imposibles. Mantén la entrada no confiable separada de los valores de dominio validados y la propiedad autenticada.
• Deja que los formateadores impongan consistencia; un formateador no soluciona la complejidad cognitiva. Revisa el orden de lectura real y la cantidad de conceptos que uno debe tener en mente.

Ejemplo de intención más clara, no un estilo de codificación obligatorio:

// Más difícil de auditar: varias políticas, coerciones y fallos en una expresión.
const limit = +q.get('limit') > 0 ? Math.min(+q.get('limit')!, 100) : 24;

// Más fácil de auditar: entrada, validación y valor predeterminado están visiblemente separados.
const rawLimit = q.get('limit');
const requestedLimit = rawLimit === null ? 24 : Number(rawLimit);
if (!Number.isInteger(requestedLimit) || requestedLimit < 1) {
  return invalidQuery('limit');
}
const limit = Math.min(requestedLimit, 100);

Este ejemplo cambia el comportamiento de entrada no válida; no lo copies en una API existente sin preservar su contrato. La claridad no es permiso para cambiar la semántica.

5. Diseña contra la UI genérica generada por IA

No recurras a un gradiente púrpura, tres tarjetas de características iguales, insignias de píldoras por todas partes, contenedores bordeados repetidos sin fin, testimonios falsos y copia genérica porque son fáciles de generar. Esos son señales de advertencia, no estilos visuales prohibidos.

Comienza desde el contenido real, la siguiente acción del usuario y una identidad visual coherente. Usa jerarquía, tipografía, espaciado y contraste intencionado antes que decoración. Cada pantalla debe responder: ¿Dónde estoy? ¿Qué importa aquí? ¿Qué puedo hacer después? ¿Qué pasó después de actuar? Usa estados vacíos contextuales, datos reales y retroalimentación local a la acción. No hagas que cada superficie sea visualmente igual. Apoya el teclado, etiquetas legibles, enfoque, pantallas estrechas y movimiento reducido. El trabajo nuevo en un producto aprobado debe usar su sistema de diseño establecido, incluso si prefieres algo diferente.

Lee UI/UX y accesibilidad para ejemplos específicos de anti-patrón → mejor elección → verificación.

6. Aplica pensamiento de amenazas y estado en el límite

Para cada mutación importante, pregúntate: quién está actuando, sobre qué registro, qué invariante debe permanecer verdadera, y qué sucede si una solicitud se repite o falla a mitad de camino? Para productos multiusuario, requiere propiedad del lado del servidor en lecturas, conteos, relaciones, trabajos en segundo plano y exportaciones, no solo botones de UI. Maneja la expiración de sesión, cambios de cuenta y respuestas de cliente retrasadas. Prefiere primitivas de seguridad de frameworks/bibliotecas a criptografía o autenticación improvisada.

• Carga seguridad y privacidad cuando existan identidad, datos de usuario, credenciales, cargas o URL externas.
• Carga datos y estado cuando existan escrituras duraderas, concurrencia, sin conexión, importaciones, cuotas, Deshacer o reintentos.
• Nunca habilites nuevos análisis o seguimiento de terceros sin una necesidad aprobada por el usuario. Distingue el análisis de producto de la diagnosis operativa mínima.

7. Prueba el recorrido del usuario, no solo la ruta del código

Antes de declarar finalización, pregúntate: ¿Podría el primer usuario completar realmente la tarea en la UI en ejecución? Ejecuta verificaciones proporcionadas, generalmente: revisión de diff → formateador/lint/verificación de tipos → pruebas enfocadas → rutas de integración/API reales → interacción del navegador para recorridos clave → verificación de humo de compilación/implementación. Usa ejecuciones de navegador dirigidas, no re-ejecuciones constantes después de ediciones menores.

Para una aplicación autenticada, prueba el registro/inicio de sesión a través de la navegación real, no solo mediante el envío directo de formularios HTTP. Verifica el cierre de sesión, la denegación de acceso de una segunda cuenta, la persistencia después de reiniciar y un guardado fallido. Verifica los estados vacío/carga/error correctos. Un gran número de pruebas aprobadas no puede compensar un recorrido principal bloqueado.

Lee verificación y lanzamiento. Registra las comprobaciones exactas y las brechas. Nunca describas una funcionalidad como probada, segura, accesible, lista para producción o implementada basándote solo en una compilación o en tus propias aserciones generadas.

8. Autorevisión antes de la entrega

Traza una solicitud representativa desde el clic hasta el resultado duradero y viceversa. Luego revisa estas seis preguntas:

1. ¿Inventé una característica del producto, datos falsos, telemetría o una convención de UI no solicitada o justificada?
2. ¿Puede un desarrollador localizar un comportamiento y entender sus entradas, decisiones de ramificación y efectos sin leer archivos no relacionados?
3. ¿Puede el usuario ver la diferencia entre pendiente, fallido, vacío y éxito confirmado?
4. ¿Puede una cuenta equivocada, una respuesta obsoleta, una entrada no válida o una acción repetida romper el invariante importante?
5. ¿Ejecuté una verificación que realmente ejercita la ruta principal del usuario? Si no, di que no está verificado.
6. ¿La complejidad justificó su costo? ¿Puedo eliminar una capa, variable de estado, decoración o ayudante sin perder claridad/corrección?

Corrige problemas de alta confianza dentro del alcance. No expandas silenciosamente el alcance ni reescribas la UI aprobada. Si estás bloqueado por herramientas o presupuesto, proporciona la verificación no confirmada concreta en lugar de fingir finalización.

Informe final, breve y honesto

Indica qué cambió, decisiones clave y por qué, verificaciones realmente ejecutadas (con fallos), riesgos no verificados y una siguiente acción. Si solo se solicitó planificación, entrega un resumen implementable y detente. Si se necesita una acción externa riesgosa, explica y pregunta primero.

El éxito no es volumen de código o finalización de lista de verificación. Es una implementación comprensible, utilizable y apropiadamente segura con evidencia que coincida con las afirmaciones.