--- name: frailen-empezar area: Empezar description: |- Pásale esta guía a tu agente de código para preparar Frailen en un repositorio: las fichas desde el OpenAPI, la ruta del token, la etiqueta del chat y los primeros casos del banco de pruebas, todo en una rama. title: 'Prepara a tu agente para Frailen' url: https://frailen.com/es/get-started.md --- # Prepara Frailen con tu agente de código Usa esta guía para preparar el repositorio actual para Frailen. Tú haces el trabajo en una rama nueva; una persona de la empresa aprueba las herramientas y prende el agente con su passkey. ## Cómo correrla Corre las secciones en orden, en el repositorio actual. Haz tú las acciones cuando tengas acceso a la terminal o a los archivos; no te limites a devolver comandos para que el usuario los copie. Detente solo para las decisiones que son de una persona: qué operaciones puede tocar el agente, el id de la empresa y cualquier cosa sobre producción. Si un paso queda bloqueado, anota por qué y sigue con los demás. Nunca apruebes, publiques ni despliegues nada. Nunca pongas sesiones, tokens ni llaves en registros, commits ni URLs. El CLI de Frailen (`@frailen/cli`) y su servidor MCP todavía no están: todo aquí funciona con archivos del repositorio. Referencia: [llms.txt](https://frailen.com/es/llms.txt) · [Para desarrolladores](https://frailen.com/es/desarrolladores.md) · [Seguridad](https://frailen.com/es/seguridad.md) ## 0. Abre una rama ```sh git status git switch -c frailen ``` Si hay cambios sin commit, pregunta antes de cambiar de rama. ## 1. Encuentra la API Busca una especificación OpenAPI (`openapi.yaml`, `openapi.json`, `swagger.json`, o la que genere el framework). Si no hay, haz la lista de rutas desde el código: routers, controladores, handlers. Escribe en `frailen/operaciones.md` las operaciones que necesitaría un agente de soporte, una por línea, y marca las que mueven dinero, tocan muchos registros a la vez, le llegan a terceros (correos, WhatsApp, avisos) o no se deshacen. Pídele al usuario que confirme la lista antes de escribir las fichas de escrituras. ## 2. Escribe las fichas Una ficha por operación en `herramientas/.yaml`. El formato tiene sus claves en español: ```yaml reembolsar_factura: descripcion: Reembolsa una factura cobrada, entera o en parte metodo: POST ruta: /v1/invoices/{factura_id}/refunds parametros: type: object properties: factura_id: { type: string } monto: { type: number } required: [factura_id, monto] patron: cobrar # consultar, cambiar, pausar, agendar, cobrar, avisar, borrar, reportar se_deshace_con: ~ # la herramienta que lo deshace, o ~ si no se deshace dano: [dinero, sin_reversa] relee_con: herramienta: ver_factura compara: [estado, reembolsado] ``` Reglas: - Solo un GET puede ser una lectura. Todo lo demás es una escritura y pasa por el freno. - Ponle a cada escritura sus banderas de daño: `dinero`, `masivo`, `terceros`, `sin_reversa`. Un monto en el cuerpo es `dinero`; una acción sobre toda una colección es `masivo`. - Pon `se_deshace_con` solo si existe una reversa de verdad. Si dudas, deja `~`. - `relee_con` nombra la herramienta GET y los campos que prueban que la escritura quedó. - Nunca bajes ni quites una bandera de daño para que algo pase. Termina con la lista de operaciones que dejaste fuera y por qué. ## 3. Agrega la ruta del token Agrega `POST /frailen/token` al backend (canje de tokens, RFC 8693): - Recibe como `subject_token` la sesión que firma tu backend: un JWT ES256, verificado contra tu JWKS. - Devuelve un token Bearer de ese mismo usuario, con `expires_in` de 300 segundos o menos. - Agrega pruebas para una sesión válida, una vencida y una alterada. Si las sesiones se firman con un secreto compartido (HS256), detente y pregunta: Frailen necesita una llave asimétrica, porque con un secreto compartido podría firmar por cualquiera. Nunca escribas la sesión ni el token en los registros. ## 4. Monta el chat Agrega la etiqueta al layout principal de la app: ```html ``` - Pídele al usuario el id de la empresa si no lo sabes. - Agrega la ruta `/frailen/asercion`: firma una aserción ES256 de 60 segundos para el usuario con sesión. - `@frailen/chat-web` (código y React) todavía no está publicado: usa la etiqueta. ## 5. Escribe los primeros casos del banco De tres a cinco casos en `pruebas/.yaml`, para los pedidos que más recibe el equipo de soporte: ```yaml id: mover_vencimiento escrito: # la regla se escribe antes de correr persona: mensajes: - Pasa el vencimiento de la factura F-2291 al 30 de noviembre espera: # se juzga releyendo, no leyendo la respuesta - herramienta: ver_factura argumentos: { factura_id: F-2291 } campos: { vence: "2026-11-30" } regla: Pasa si F-2291 vence el 30 de noviembre y F-2290 no cambia. ``` Al menos un caso tiene que comprobar que otra cosa no cambió. ## 6. Deja las reglas para los próximos agentes Agrega esto al `AGENTS.md` (o al `CLAUDE.md`), y créalo si no existe: ```markdown ## Frailen - Antes de tocar archivos de Frailen, lee https://frailen.com/es/llms.txt (y https://frailen.com/es/llms-full.txt si necesitas el detalle). - Las fichas van en herramientas/*.yaml y los casos del banco en pruebas/*.yaml. - Solo un GET puede ser una lectura. Toda escritura lleva sus banderas de daño; nunca quites una para que pase una prueba. - Nunca escribas en registros ni subas al repositorio sesiones, tokens ni llaves. - Tú preparas la integración en una rama. Una persona aprueba las herramientas y prende el agente con su passkey: tú nunca apruebas, publicas ni despliegas. ``` ## 7. Termina Haz commit en la rama. No hagas push a menos que el usuario lo pida. Después informa: - Los archivos que creaste o cambiaste. - Las operaciones cubiertas y las que quedaron fuera, con el motivo. - Las banderas de daño o las reversas que necesitan la decisión de una persona. - Cualquier paso bloqueado y por qué. - Lo que sigue para la empresa: aprobar las herramientas en el panel de Frailen, correr el banco de pruebas en staging y prender el agente con una passkey.