Guía de desarrollador · quote-developer

quote-developer: guía técnica

Cómo genera el agente el PDF de cotización de alcance y llena la plantilla XLSX del equipo Campus, qué celdas puede tocar y cómo se verifica que ambos cuadren.

3 nov 2026Guía de desarrolladorClaude Code16 min de lectura

Descripción general

El Agente Desarrollador de Cotizaciones (quote-developer) convierte los alcances de un proyecto en dos entregables que deben contar exactamente el mismo alcance: un PDF de cotización de alcance con el desglose por módulos y precios, y el XLSX de cotización del equipo Campus, que corre el modelo de costos con las estimaciones de esfuerzo por especialidad.

Esta guía explica cómo está construido: la jerarquía de módulos, submódulos y funcionalidades que comparten el PDF y el Excel, qué celdas de la plantilla puede llenar y cuáles son intocables, cómo se estiman los días, cómo se diseña el PDF y cómo se comprueba que todo cuadre antes de entregar. Está pensada para quien mantiene el agente.

Qué hace y qué no hace

Cómo corre: Claude Code y CLAUDE.md

Corre en Claude Code y se gobierna con CLAUDE.md, que lee al inicio de cada sesión y se co-evoluciona con el usuario. Las páginas de wiki/ (plantilla-xlsx.md, diseno-pdf-cotizacion.md, perfil-usuario.md) son espejos consultables de partes de CLAUDE.md: si alguna difiere, manda CLAUDE.md, y los espejos se actualizan junto con él.

Decisiones fundacionales

Estructura del repositorio

quote-developer/
  CLAUDE.md                       # rol, reglas del PDF y del XLSX
  wiki/
    index.md                      # catálogo y resumen de cotizaciones entregadas
    log.md                        # bitácora (solo se añade)
    perfil-usuario.md             # rol y reglas de oro
    marca-campuslands.md          # identidad general + diseño vigente del PDF
    diseno-pdf-cotizacion.md      # espejo del diseño del PDF
    plantilla-xlsx.md             # mapeo de celdas de la plantilla
  cotizaciones/
    <slug-cliente>/               # un cliente
      Cotizacion de Alcance.pdf
      Cotizacion.xlsx
    <slug-cliente>/<slug-proyecto>/  # un cliente con varios proyectos
  recursos/                       # solo lectura
    FullServices - Plantilla Cotizaciones.xlsx  # plantilla maestra: nunca se edita

Reglas de carpetas

• wiki/ y cotizaciones/ son del agente; recursos/ es solo lectura.
• Para cada cliente nuevo, el agente copia la plantilla maestra a cotizaciones/<slug>/Cotizacion.xlsx y trabaja sobre la copia. Nunca modifica la plantilla maestra.
• Nomenclatura corta (vigente desde 2026-08-06): Excel tiene un límite de longitud de ruta más estricto que el de Windows (260 caracteres); una ruta de unos 236 caracteres falla con «no hemos encontrado el archivo» aunque el archivo sea válido. Por eso los nombres de archivo y carpeta son cortos y sin tildes, y la ruta completa se mantiene bajo unos 180 caracteres. Para un cliente con varios proyectos se usa cotizaciones/<slug-cliente>/<slug-proyecto>/, con archivos simplemente Cotizacion.xlsx y Cotizacion de Alcance.pdf (el cliente y el proyecto ya están en la ruta).

El flujo de trabajo

1. RecibirAlcances y razón social. Si hay ambigüedad, pregunta antes de seguir.
2. PDF de alcancePor módulos, submódulos y funcionalidades, con «Pendiente de costear».
3. Llenar XLSXSolo L/M/N, días B:K y las dos celdas permitidas.
4. RecalcularRecalcula y reescribe el PDF con los precios leídos del XLSX.
5. VerificarPDF = XLSX, cero errores de fórmula, doble verificación de precios.
6. EntregarAmbos archivos en la carpeta del cliente; wiki y bitácora al día.

1. Recibir. El usuario comparte los alcances (texto, notas, brief) y el nombre o razón social del cliente.
2. Preguntar ante la duda. Si hay ambigüedad en el alcance, en el esfuerzo o en cualquier dato necesario para cotizar, el agente pregunta directamente antes de continuar.
3. Generar el PDF. Sigue la plantilla visual, organizado por módulos. En esta etapa el valor de cada fila aún dice «Pendiente de costear».
4. Llenar el XLSX. Con el PDF validado por el usuario, usa el desglose de módulos, submódulos y detalles para llenar la plantilla.
5. Recalcular y poner precios. Recalcula el XLSX y actualiza el PDF reemplazando «Pendiente de costear» por los precios reales.
6. Verificar. Comprueba que ambos archivos reflejen el mismo alcance, que el XLSX recalcule sin errores, que ningún día sea menor a 0,5 ni esté en la celda equivocada, y que los precios del PDF coincidan con el XLSX.
7. Entregar ambos archivos y actualizar wiki/index.md y wiki/log.md.

La plantilla XLSX

La plantilla maestra (hoja Plantilla) ya trae todas las fórmulas de costeo montadas por el equipo Campus: las columnas A y P a AC, la fila 121 en adelante, etc. El agente solo llena dos tipos de celda.

La jerarquía L / M / N

Desde el 2026-08-05 la jerarquía es flexible: la cantidad de funcionalidades (N) bajo cada submódulo (M) es libre, tantas como el alcance real necesite. Queda prohibido forzar «un submódulo, una descripción».

Cada fila L, M o N ocupa su propia fila; las otras dos columnas de esa fila quedan vacías. Un ejemplo de estructura correcta:

L: MÓDULO A - descripción breve
M: Submódulo 1
N: Funcionalidad 1 (con sus días)
N: Funcionalidad 2 (con sus días)
N: Funcionalidad 3 (con sus días)
M: Submódulo 2
N: Funcionalidad 1 (con sus días)
L: MÓDULO B - descripción breve
M: Submódulo 1
N: Funcionalidad 1 (con sus días)

El criterio de cardinalidad es una pregunta: ¿cuántas funcionalidades atómicas y realmente distintas describe el alcance para ese submódulo? Ni una menos (no resumir dos funcionalidades reales en una fila), ni una de más forzada para aparentar detalle. En la columna L no hay numeración M1. o M2. (a diferencia del PDF).

Filas fijas y zonas de la hoja

Las dos celdas autorizadas

Son las únicas excepciones a la zona intocable. Se ubican en relación con la «barra gris», la fila con relleno gris sólido (#999999) en la columna L que cierra la tabla de alcance. En la plantilla maestra está en la fila 120, pero se desplaza si se insertaron filas por un alcance grande, y ambas celdas se mueven con ella.

Antes de escribir en cualquiera de las dos, el agente confirma que esté vacía o con el valor esperado, y confirma R por la etiqueta AIU de la columna Q de esa fila, no solo por el número. Si ya contiene datos de una fila real de alcance, no la sobrescribe: reporta el conflicto.

Si el alcance necesita más filas

Se insertan filas (nunca se sobrescribe la zona de fórmulas de resumen) y se verifica que las fórmulas de las columnas A, X, Y, AB y AC se hayan propagado en las filas nuevas antes de recalcular. Esto ya ocurrió en cotizaciones grandes, donde también hubo que reparar referencias de validaciones de datos y formatos condicionales que apuntaban a las filas límite.

Aclaraciones sin celda propia

Si el usuario pide dejar una condición sobre una fila o módulo («este cobro aplica solo si…») y no hay dónde escribirla sin tocar valores o fórmulas, se usa un comentario de celda de Excel sobre la celda L o M relevante. No cambia ningún valor ni fórmula, es visible al pasar el cursor y sobrevive al recálculo con LibreOffice.

La estimación de días

Las columnas B a K corresponden a estas especialidades:

Las reglas de estimación, vigentes desde el 2026-08-05:

• El estimado va siempre en la fila de la funcionalidad (N). El submódulo (M) nunca lleva días: es un encabezado de agrupación, no una unidad de esfuerzo.
• Cada N tiene su estimado independiente. Nunca se reparte ni se promedia un solo estimado entre varias filas.
• Solo se llenan las especialidades que participan. Las demás quedan vacías, no en 0.
• Piso mínimo de 0,5. Si la estimación real da menos (por ejemplo 0,23), se redondea a 0,5; por encima, se puede usar cualquier decimal realista (0,8; 1,5; 2,5).
• Se estima como lo haría un desarrollador real: complejidad técnica, integraciones externas y alcance descrito, nunca un valor genérico por defecto.

Cuando la fuente ya trae esfuerzo en horas por rol, la conversión usada en entregas anteriores fue horas ÷ 8 = días, con el piso de 0,5 por especialidad, repartiendo las horas entre funcionalidades atómicas.

El PDF de cotización

Diseño

El diseño vigente desde el 2026-07-17 usa la paleta clara de marca con el contenido en un grid con líneas delgadas, tanto horizontales como verticales, como una hoja de cálculo.

Contenido

• 100 % verídico: solo lo que el usuario compartió o confirmó. Cero relleno genérico.
• Espejo del XLSX: el PDF nunca muestra menos ni más nivel de detalle que el cargado en el Excel. Módulo es L, submódulo es M y funcionalidad es N.
• Atomicidad de bullets compuestos (desde 2026-08-06): un bullet de la fuente que une varias cosas con «y» o comas se divide solo si cada una es una capacidad distinta (verbos o acciones diferentes). No se divide si enumera dimensiones de una sola capacidad: «por series, subseries, expedientes y dependencias» es una taxonomía, una funcionalidad.
• Nota de contexto técnico: si la fuente trae «Componente tecnológico principal» o «Clasificación» por producto, se agrega como nota informativa en cursiva gris bajo el objetivo, sin precio y fuera de la tabla. Se omite si la fuente no los trae.

Precios en el PDF

Después de llenar el XLSX, el agente reemplaza «Pendiente de costear» por los precios reales:

1. Recalcula el XLSX con recalc.py, con cero errores fuera de A140:A144.
2. Lee los precios por fila desde la columna A del XLSX ya recalculado (data_only=True): nunca los calcula ni los transcribe a mano.
3. Hace una doble verificación antes de entregar:
   • Cada precio de línea del PDF coincide exactamente con su celda de origen.
   • La suma de los ítems de cada módulo coincide con el subtotal de su banda, y la suma de todos los módulos (incluidas las filas transversales 2 a 5) coincide exactamente con el TOTAL del XLSX.

Verificación obligatoria

El defecto preexistente de A140:A144 es un #NAME? o #ERR520 causado por una fórmula UNIQUE() que LibreOffice no soporta. Está también en la plantilla maestra en blanco y no lo introduce el llenado del agente.

Entorno y herramientas

La carpeta no incluye scripts propios: el agente se apoya en herramientas del entorno.

Dos trampas en Windows

Registradas en la bitácora y que conviene conocer:

1. PATH. Agregar LibreOffice al inicio del PATH hace que su Python sombree al del sistema (que tiene openpyxl). Hay que agregarlo al final.
2. soffice.py. El script de la skill falla en Windows por socket.AF_UNIX; se resolvió con un envoltorio que reemplaza get_soffice_env y run_soffice antes de ejecutar recalc.py, sin tocar la skill.

Además, LibreOffice reescribe al recalcular los booleanos de la columna AB (los checkboxes) como =TRUE() y =FALSE(). Tienen el mismo valor, por lo que no se corrige.

Comandos «!»

Los comandos son órdenes cortas del usuario (!optimize, !notime…) que el agente debe ejecutar de forma obligatoria, siempre dentro de sus reglas duras. Hay un solo catálogo para todos los agentes y de él salen las instrucciones de cada uno, las bitácoras y las tablas de las guías.

Dónde vive cada cosa

La regla común

1. Un comando es una palabra precedida de ! al inicio de un mensaje o de una línea; el texto que sigue es su objeto.
2. Es obligatorio: el agente no pide permiso ni lo reinterpreta. Solo lo limita una regla dura (veracidad, marca, confidencialidad, puertas de aprobación y de verificación); entonces hace lo que la regla permite y dice qué no pudo.
3. Se combinan. Si dos modos chocan, el orden es: reglas duras > !strict-mode y !no-assumptions > !think-deep, !critical-mode y !double-check > !notime.
4. Rige la tarea en curso, no las siguientes.
5. La primera línea de la respuesta nombra los comandos recibidos.
6. Un comando desconocido no se adivina: se propone el más parecido y se pregunta. !help lista los disponibles.
7. Si un comando cambió un entregable o la wiki, se anota en wiki/log.md.

Cómo añadir o cambiar un comando

1. Edita CMDS (definición), AGENTES (a quién aplica y su nota) o ALIAS en resources/comandos/comandos.py.
2. Corre python -X utf8 resources/comandos/comandos.py: reescribe la sección de cada agente, el catálogo y, la primera vez, añade la entrada a su bitácora.
3. Recompila las guías (python guides/_src/build.py).
4. python resources/comandos/comandos.py --verificar falla si algo quedó desfasado.

Comandos de este agente

General

Modos

Técnico y seguridad

UX/UI y diseño

Gestión de proyecto

IA avanzada

Multiagente

Mantenimiento

La bitácora wiki/log.md es append-only y cada entrada empieza con ## [YYYY-MM-DD] <tipo> | <descripción>, con tipos setup, build, ajuste, deploy y lint. En el lint periódico se revisan contradicciones, información desactualizada, páginas huérfanas y convenciones de diseño que ya no se usan.

Problemas frecuentes

Cosas que no están alineadas

Varias referencias de CLAUDE.md y de la wiki apuntan a archivos que hoy no existen en esta carpeta:

• Cita scripts/recalc.py, pero la carpeta no tiene scripts/: recalc.py viene de la skill de xlsx.
• Cita wiki/flujo-trabajo.md, que no existe; el flujo vive en CLAUDE.md.
• wiki/plantilla-xlsx.md toma cotizaciones/comultrasan/Financiera Comultrasan - Cotizacion.xlsx como referencia de cardinalidad variable; ese archivo sí existe en esta carpeta.

Referencia rápida de archivos