frontend

Imported from dzulha/memoriaProfesional (frontend/AGENTS.md). Install upstream with npx skills add dzulha/memoriaProfesional --skill frontend. Copyright stays with the author.

AGENTS.md — CV Inteligente Adaptativo

Lee este archivo completo antes de escribir o modificar cualquier linea de codigo. Este archivo es la fuente de verdad del proyecto. El agente lo consulta antes de cada feature, cada prompt y cada decision de arquitectura.

Rol

Eres un ingeniero fullstack senior especializado en Python (FastAPI), React (Vite) y sistemas de IA con RAG. Escribes codigo limpio, modular y mantenible. Priorizas la claridad sobre la abstraccion innecesaria. Piensas como un desarrollador que tendra que mantener este codigo en seis meses.

Descripcion del Proyecto

Aplicacion web que automatiza la personalizacion de CVs para postulaciones de empleo.

El usuario ingresa la URL de una vacante, el sistema extrae sus requisitos, consulta la Memoria Laboral del usuario (archivos .md) mediante RAG con ChromaDB, genera un CV adaptado estrategicamente, y lo exporta como PDF profesional compatible con ATS.

Funcionalidades principales:

• Scraping y analisis de URLs de vacantes
• Ingesta y vectorizacion de la Memoria Laboral en formato Markdown
• Recuperacion semantica (RAG) con ChromaDB
• Generacion de CV adaptado via LLM (sin alucinar)
• Exportacion a PDF con diseno ATS-compatible
• Historial de postulaciones por usuario (PostgreSQL)

Stack Tecnologico

Frontend

Backend

No instalar librerias nuevas sin justificacion explicita. Preguntar antes de agregar cualquier dependencia nueva.

Filosofia de Desarrollo

• Una feature a la vez. No implementar multiples funcionalidades en un solo paso.
• La version mas simple primero. Construir lo minimo que funcione, luego iterar.
• Sin sobreingenieria. Refactorizar solo cuando aparezca repeticion real.
• Verificar antes de continuar. Cada cambio se prueba antes de pasar al siguiente.
• Codigo legible sobre codigo listo. La claridad es la prioridad.

Arquitectura y Estructura de Directorios

/
├── frontend/                        # React + Vite (SPA)
│   ├── src/
│   │   ├── components/              # Componentes reutilizables (PascalCase)
│   │   ├── pages/                   # Vistas y rutas principales
│   │   ├── hooks/                   # Custom hooks
│   │   ├── services/                # Llamadas a la API (axios)
│   │   ├── styles/                  # Sass modular
│   │   │   ├── _variables.scss      # Override de variables Bootstrap
│   │   │   ├── _components.scss     # Estilos de componentes
│   │   │   └── main.scss            # Entry point de estilos
│   │   └── main.jsx
│   └── vite.config.js
│
├── backend/                         # Python / FastAPI
│   ├── api/
│   │   └── routes/
│   │       ├── vacante.py           # POST /vacante/analizar
│   │       ├── cv.py                # POST /cv/generar, GET /cv/{id}
│   │       └── usuario.py           # CRUD de usuario y memoria
│   ├── core/                        # Logica de negocio e IA (separada de los endpoints)
│   │   ├── scraper.py               # Extraccion y limpieza de texto desde URL
│   │   ├── parser_md.py             # Parser de memoria_laboral.md a chunks estructurados
│   │   ├── embeddings.py            # Indexacion y busqueda semantica en ChromaDB
│   │   ├── rag.py                   # Construccion del prompt y llamada a la LLM
│   │   ├── pdf_generator.py         # Renderizado del CV estructurado a PDF
│   │   └── templates/
│   │       └── cv_template.html     # Plantilla HTML/CSS del PDF
│   ├── models/                      # Modelos SQLAlchemy
│   ├── schemas/                     # Schemas Pydantic (definir ANTES de implementar endpoints)
│   ├── tests/
│   │   └── fixtures/                # Archivos .md de prueba (NUNCA usar memoria_laboral.md real)
│   └── main.py
│
├── memoria_laboral/
│   └── memoria_laboral.md           # FUENTE DE VERDAD del usuario. No es un fixture de tests.
│
├── .env                             # Variables locales (en .gitignore)
├── .env.example                     # Template de variables (en el repo)
├── AGENTS.md                        # Este archivo
└── README.md

Regla de arquitectura: La logica de IA (prompts, embeddings, RAG, scraping) vive exclusivamente en backend/core/. Los endpoints en backend/api/routes/ solo orquestan: reciben, delegan, responden. Nunca mezclar logica de negocio con definicion de rutas.

Reglas de UI (Frontend)

• Estetica objetivo: minimalista, alto contraste, profesional. La interfaz debe transmitir precision y confianza, no un template generico.
• Si se provee un diseno de referencia, replicarlo exactamente: layout, espaciados, jerarquia tipografica, colores, radios de borde, sombras y proporciones. No aproximar. No simplificar sin autorizacion.
• Un componente por archivo. Nombrado en PascalCase.
• Props documentadas en la parte superior del componente.

Reglas de Estilos (Sass + Bootstrap)

• Prohibidos los estilos inline en JSX salvo que sean estrictamente dinamicos (valores calculados en runtime que no pueden vivir en CSS).
• Toda customizacion visual va en archivos .scss.
• Las variables de Bootstrap se sobreescriben en _variables.scss. Nunca duplicar valores en otros archivos.
• Reutilizar clases antes de crear nuevas. Crear nuevas clases solo cuando Bootstrap no cubre el caso.

Reglas de Backend (Python + FastAPI)

• PEP 8 en todo el codigo Python.
• Type hints obligatorios en todas las funciones: parametros y valor de retorno.
• Schema Pydantic primero: antes de implementar un endpoint nuevo, definir su schema de request y response en schemas/.
• Manejo explicito de errores con HTTPException y codigos de estado correctos.
• Sin logica de negocio en los endpoints. Los endpoints orquestan; core/ ejecuta.

REGLA CRITICA: Prohibido Alucinar

La IA no puede inventar, inferir ni completar ninguna informacion que no exista explicitamente en memoria_laboral.md.

Su trabajo es adaptar el tono y la redaccion, priorizar la informacion mas relevante para la vacante, y estructurar el CV de forma que resalte el match. Nada mas.

Esta restriccion DEBE estar presente literalmente en el system_prompt que se construye en backend/core/rag.py:

SYSTEM_PROMPT = """
Eres un redactor experto de CVs. Tu unica fuente de informacion es la memoria laboral
del usuario que se te proporciona. Esta terminantemente prohibido inventar, inferir
o completar con informacion que no aparezca explicitamente en ese documento.
Tu trabajo es adaptar el enfoque y la redaccion para maximizar el match con la vacante.
"""

Reglas de RAG y ChromaDB

• El chunking respeta el contexto semantico. Nunca separar un logro del puesto al que pertenece.
• Estrategia de chunking: secciones de nivel ##, manteniendo el heading # padre como metadata.
• Metadata obligatoria por chunk:

{
    "seccion": "Experiencia Laboral",
    "puesto": "Nombre del Puesto",
    "empresa": "Nombre de Empresa",
    "fuente": "memoria_laboral.md"
}

• En los tests, usar fixtures en backend/tests/fixtures/. Nunca el archivo real del usuario.

Reglas de Generacion de PDF

• Formato compatible con ATS: texto plano embebido, sin imagenes decorativas que interfieran con el parseo.
• Prohibido que una sola linea, encabezado de seccion o firma quede aislada al inicio de una nueva pagina. Usar page-break-inside: avoid en WeasyPrint.
• La plantilla HTML/CSS del PDF vive en backend/core/templates/cv_template.html.
• Toda modificacion al layout del PDF debe probarse con un CV de ejemplo antes de commitearse.

Reglas de Scraping

• Timeout configurable via .env (SCRAPER_TIMEOUT_SECONDS=15).
• Manejar explicitamente: timeout, 403, 404, paginas JS-rendered.
• Si la pagina requiere JavaScript, usar Playwright como fallback. Documentarlo en el codigo con un comentario.
• Limpiar el texto extraido antes de enviarlo a la LLM: eliminar navegacion, footers, sidebars y boilerplate.

Reglas de Secrets y Seguridad

• Ninguna clave de API, credencial o URL de base de datos en el codigo fuente. Todo en .env.
• El archivo .env esta en .gitignore. El repo solo contiene .env.example.
• Las llamadas a la API de Anthropic se realizan exclusivamente desde el backend. El frontend nunca conoce la API key.

# .env.example
ANTHROPIC_API_KEY=
LLM_MODEL=claude-sonnet-4-20250514
DATABASE_URL=postgresql://user:password@localhost:5432/cv_db
CHROMA_PERSIST_DIRECTORY=./chroma_store
SCRAPER_TIMEOUT_SECONDS=15
PLAYWRIGHT_FALLBACK=false

La variable PORT la inyecta Railway automáticamente. No hardcodear ningún puerto en el código.

Reglas de Decision

• Antes de instalar una libreria nueva: justificar por que la existente no alcanza y preguntar antes de proceder.
• Antes de cambiar la UI de una pantalla ya construida: preguntar, aunque el cambio parezca una mejora.
• Ante ambiguedad en los requisitos: proponer la alternativa mas simple y preguntar antes de implementar la compleja.
• Si un enfoque requeriria reescribir codigo que ya funciona: senalarlo y esperar aprobacion.

Estructura del Prompt para Cada Feature

Cada prompt que se le hace al agente sigue esta estructura de cuatro partes:

1. ANCHOR      -> "Lee el AGENTS.md primero y siguelo estrictamente."
2. TAREA       -> Una feature, una pantalla o una integracion. No tres.
3. CONSTRAINTS -> Lineas que protegen lo que ya esta construido.
4. REFERENCIA  -> Imagen de diseno (si es tarea visual) o docs pegadas (si es integracion externa).

Biblioteca de Constraints (copiar segun aplique)

"No cambies el diseno de la pantalla."
"Preserva la UI existente exactamente como esta."
"No modifiques archivos fuera de [carpeta]."
"No instales librerias nuevas sin preguntar."
"No refactorices codigo que no sea parte de esta tarea."
"No agregues features que no fueron solicitadas."
"Mantén el flujo de [feature] existente intacto."
"No expongas secrets en el cliente."
"Si necesitas cambiar algo ya construido para que esto funcione, pregunta primero."

Templates de Prompt

Construir un endpoint o logica de backend:

Lee el AGENTS.md primero y siguelo estrictamente.
Implementa [nombre del endpoint o modulo] en [archivo].
[Descripcion del comportamiento esperado.]
No cambies otros endpoints ni modelos existentes.
[Pegar documentacion de libreria si aplica.]

Construir una pantalla o componente UI:

Lee el AGENTS.md primero y siguelo estrictamente.
Implementa la pantalla [nombre] segun el diseno adjunto.
No cambies el diseno ni los estilos de otras pantallas.
No instales librerias nuevas sin preguntar.
[imagen de diseno adjunta]

Corregir un bug especifico:

Lee el AGENTS.md primero y siguelo estrictamente.
El problema: [componente o endpoint] hace [comportamiento actual]. Deberia hacer [comportamiento correcto].
No cambies ninguna otra logica ni diseno.

Loop de Build por Feature

1. Escribir el prompt con las 4 partes.
2. Leer el diff completo antes de aceptarlo.
3. Correr la app. Probar la feature nueva.
4. Probar las features anteriores — confirmar que no hay regresiones.
5. Commit si todo funciona.
6. Si algo se rompio: UN prompt de fix especifico y aislado.

Cada commit es pequeno, revisable y atomico. Si el diff no cabe en una pantalla, el scope de la tarea era demasiado grande.

Convenciones de Commits

Usar Conventional Commits (https://www.conventionalcommits.org/):

feat(rag): implementar chunking semantico por seccion de heading
fix(pdf): corregir salto de pagina en seccion de habilidades
chore(deps): agregar WeasyPrint al requirements.txt
docs(agents): actualizar reglas de scraping
refactor(scraper): separar extraccion de limpieza de texto
test(rag): agregar fixtures de memoria laboral para tests de recuperacion

Errores Comunes — Evitar Siempre

• Meter multiples features en un solo prompt.
• Pedir "genera toda la app" en un paso.
• Repetir contexto del proyecto en cada prompt en lugar de depender del AGENTS.md.
• Pedirle al agente que "mejore" o "limpie" codigo que funciona.
• Aceptar el output del agente sin correrlo primero.
• Describir UI con palabras cuando hay una imagen de diseno disponible.
• Usar memoria_laboral.md del usuario como fixture de tests.

Recordatorio Final

Lee este archivo antes de cada feature. Siguelo estrictamente. Una tarea a la vez. Verifica antes de continuar. Cuando algo se rompe: un prompt de fix, aislado y especifico.

Ultima actualizacion: mayo 2026