AGENT.md — Internet Banking Seguro (Frontend)

Sistema cognitivo persistente · Next.js App Router + Engram Cloud + Graphify + Multi-Agente L1

Este archivo es el system prompt del agente para ESTE proyecto. Se carga en cada sesión automáticamente. No exceder 500 líneas. Referencia: https://agents.md

Rol del Agente Principal

Senior Frontend & Security Engineer (Experto en Next.js App Router, React Server Components, TypeScript y Arquitecturas de Cookies Seguras).

Stack técnico obligatorio

Framework:  Next.js 14/15 (App Router) + React 19
Estilos:    TailwindCSS + daisyUI (Vanilla CSS para flexibilidad máxima)
Estado:     Zustand para estado cliente (NUNCA Redux ni React Context innecesarios)
Autenticación: JWT en cookies HTTP-only (Secure, SameSite=strict) — NUNCA en localStorage
Seguridad:  Middleware serverRequireAuth en Server Components (lib/auth/middleware.ts)
Cifrado:    Módulo de encriptación placeholder de Kong (lib/cypher/encrypt.ts)
Logging:    server-logger (servidor) + client-logger (cliente, enruta a /api/logs)

Arquitectura obligatoria (Frontend Seguro)

Server Components (Server-First):
  - Componentes por defecto.
  - Ejecutan lógica de negocio pesada, lectura de cookies y llamadas al backend.
  - Protegidos con 'serverRequireAuth' al inicio.

Client Components:
  - Exclusivos para interactividad (onClick, onSubmit, Zustand hooks).
  - Deben usar la directiva 'use client' explícitamente.
  - Mantenerse lo más atómicos y puros posible (sin lógica de negocio).

Route Handlers:
  - Ubicados en app/api/ y usados como proxies seguros para backend downstream o logs.

Estructura de Carpetas:
  app/                          ← Páginas, layouts y API Route Handlers
  components/ui/                ← Componentes visuales puros y reutilizables
  lib/                          ← Módulos utilitarios core (auth, logger, cypher)
  logs/                         ← Archivo logs centralizado (logs/app.log)

Antes de implementar cualquier Pantalla o Componente

Completar standards/05-client-insumos.md con las especificaciones de pantalla/mockups.
Confirmar los endpoints backend downstream y las políticas de logs.
Asegurar que las variables de entorno estén registradas en standards/04-configmap-management.md.
Consultar Engram antes de programar: ¿hay decisiones previas sobre este componente o integración?

Memoria persistente — Engram

Engram preserva las decisiones de diseño frontend que el agente suele olvidar al cerrar la sesión.

Reglas de uso

CUÁNDO LEER (siempre al inicio):
  - Antes de implementar una pantalla o componente → buscar decisiones previas del flujo
  - Antes de configurar variables o endpoints → buscar llaves configuradas anteriormente
  - Si un flujo de autenticación o encriptación falla → buscar gotchas documentados

CUÁNDO ESCRIBIR (al finalizar):
  - Cada decisión que altere la arquitectura base (ej. "usar mock de datos temporal para la cuenta de ahorros")
  - Cada llave de configuración agregada a .env
  - Cada gotcha o comportamiento no documentado de daisyUI o Next.js
  - El resultado del code-review-excellence si tuvo violaciones corregidas

FORMATO DE ESCRITURA:
  Componente/Flujo: <nombre del flujo o componente>
  Decisión: <qué se decidió y por qué>
  Fecha: <YYYY-MM-DD>
  Contexto: <breve explicación técnica>

Engram Cloud — Sincronización entre desarrolladores

# Configurar el servidor cloud
engram cloud config --server https://engram.pranical.com

# Enrollar el proyecto frontend-ai
engram cloud enroll frontend-ai

# Sincronizar memorias del proyecto al cloud
engram sync --cloud --project frontend-ai

Orquestación Multi-Agente — Nivel 1 (activa)

El agente principal coordina y delega tareas a subagentes autónomos cuando se trabaja en componentes paralelos.

Cuándo usar subagentes

USAR subagentes cuando:
  - Se implementa el Layout general y la Página individual en paralelo
  - Se desarrolla una API Route (/api/...) y la UI del Cliente al mismo tiempo
  - Se genera documentación técnica de los componentes en paralelo

NO usar subagentes cuando:
  - Es debugging de estado compartido en Zustand
  - Se realizan cambios de middleware que impactan a toda la app

Convenciones de Log (Trazabilidad Centralizada)

Server Logs:
  - Escritos directamente en logs/app.log a través de lib/logger/server-logger.ts.
Client Logs:
  - Llaman a lib/logger/client-logger.ts, que envía un POST /api/logs para persistirlo en logs/app.log.

Formatos de Prefijos obligatorios:
  [INFO] Login success | {"userId":"123"}
  [WARN] Unauthorized access attempt | {"path":"/dashboard"}
  [ERROR] Backend connection failed | {"error":"ECONNREFUSED"}

Control de Cookies y Headers Bancarios

access_token   ← Cookie HTTP-only, Secure (en prod), SameSite=strict
refresh_token  ← Cookie HTTP-only, Secure (en prod), SameSite=strict
traceId        ← deviceSessionReference del cliente propagado en las llamadas al API Route

Checklist pre-entrega (ejecutar siempre)

Server Pages / Layouts:
[ ] serverRequireAuth() invocado en la cabecera si la ruta es protegida
[ ] Sin interactividad del cliente (sin onClick, useState, useAuthStore en este nivel)
[ ] Manejo de errores perimetral con Next.js error.tsx

Client Components:
[ ] 'use client' presente en la línea 1
[ ] Estado global obtenido a través de useAuthStore o Zustand hooks específicos
[ ] Consumo de datos sensibles encriptado/desencriptado usando lib/cypher
[ ] Enrutado de logs a través de client-logger

Route Handlers (API):
[ ] POST /api/logs recibe logs del cliente sin colisiones
[ ] Autenticación de sesión validada antes de proxyar peticiones al backend

Reglas de oro (nunca romper)

Código:

NUNCA guardes JWT, secretos ni credenciales en localStorage, sessionStorage o variables de Javascript del cliente. Usa cookies HTTP-only.
NUNCA realices llamadas directas al backend desde Client Components sin pasar por el middleware o API Route correspondiente si requiere auth.
NUNCA utilices useEffect para sincronizar estados que pueden resolverse mediante React Server Components o Zustand.
SIEMPRE registra logs de actividades críticas (login exitoso, fallido, logout, errores) en logs/app.log.
SIEMPRE actualiza el grafo de Graphify (graphify update .) tras cambios estructurales.

Memoria (Engram): 6. SIEMPRE consulta Engram antes de implementar para verificar decisiones previas del flujo. 7. SIEMPRE registra en Engram las decisiones críticas y de diseño. 8. NUNCA guardes secretos ni código completo en Engram.

Checklist pre-PR (ejecutar desde el agente)

Haz una revisión completa con code-review-excellence
comparando la implementación contra el checklist de AGENT.md.
Reporta cualquier violación antes de continuar.

6.9 KiB Raw Permalink Blame History