Saltar a contenido

Para LLMs y agentes

Esta página explica cómo un modelo de lenguaje (LLM) o un agente autónomo debe consumir esta documentación y trabajar este repositorio sin romper las convenciones del equipo. Es una página de explicación: el porqué y el orden de las cosas, no un tutorial paso a paso.

Para quién es esto

Esta página está pensada para personas Y para agentes. Si eres un humano dirigiendo a un agente, dale este enlace primero. Si eres un agente, empieza por llms.txt (abajo) y vuelve aquí para el flujo de trabajo.

El sitio se publica en formato llms.txt

El build de la documentación (MkDocs Material) genera dos artefactos pensados para consumo por máquinas, siguiendo el estándar de llmstxt.org:

  • /llms.txt — un índice estructurado: un único fichero Markdown con el título del proyecto, una descripción y secciones de enlaces a las páginas .md individuales. Es ligero y está pensado para que un agente lo lea primero y decida qué páginas necesita.
  • /llms-full.txt — todo el contenido de la documentación concatenado en un solo fichero. Útil cuando quieres volcar el corpus completo en el contexto de una sola pasada, sin navegar enlace a enlace.

Además, MkDocs sirve cada página también de forma individual, accesible por su ruta .md, de modo que un agente puede seguir los enlaces de llms.txt y traer solo la página concreta que le hace falta.

Pauta de navegación para un agente

  1. Lee /llms.txt para obtener el mapa del sitio.
  2. Si necesitas el corpus entero de una vez, usa /llms-full.txt.
  3. Si solo necesitas un tema, sigue el enlace .md de esa página desde llms.txt.

Antes de tocar código: lee el conocimiento tribal

El repositorio guarda el conocimiento no obvio —lo que marca la diferencia entre un arreglo rápido y horas de depuración— en dos ficheros AGENTS.md:

  • backend/AGENTS.md — patrones reales del backend: estructura del proyecto, multitenancy, precios en céntimos, i18n, state machine de Comanda, migración a arquitectura hexagonal, arquitectura híbrida del chat, y las convenciones normativas.
  • frontend/AGENTS.md — el equivalente para el frontend.

No improvises sobre lo que dice AGENTS.md

Estos ficheros capturan precisamente lo que no puedes deducir leyendo cuatro ficheros sueltos. Si una instrucción de AGENTS.md contradice tu intuición, gana AGENTS.md. El fichero backend/CLAUDE.md simplemente re-exporta backend/AGENTS.md (@AGENTS.md) más un recordatorio de estilo de docstrings.

Reglas de arquitectura que un agente DEBE respetar

ADR-004: puertos, no imports cross-module

El backend está organizado en módulos hexagonales: app/modules/{módulo}/{domain,application,infrastructure,interface}/. La regla dura es:

  • Sin imports cross-module directos. La comunicación entre módulos va solo por puertos o eventos de dominio.
  • El código compartido vive en app/shared, nunca dentro de un módulo concreto.
  • HTTPException solo en interface/; las excepciones de dominio heredan de app.shared.domain.exceptions.DomainException.

Esto se hace cumplir automáticamente: make lint-arch (import-linter) es un gate duro en CI junto con pytest tests/contract/. Si introduces un import cross-module, el merge se bloquea.

Otras convenciones normativas

StrEnum en vez de magic strings; match/case sobre enums; value objects frozen; dinero siempre en céntimos (int) en BD; datetime siempre timezone-aware; método de entrada de los use cases siempre async def execute(...). El detalle completo está en backend/AGENTS.md.

El contrato es aditivo: backend y frontend viajan juntos

El contrato hacia el frontend (el OpenAPI snapshot y el contrato SSE) está protegido por tests de contract-lock:

  • tests/contract/openapi_snapshot.json — solo puede crecer en paths nuevos.
  • El contrato SSE (nombres de evento, forma de payloads, Content-Type: text/event-stream).

La regla operativa, autorizada de forma permanente por el owner del proyecto, es:

Las adiciones aditivas (añadir campos a respuestas, ampliar el contrato SSE, regenerar el snapshot) NO requieren sign-off, con una condición innegociable: en el MISMO cambio se cablea el frontend para consumir lo nuevo. Nunca un campo de contrato nuevo sin su consumo en el front.

Removals, renames y type-changes NO son aditivos

Eliminar, renombrar o cambiar el tipo de un campo existente rompe clientes desplegados y requiere sign-off explícito del usuario — no lo decide el agente.

Tests contra la BD camarero_qtest

Los tests e2e usan PostgreSQL real (no mocks), no sqlite. La base de datos de tests es camarero_qtest.

La variable EMBEDDINGS_ENABLED se ajusta según el caso:

  • En tests, por defecto va a false (lo fija tests/conftest.py): los tests stubean IntentClassifier.classify o usan embeddings fake. Nunca dependas del modelo de embeddings real en un test.
  • Actívala solo cuando el caso concreto valide explícitamente el camino con embeddings.

La señal de progreso durante la migración hexagonal NO es que uvicorn main:app levante, sino que pytest tests/{módulo}/e2e/ pase con el módulo ya viviendo en app/modules/.

Memoria persistente del proyecto y findings

  • Memoria persistente. El proyecto mantiene memoria de agente que persiste entre conversaciones (correcciones de contratos, fixes de bugs, features, entorno de desarrollo). Consúltala para no repetir errores ya documentados ni re-descubrir decisiones ya tomadas.
  • Convención de findings. Cualquier bug, lógica rara o deuda detectada se documenta en docs/findings/{YYYY-MM-DD}-{task}-{slug}.md con la plantilla del plan. Si una tarea no produjo hallazgos, deja explícito "Findings: ninguno." en su cierre.

Resumen del flujo para un agente

  1. Leer /llms.txt (o /llms-full.txt) para mapear la documentación.
  2. Leer backend/AGENTS.md y frontend/AGENTS.md antes de tocar código.
  3. Respetar ADR-004 (puertos, no imports cross-module) — lo verifica make lint-arch.
  4. Tratar el contrato como aditivo: backend + frontend en el mismo cambio.
  5. Correr los tests contra camarero_qtest con EMBEDDINGS_ENABLED según el caso.
  6. Consultar la memoria persistente y registrar findings al cerrar la tarea.

Páginas relacionadas