Saltar al contenido
Aula en la nube
Proyecto 2 · Sesión 2 · Semana 2-6 nov

Acciones predefinidas: acciones.json y el motor

Esta semana está la idea central del proyecto: tú decides qué hace tu herramienta escribiendo acciones.json; el agente programa el motor que lo interpreta. Y a la vez das el segundo paso con OpenCode: le enseñas tu esquema con una skill, te creas un comando propio para añadir acciones y un subagente revisor que lee tu código sin poder tocarlo.

El hilo del proyecto 2

Tus acciones son las tareas que te hacen perder tiempo.

Cada uno se construye una herramienta útil para sí mismo, y reutilizable. Esta semana la llenas: cada acción de tu acciones.json automatiza algo que hoy haces a mano, y la ejecutas con una orden cada vez que la necesites.

🗓 Semana 2 · 2-6 nov🧩 acciones.json → config → Motor → Accion🤖 skill · comando · subagente🛡 Excepciones propias📝 Primer ADR

En esta página

Al acabar la semana

Partes de lo que dejaste en la Sesión 1: el comando tareas con --help, version y listar, el repo con su .gitignore, tu opencode.json de permisos y tu AGENTS.md. Al acabar tendrás 3 acciones propias funcionando (siempre primero con --simular), las órdenes tareas validar, tareas acciones y tareas ejecutar, y esto en tu repo:

Tu herramientaTu procesocli-tareas/acciones.json · 3 acciones tuyasREADME.md · con el esquemasrc/tareas/errores.py · excepcionessrc/tareas/config.py · validasrc/tareas/acciones.py · las clasessrc/tareas/motor.py · el motorsrc/tareas/cli.py · las órdenesy además….opencode/skills/acciones-json/SKILL.md.opencode/commands/nueva-accion.md.opencode/agents/revisor.mddocs/adr/0001-configuracion-externa.mddocs/prompts.md≥ 10 commits · cuentan los de la Sesión 1

Desliza el diagrama de lado para verlo entero

A la izquierda, lo que hace tu herramienta; a la derecha, cómo la has construido con el agente.

Semipresencial: lo que se comprueba el 6 nov

Esto es exactamente lo que se comprueba el viernes 6 de noviembre, al cerrar la quincena 3: 3 acciones propias funcionando, el ADR y commits reales en tu repo.

En casa trabajas también con OpenCode (puedes abrirlo en la terminal integrada de VS Code); cómo conectarte desde casa a los modelos del centro lo explica el profesor en la tutoría colectiva de arranque.

Por qué configuración externa y no código

Piensa en el mando de la tele. El fabricante programa una vez lo que hace cada botón (el motor), pero qué canal está en el 1 lo decides tú en el menú, sin abrir el aparato. Si para cambiar el canal del botón 1 tuvieras que soldar algo dentro, nadie lo haría. Con tu herramienta pasa igual: si cada acción es una función escrita en Python, cambiar «mueve los PDF» por «mueve los PDF y los EPUB» exige tocar código, probarlo y reinstalar. Si vive en un fichero de configuración, cambias una línea.

El cambio: mover también los EPUBEn el códigoEn acciones.jsonEditar Pythonla funciónProbarlootra vez enteroReinstalarla herramientaPor fintras tres pasosCambiar una líneaen el JSONListosin tocar Python

Desliza el diagrama de lado para verlo entero

Si la acción es código, cada cambio pasa por tocar, probar y reinstalar. Si es configuración, cambias una línea.

Lo usas todos los días

No es un invento del curso: lo usas todos los días sin darte cuenta.

Lo interpreta: git

.gitignore

Qué ficheros no se suben (lo escribiste en la Sesión 1).

Lo interpreta: npm / Node

package.json

Dependencias y órdenes como npm run dev.

Lo interpreta: Docker

docker-compose.yml

Qué servicios arrancan, en qué puertos, con qué variables.

Lo interpreta: VS Code

settings.json de VS Code

Tema, tamaño de letra, formateo al guardar…

Lo interpreta: uv / pip

pyproject.toml

Nombre del paquete, versión y el comando tareas.

Lo interpreta: OpenCode

opencode.json · AGENTS.md · .opencode/

Qué puede hacer tu agente, qué normas sigue y qué sabe de tu proyecto.

Lo interpreta: TU motor

acciones.json

Qué hace tu herramienta con tus ficheros.

La misma idea, dos veces

Igual que tu CLI lee acciones.json, OpenCode lee opencode.json, AGENTS.md y la carpeta .opencode/. Nadie recompila OpenCode para adaptarlo a tu proyecto: tú configuras a tu agente igual que tu usuario configura tu herramienta.

Esta semana harás las dos cosas: el acciones.json de tu CLI y tres ficheros nuevos en .opencode/.

El reparto de papeles

Así queda tu CLI: el JSON dice qué; config.py comprueba que el JSON tiene sentido antes de tocar un solo fichero; el Motor elige los ficheros que cumplen el filtro; cada Accion sabe hacer una cosa; y la CLI pinta el resultado.

solo llega un JSON válidoEl JSONlo escribes túconfig.pycarga y validaEl motorelige ficherosLa acciónuna por ficheroTabla Richqué → dóndeError de configsale con un 3Tu discomueve, renombra…si algo fallasolo sin --simular

Desliza el diagrama de lado para verlo entero

Solo un JSON válido llega al motor. Con --simular sale la misma tabla, pero nada toca el disco.

El método de cada paso

El mismo de la Sesión 1. ¿Dudas con OpenCode (atajos, permisos, sesiones)? Tienes la guía de OpenCode del curso.

Tú decidesPlan piensaBuild haceIntenciónPide planHazloAuditaCommit/newsiguiente tarea

Desliza el diagrama de lado para verlo entero

Tú decides al principio y al final; plan piensa y build hace en medio. Y vuelta a empezar con la siguiente tarea.

Los seis pasos, uno a uno

1 · Tú escribes la intención

El esquema, la acción, el criterio de aceptación.

2 · Agente plan

shift+tab: «explícame cómo lo harías y qué ficheros tocarías». Lees el plan y lo corriges.

3 · Agente build

shift+tab: «hazlo». Apruebas cada edición y cada orden leyendo el diff.

4 · Auditas

Lees el código, pruebas en ~/pruebas-tareas con --simular y con casos feos. Si algo sale mal, /undo o le explicas el fallo.

5 · Commit pequeño hecho por ti

Y el prompt clave a docs/prompts.md (o /export de la sesión).

6 · Sesión nueva por tarea

/new; /compact si la conversación se alarga.

Paso 1 · Diseña tu esquema: lo haces TÚ, sin IA

Esta parte es la que te pertenece: el esquema es la especificación de tu herramienta. Si se lo pides a la IA, tendrás la herramienta de otra persona. OpenCode, cerrado. Crea acciones.json en la raíz del repo partiendo de este ejemplo:

acciones.json
{  "version": 1,  "acciones": [    {      "nombre": "ordenar-descargas",      "descripcion": "Mueve los PDF y documentos de Descargas a Documentos/PDF",      "tipo": "mover",      "origen": "~/Descargas",      "filtro": { "extensiones": [".pdf", ".docx"] },      "destino": "~/Documentos/PDF"    },

La acción ordenar-descargas

Tipo mover: de origen a destino, solo los PDF y los Word. Sin CARPETA en la orden, usa su origen.

Antes de ordenar

~/
Descargas/
FOTO1.JPG
apuntes de redes.docx
cumpleaños 2.png
factura.pdf
viejo.tmp
Documentos/PDF/vacía
tareas ejecutar ordenar-descargas

Después de ordenar

~/
Descargas/
FOTO1.JPG
cumpleaños 2.png
viejo.tmp
Documentos/PDF/
apuntes de redes.docx
factura.pdf

La acción renombrar-fotos

FOTO1.JPG pasa a ser la 001 y cumpleaños 2.png, la 002; los demás no cumplen el filtro.

acciones.json
    {      "nombre": "renombrar-fotos",      "descripcion": "Renombra fotos con su fecha: 2026-10-26_001.jpg",      "tipo": "renombrar",      "filtro": { "extensiones": [".jpg", ".jpeg", ".png"] },      "plantilla": "{fecha:%Y-%m-%d}_{n:03}{ext}"    },

Antes de renombrar

Descargas/
FOTO1.JPG
apuntes de redes.docx
cumpleaños 2.png
factura.pdf
viejo.tmp
tareas ejecutar renombrar-fotos ~/pruebas-tareas/Descargas

Después de renombrar

Descargas/
2026-11-03_001.jpg
2026-11-03_002.png
apuntes de redes.docx
factura.pdf
viejo.tmp

La acción limpiar-temporales

acciones.json
    {      "nombre": "limpiar-temporales",      "descripcion": "Borra .tmp con más de 30 días",      "tipo": "borrar",      "filtro": { "patron": ".*\\.tmp$", "mas_antiguo_que_dias": 30 },      "confirmar": true    }

Antes de limpiar

Descargas/
FOTO1.JPG
apuntes de redes.docx
cumpleaños 2.png
factura.pdf
viejo.tmp40 días
tareas ejecutar limpiar-temporales ~/pruebas-tareas/Descargaspregunta antes de borrar

Después de limpiar

Descargas/
FOTO1.JPG
apuntes de redes.docx
cumpleaños 2.png
factura.pdf

Campo a campo

"nombre": "ordenar-descargas","descripcion": "Mueve los PDF…","tipo": "mover","origen": "~/Descargas","filtro": { "extensiones": [".pdf", ".docx"] },"destino": "~/Documentos/PDF"lo que escribes en tareas ejecutarlo que enseña tareas accionesqué clase Python la ejecutacarpeta si no le pasas otraqué ficheros se tocana dónde van (se crea si no existe)

Desliza el diagrama de lado para verlo entero

En azul, los campos obligatorios; en gris, los opcionales o los que pide cada tipo de acción.

Campos de la raíz y obligatorios

"version"

obligatorio: sí (raíz)entero

Ej.: 1

Versión del esquema. Si mañana cambias el formato, subes a 2 y el programa sabe qué está leyendo.

"acciones"

obligatorio: sí (raíz)lista

Ej.: [ … ]

La lista de acciones. Vacía = error de configuración.

"nombre"

obligatorio: sítexto sin espacios

Ej.: ordenar-descargas

Lo que escribes en tareas ejecutar NOMBRE. Único: no puede haber dos iguales.

"descripcion"

obligatorio: sítexto

Ej.: Mueve los PDF…

Lo que enseña tareas acciones. Escríbela para alguien que no eres tú.

"tipo"

obligatorio: síuno de la lista

Ej.: mover

Qué clase de acción es. El motor elige la clase Python a partir de este campo.

Campos según el tipo de acción

"origen"

obligatorio: noruta

Ej.: ~/Descargas

Carpeta por defecto si no pasas CARPETA en la orden. ~ se expande a tu carpeta personal en Linux, macOS y Windows.

"filtro"

obligatorio: noobjeto

Ej.: { "extensiones": [".pdf"] }

Qué ficheros de la carpeta se tocan. Sin filtro = todos (¡cuidado con borrar!).

"destino"

obligatorio: mover / copiarruta

Ej.: ~/Documentos/PDF

A dónde van. Si no existe, se crea.

"plantilla"

obligatorio: renombrartexto con {huecos}

Ej.: {fecha:%Y-%m-%d}_{n:03}{ext}

El nombre nuevo de cada fichero.

"confirmar"

obligatorio: no (borrar: sí)true / false

Ej.: true

Pide confirmación antes de actuar salvo que pases --si.

Tipos de acción

mover

Qué le pasa al fichero: origen → destino

Para qué en tu vida real: Ordenar Descargas, sacar las capturas del escritorio.

copiar

Qué le pasa al fichero: origen → destino (el original se queda)

Para qué en tu vida real: Copia de seguridad de tus apuntes a un USB o a una carpeta sincronizada.

renombrar

Qué le pasa al fichero: mismo sitio, nombre nuevo

Para qué en tu vida real: Fotos con fecha, apuntes numerados (tema-01, tema-02…).

borrar

Qué le pasa al fichero: desaparece (con confirmación)

Para qué en tu vida real: Temporales, instaladores .exe/.deb viejos, ficheros vacíos.

… con IA (semana 3)

Qué le pasa al fichero: lo decide un modelo del centro

Para qué en tu vida real: Clasificar por contenido, poner nombre a partir del texto de un PDF, resumir.

Filtros: qué ficheros se tocan

Dentro de filtro. Si pones varios, el fichero tiene que cumplirlos todos.

Filtro de ordenar-descargasfactura.pdfapuntes de redes.docxFOTO1.JPGcumpleaños 2.pngviejo.tmpextensiones[.pdf, .docx]en minúsculasElegidos · 2 de 5pasan a la acciónSe quedan · 3 de 5

Desliza el diagrama de lado para verlo entero

Los cuatro filtros

"extensiones"

Ej.: [".pdf", ".docx"]

Solo esas extensiones. Compáralas en minúsculas: FOTO1.JPG también es .jpg.

"patron"

Ej.: "^captura.*\\.png$"

Expresión regular sobre el nombre. En JSON la barra invertida se escribe doble.

"mas_antiguo_que_dias"

Ej.: 30

Solo ficheros cuya fecha de modificación tiene más de N días.

"mayor_que_mb"

Ej.: 100

Solo ficheros de más de N MB (vídeos olvidados, ISOs…).

Plantillas de nombre

Para renombrar. Son huecos entre llaves que el motor rellena con el formato de Python (str.format): lo de detrás de los dos puntos es el formato.

{fecha:%Y-%m-%d}→ 2026-11-03
_tal cual
{n:03}→ 001
{ext}→ .jpg

{fecha:%Y-%m-%d}

da 2026-11-03

Fecha de modificación del fichero con el formato que quieras (%d/%m no: la barra no vale en nombres).

{n:03}

da 001, 002…

Contador con ceros a la izquierda. {n} sin formato da 1, 2, 3.

{ext}

da .jpg

La extensión original, con punto, en minúsculas.

{nombre}

da IMG_2041

El nombre original sin extensión, por si quieres conservarlo: {fecha:%Y%m%d}-{nombre}{ext}.

Reto: 3 acciones para TU vida real

Al final tendrás 3 acciones que te ahorran tiempo a ti (las del ejemplo no cuentan). La primera la escribes ahora, a mano; la 2.ª y la 3.ª las añadirás en el paso 5 con tu comando /nueva-accion. Ideas, de menos a más difícil:

  1. FácilMover las capturas de pantalla del escritorio a ~/Imágenes/Capturas (filtro por extensión).
  2. MediaCopiar los apuntes de DAM modificados hace menos de 7 días a una carpeta de copia, o borrar instaladores .exe/.deb de más de 60 días.
  3. DifícilRenombrar las fotos del móvil a {fecha:%Y-%m-%d}_{n:03}{ext} usando un patron regex que solo coja las que empiezan por IMG_ o PXL_.

Después, añade al README una sección «Esquema de acciones.json» con la tabla de campos (la tuya, no la de esta página si has cambiado algo). Si el esquema no está escrito, el agente se lo inventa: en el paso siguiente se lo enseñas.

Paso 2 · Tu primera skill: enseña el esquema

Si en cada prompt tuvieras que pegar tu esquema entero, acabarías harto y, peor, una vez se te olvidaría. Para eso existen las skills: un fichero Markdown con conocimiento concreto (cómo es tu acciones.json y qué reglas sigue el código que lo lee) que el agente carga cuando lo necesita.

El agente veid y description¿Encaja?con lo que pidesCarga la skilllee SKILL.md enteroTrabajacon tu esquemaNo la cargaahorra contexto@acciones-jsonsínotú la fuerzas

Desliza el diagrama de lado para verlo entero

Cuatro formas de personalizar OpenCode

Antes de crearla, el mapa de lo que puedes poner en tu repo para personalizar a OpenCode:

AGENTS.md

raíz del repo

Quién la activa: Siempre: entra en todas las conversaciones.

Para qué: Normas generales del proyecto (stack, órdenes, «no hagas push»).

Skill

.opencode/skills/NOMBRE/SKILL.md

Quién la activa: El agente, bajo demanda, cuando la description encaja con la tarea (o tú, con @NOMBRE).

Para qué: Conocimiento concreto que no hace falta siempre: tu esquema de acciones.json.

Comando

.opencode/commands/NOMBRE.md

Quién la activa: Tú, escribiendo /NOMBRE argumentos.

Para qué: Un prompt que repites a menudo, con sus pasos fijos.

Subagente

.opencode/agents/NOMBRE.md

Quién la activa: Tú, pidiéndoselo con palabras (o el agente principal, si lo necesita).

Para qué: Otro agente con su propio papel y sus propios permisos: un revisor que no puede editar.

Dónde vive cada pieza

Crea la carpeta .opencode/skills/acciones-json/ y dentro el fichero SKILL.md (en mayúsculas). Adáptalo a tu esquema si has cambiado campos.

cli-tareas/
opencode.jsonpermisos del proyecto (Sesión 1)
AGENTS.mdnormas que el agente lee SIEMPRE (Sesión 1)
acciones.json
.opencode/
skills/
acciones-json/
SKILL.mdpaso 2: lo que el agente sabe de tu esquema
commands/
nueva-accion.mdpaso 5: tu orden /nueva-accion
agents/
revisor.mdpaso 6: tu subagente revisor
src/tareas/ …

La skill acciones-json

.opencode/skills/acciones-json/SKILL.md
---name: acciones-jsondescription: Reglas del fichero acciones.json de la CLI tareas (campos, tipos, filtros, plantillas y validación). Úsala siempre que crees o cambies acciones o el código que las lee (config.py, acciones.py, motor.py).---# Esquema de acciones.json- Raíz: {"version": 1, "acciones": [...]}. Cada acción: nombre (único, minúsculas-con-guiones), descripcion, tipo.- Tipos: mover y copiar (requieren destino), renombrar (requiere plantilla), borrar (siempre pide confirmación salvo --si).- filtro opcional: extensiones (lista, en minúsculas), patron (regex válida), mas_antiguo_que_dias, mayor_que_mb.- plantilla: huecos {fecha:%Y-%m-%d}, {n:03}, {ext}, {nombre}.## Reglas al programar- Valida el JSON en config.py ANTES de ejecutar; errores con AccionNoValida(accion, campo, motivo).- pathlib y shutil; encoding="utf-8"; nunca shell=True; nunca sobrescribir (destino_libre).- Toda acción admite --simular y devuelve list[Resultado].- Si añades un campo o un tipo nuevo, documéntalo en el README y en esta skill.

Cómo está hecha una skill

Frontmatter de la skill

Lo de arriba entre ---. El id de la skill es el nombre de la carpeta (acciones-json), en minúsculas y con guiones; name es solo una etiqueta.

description, lo más importante

El agente solo ve el id y la descripción de cada skill, y con eso decide si la carga. Por eso dice qué es y, sobre todo, cuándo usarla. Sin descripción, la skill no le llega al modelo.

Se carga cuando encaja

El agente llama a su herramienta skill y entonces sí lee el fichero entero: no gasta contexto con tu esquema cuando le pides otra cosa. Para forzarla, escribe @acciones-json.

Si el esquema cambia, la skill cambia

La última regla es para el agente y para ti. Una skill desactualizada enseña mal.

Más detalle en la guía: Skills: conocimiento bajo demanda.

¿AGENTS.md o skill?

AGENTS.md

Siempre

  • Entra en cada conversación.
  • Normas generales: stack, pathlib, «no hagas push».

Skill

Solo cuando hace falta

  • El conocimiento detallado de una parte del proyecto.
  • Aquí: tu esquema de acciones.json.

Con los modelos del centro el contexto cuesta, así que AGENTS.md corto y el detalle en skills.

Compruébalo con /skills

  1. Sal de OpenCode y vuelve a abrirlo en la carpeta del repo (o opencode reload): con la config ya cargada puede seguir sin ver la skill.
  2. Escribe /skills: tiene que aparecer acciones-json.
  3. Y a git, que la skill es parte de tu proyecto:
Terminal
git add .opencode/skills/acciones-json/SKILL.mdgit commit -m "Skill acciones-json: el agente carga las reglas de mi esquema"

Paso 3 · Valida antes de ejecutar, con el agente

Un programa que borra ficheros no puede fiarse de un JSON escrito a mano. Primero se comprueba todo el fichero y solo si está bien se toca el disco. Y cuando algo falla, el mensaje tiene que decir qué acción y qué campo:

No sirve

Mensaje genérico

  • Error en la configuración
  • No dice qué acción ni qué campo: a buscar a ciegas.

Te lo arregla en 10 segundos

Mensaje que dice dónde

  • Acción «renombrar-fotos», campo «plantilla»: es obligatorio en acciones de tipo renombrar

Validar: primero, el plan

Abre una sesión nueva (/new) y pasa al agente plan con shift+tab. Fíjate en lo corto que es el prompt: @acciones.json adjunta tu fichero y la skill pone el resto.

Prompt · agente plan
Carga la skill acciones-json y lee @acciones.json.Quiero validar acciones.json ANTES de ejecutar nada:- src/tareas/errores.py con TareasError, ConfigError y AccionNoValida;- src/tareas/config.py con cargar(ruta) -> list[dict];- la orden «tareas validar» en src/tareas/cli.py.No toques nada todavía: dime qué ficheros crearías o cambiarías, qué clasesy funciones tendrán y qué casos de error vas a detectar.

Lee el plan. ¿Ha entendido tu esquema? ¿Se olvida de algún caso (nombre repetido, regex rota)? Corrígelo ahí mismo.

Validar: después, build

Cuando el plan te convenza, shift+tab para pasar a build:

Prompt · agente build
Hazlo según el plan. Criterio de aceptación:- TareasError (codigo_salida = 1), ConfigError (codigo_salida = 3) y  AccionNoValida(accion, campo, motivo) → «Acción «X», campo «Y»: motivo».- JSON roto → ConfigError con línea y columna.- Cada mensaje dice QUÉ acción y QUÉ campo fallan, en español.- «tareas validar»: «✔ N acciones válidas» en verde, o el error en rojo  SIN traceback y saliendo con e.codigo_salida.Solo esos tres ficheros, sin dependencias nuevas.Termina ejecutando: uv run tareas validar
  • edit · *

    Con tu opencode.json de la Sesión 1, cada edición te pide permiso: lee el diff antes de aceptar.

  • shell · uv run tareas validar *

    Esta sí la puede ejecutar solo: está en tu lista de órdenes permitidas.

Las excepciones heredan

Para auditar, esto es lo que deberías obtener. Las excepciones heredan unas de otras:

TareasErrorbase · sale con 1ConfigErrorJSON roto · sale con 3AccionNoValidaacción, campo y motivocli.pyexcept TareasError as e:una sola captura para todotyper.Exitcon e.codigo_salidaes un TareasErrores un ConfigErrorcaptura

Desliza el diagrama de lado para verlo entero

La CLI captura TareasError una sola vez: cualquier error de la familia trae su propio código de salida.

errores.py de referencia

src/tareas/errores.py
# src/tareas/errores.pyclass TareasError(Exception):    """Base de todos los errores previsibles de la herramienta."""    codigo_salida = 1​​class ConfigError(TareasError):    """acciones.json no existe, no es JSON o no cumple el esquema."""    codigo_salida = 3​​class AccionNoValida(ConfigError):    """Una acción concreta tiene un campo mal: dice cuál y por qué."""​    def __init__(self, accion: str, campo: str, motivo: str):        super().__init__(f"Acción «{accion}», campo «{campo}»: {motivo}")        self.accion = accion        self.campo = campo

config.py: cargar el fichero

Y así es, resumido, config.py. No lo copies: es la referencia para comparar con lo que te haya hecho el agente.

src/tareas/config.py (resumido)
TIPOS = {"mover", "copiar", "renombrar", "borrar"}OBLIGATORIOS = ["nombre", "descripcion", "tipo"]POR_TIPO = {"mover": "destino", "copiar": "destino", "renombrar": "plantilla"}​​def cargar(ruta: Path) -> list[dict]:    ruta = ruta.expanduser()    if not ruta.is_file():        raise ConfigError(f"No encuentro {ruta}. Crea acciones.json o usa --config RUTA")    try:        datos = json.loads(ruta.read_text(encoding="utf-8"))    except json.JSONDecodeError as e:        raise ConfigError(f"{ruta.name} no es JSON válido: línea {e.lineno}, columna {e.colno} ({e.msg})")​    acciones = datos.get("acciones") if isinstance(datos, dict) else None    if not isinstance(acciones, list) or not acciones:        raise ConfigError("Falta la lista «acciones» o está vacía")

config.py: acción a acción

src/tareas/config.py (resumido)
    vistos = set()    for i, a in enumerate(acciones, start=1):        nombre = a.get("nombre", f"nº {i}")        for campo in OBLIGATORIOS:            if not a.get(campo):                raise AccionNoValida(nombre, campo, "es obligatorio")        if nombre in vistos:            raise AccionNoValida(nombre, "nombre", "está repetido")        vistos.add(nombre)        if a["tipo"] not in TIPOS:            raise AccionNoValida(nombre, "tipo", f"«{a['tipo']}» no existe; usa uno de: {', '.join(sorted(TIPOS))}")        extra = POR_TIPO.get(a["tipo"])        if extra and not a.get(extra):            raise AccionNoValida(nombre, extra, f"es obligatorio en acciones de tipo {a['tipo']}")

config.py: ¿la regex compila?

src/tareas/config.py (resumido)
        patron = a.get("filtro", {}).get("patron")        if patron is not None:            try:                re.compile(patron)            except re.error as e:                raise AccionNoValida(nombre, "filtro.patron", f"expresión regular rota: {e}")    return acciones

Pruébalo y mira el código de salida

En tu terminal, o desde OpenCode con ! delante:

Terminal
uv run tareas validarecho $?        # Linux/macOS: 0 si es válido, 3 si no$LASTEXITCODE   # lo mismo en PowerShell

Casos feos que pruebas TÚ

Haz una copia (pruebas/roto.json), estropéala a propósito de cada una de estas formas y ejecuta uv run tareas --config pruebas/roto.json validar. Ninguno puede acabar en traceback. Si alguno falla, explícaselo al agente con el mensaje que has visto, no con «no va».

Coma de más

Una coma tras la última acción: … } , ]

Debe decir: No es JSON válido: línea X, columna Y

Tipo inexistente

"tipo": "mober"

Debe decir: Acción «…», campo «tipo»: «mober» no existe; usa uno de: borrar, copiar, mover, renombrar

Nombre repetido

Dos acciones con "nombre": "ordenar-descargas"

Debe decir: Acción «ordenar-descargas», campo «nombre»: está repetido

Regex rota

"patron": "*.tmp" (el * no puede ir el primero)

Debe decir: Acción «…», campo «filtro.patron»: expresión regular rota

Extra: fichero que no existe

--config nada.json

Debe decir: No encuentro nada.json…

Paso 4 · El motor y las acciones en clases

Aquí aparecen las clases de verdad. Una clase base Accion define lo que toda acción sabe hacer (ejecutar) y cada subclase (Mover, Copiar, Renombrar, Borrar) solo implementa lo suyo en aplicar. El método estático Accion.desde_config(dict) es una fábrica: gracias a ella, el motor no tiene ni un if tipo == …, y añadir un tipo nuevo es escribir una subclase más.

{"tipo": "mover"}del JSONAccion.desde_configla fábrica_registromover → Movercopiar → Copiarrenombrar → Renombrarborrar → BorrarMover(config)el objetoNi un if por tipo: cada subclase se apunta sola al registro

Desliza el diagrama de lado para verlo entero

El motor elige, la acción aplica

El Motor recibe la carpeta de la orden (o el origen de la acción), selecciona los ficheros que cumplen el filtro y se los pasa a la acción, que devuelve un informe: una lista de Resultado (qué fichero, a qué destino, en qué estado). El estado es uno de estos tres:

hecho

La acción ha tocado el disco de verdad.

simulado

Con --simular: dice qué haría, sin tocar nada.

saltado

No había nada que hacer: al renombrar, el nombre nuevo es el que ya tenía.

Motor: plan y luego build

Sesión nueva (/new). Primero en plan; cuando el plan te cuadre, en build:

Prompt · agente plan
Carga la skill acciones-json y explícame cómo harías acciones.py y motor.py: clases, métodos y cómo garantizas que --simular no toca el disco
Prompt · agente build
Carga la skill acciones-json. Crea src/tareas/acciones.py y src/tareas/motor.py:1. acciones.py: dataclass Resultado(origen, destino, estado: hecho | simulado | saltado);   clase base abstracta Accion con ejecutar(ficheros, simular) y aplicar(fichero, n, simular)   abstracto; fábrica Accion.desde_config(dict) con un registro de subclases (nada de   if/elif por tipo); subclases Mover, Copiar, Renombrar y Borrar (destructiva = True).2. motor.py: clase Motor(acciones) con seleccionar(carpeta, filtro) y   ejecutar(nombre, carpeta, simular) -> list[Resultado]. Sin carpeta, usa "origen".   Acción o carpeta inexistente → TareasError con mensaje humano.Con simular=True no se toca NADA del disco (ni mkdir). Nunca sobrescribir: sufijo « (1)».No toques cli.py y NO ejecutes ninguna acción: las pruebo yo.Al terminar, dime qué pasa si ejecuto dos veces seguidas la misma acción de mover y por qué.

Reglas que auditas tú

Están en tu AGENTS.md y en la skill, pero que el agente las conozca no significa que las cumpla:

  • pathlib.Path siempre: ninguna ruta montada con + "/" + ni con \.
  • Path.expanduser() para ~; encoding="utf-8" en todo open() o read_text().
  • shutil.move y shutil.copy2; nada de os.system, subprocess ni shell=True.
  • Nombres con tildes y espacios funcionan.
  • Con simular=True no se llama a mkdir, move, rename ni unlink.
  • Nunca se sobrescribe: si el destino existe, sufijo « (1)», « (2)»…

Cada «esto no lo cumple» es un error que le pides corregir y un buen párrafo para docs/prompts.md.

acciones.py: Resultado y destino_libre

Código de referencia resumido para auditar:

src/tareas/acciones.py (resumido)
@dataclassclass Resultado:    origen: Path    destino: Path | None    estado: str  # "hecho", "simulado" o "saltado"​​def destino_libre(destino: Path) -> Path:    """Nunca sobrescribe: si existe, prueba 'nombre (1).ext', 'nombre (2).ext'..."""    libre, n = destino, 1    while libre.exists():        libre = destino.with_name(f"{destino.stem} ({n}){destino.suffix}")        n += 1    return libre

acciones.py: la clase base Accion

src/tareas/acciones.py (resumido)
class Accion(ABC):    tipo = ""    destructiva = False    _registro: dict[str, type[Accion]] = {}​    def __init__(self, config: dict):        self.nombre = config["nombre"]        self.descripcion = config["descripcion"]        self.config = config​    def __init_subclass__(cls, **kwargs):        super().__init_subclass__(**kwargs)        Accion._registro[cls.tipo] = cls  # cada subclase se apunta sola​    @staticmethod    def desde_config(config: dict) -> Accion:        """Fábrica: del diccionario del JSON a la clase que toca."""        clase = Accion._registro.get(config["tipo"])        if clase is None:            raise AccionNoValida(config["nombre"], "tipo", "no hay ninguna clase para ese tipo")        return clase(config)

acciones.py: ejecutar, aplicar y Mover

src/tareas/acciones.py (resumido)
    def ejecutar(self, ficheros: list[Path], simular: bool) -> list[Resultado]:        return [self.aplicar(f, n, simular) for n, f in enumerate(ficheros, start=1)]​    @abstractmethod    def aplicar(self, fichero: Path, n: int, simular: bool) -> Resultado: ...​​class Mover(Accion):    tipo = "mover"​    def aplicar(self, fichero, n, simular):        carpeta = Path(self.config["destino"]).expanduser()        destino = destino_libre(carpeta / fichero.name)        if not simular:            carpeta.mkdir(parents=True, exist_ok=True)            shutil.move(fichero, destino)        return Resultado(fichero, destino, "simulado" if simular else "hecho")

acciones.py: Renombrar

src/tareas/acciones.py (resumido)
class Renombrar(Accion):    tipo = "renombrar"​    def aplicar(self, fichero, n, simular):        fecha = datetime.fromtimestamp(fichero.stat().st_mtime)        nuevo = self.config["plantilla"].format(            fecha=fecha, n=n, ext=fichero.suffix.lower(), nombre=fichero.stem        )        if nuevo == fichero.name:            return Resultado(fichero, None, "saltado")        destino = destino_libre(fichero.with_name(nuevo))        if not simular:            fichero.rename(destino)        return Resultado(fichero, destino, "simulado" if simular else "hecho")

acciones.py: Borrar, y Copiar

src/tareas/acciones.py (resumido)
class Borrar(Accion):    tipo = "borrar"    destructiva = True​    def aplicar(self, fichero, n, simular):        if not simular:            fichero.unlink()        return Resultado(fichero, None, "simulado" if simular else "hecho")​# Copiar es igual que Mover pero con shutil.copy2 (conserva la fecha).

motor.py: la clase Motor

src/tareas/motor.py (resumido)
class Motor:    def __init__(self, acciones: list[dict]):        self.acciones = {a["nombre"]: Accion.desde_config(a) for a in acciones}​    @staticmethod    def seleccionar(carpeta: Path, filtro: dict) -> list[Path]:        exts = {e.lower() for e in filtro.get("extensiones", [])}        patron = re.compile(filtro["patron"]) if "patron" in filtro else None        dias = filtro.get("mas_antiguo_que_dias")        mb = filtro.get("mayor_que_mb")        ahora = time.time()        elegidos = []

motor.py: el filtro, fichero a fichero

src/tareas/motor.py (resumido)
        for f in sorted(carpeta.iterdir()):            if not f.is_file():                continue            if exts and f.suffix.lower() not in exts:                continue            if patron and not patron.search(f.name):                continue            if dias and ahora - f.stat().st_mtime < dias * 86400:                continue            if mb and f.stat().st_size < mb * 1024 * 1024:                continue            elegidos.append(f)        return elegidos

motor.py: ejecutar una acción

src/tareas/motor.py (resumido)
    def ejecutar(self, nombre: str, carpeta: Path | None, simular: bool) -> list[Resultado]:        accion = self.acciones.get(nombre)        if accion is None:            raise TareasError(f"No hay ninguna acción «{nombre}». Mira la lista con: tareas acciones")        carpeta = (carpeta or Path(accion.config.get("origen", "."))).expanduser()        if not carpeta.is_dir():            raise TareasError(f"La carpeta {carpeta} no existe")        ficheros = self.seleccionar(carpeta, accion.config.get("filtro", {}))        return accion.ejecutar(ficheros, simular)

La interfaz: acciones, ejecutar y opciones

La CLI es la capa fina que une todo. La orden que hace el trabajo:

tareasprograma
ejecutarorden
ordenar-descargasNOMBRE de la acción
~/pruebas-tareas/Descargas[CARPETA], opcional
--simularopción

tareas acciones

Tabla con nombre, tipo y descripción de lo que hay en acciones.json.

--simular · --si

Enseña qué haría sin tocar nada · no pedir confirmación.

--config RUTA

Opción global: va antes de la orden (tareas --config otra.json acciones). Por defecto, ./acciones.json.

Códigos de salida

Sale con 0

Todo bien.

Sale con 1

Fallo al ejecutar (carpeta que no existe, acción desconocida, permiso denegado…).

Sale con 2

Error de uso: falta un argumento o una opción no existe (lo pone Typer solo).

Sale con 3

Configuración inválida: acciones.json roto o con campos mal.

Interfaz: plan y luego build

Sesión nueva, plan y luego build con:

Prompt · agente build
Amplía SOLO @src/tareas/cli.py (Typer + Rich). Ya existen config.cargar, Motor y las Accion.1. Opción global --config RUTA en @app.callback (por defecto ./acciones.json), guardada en ctx.obj.2. «tareas acciones»: tabla Rich con nombre, tipo y descripción.3. «tareas ejecutar NOMBRE [CARPETA] --simular --si»:   - --simular: tabla «fichero → destino» con estado «simulado», sin tocar nada;   - acción destructiva sin --simular ni --si → typer.confirm(..., abort=True);   - resumen final: N hechos, N simulados, N saltados; si ningún fichero cumple el filtro, dilo.4. Códigos de salida: 0 bien · 1 TareasError · 2 uso (Typer) · 3 ConfigError.   Nunca un traceback ante errores previsibles: mensaje en rojo y typer.Exit(e.codigo_salida).No toques acciones.py ni motor.py. Termina con: uv run tareas --help

cli.py: --config para todas las órdenes

src/tareas/cli.py (fragmento)
# src/tareas/cli.py (fragmento)@app.callback()def principal(    ctx: typer.Context,    config: Path = typer.Option(Path("acciones.json"), "--config", help="Ruta de acciones.json"),):    ctx.obj = config

cli.py: una sola captura para todo

El fragmento clave de cli.py: fíjate en cómo se captura una sola excepción base para todo.

src/tareas/cli.py (fragmento)
@app.command()def ejecutar(    ctx: typer.Context,    nombre: str = typer.Argument(..., help="Nombre de la acción (ver: tareas acciones)"),    carpeta: Path | None = typer.Argument(None, help="Carpeta sobre la que actuar"),    simular: bool = typer.Option(False, "--simular", help="Enseña qué haría sin tocar nada"),    si: bool = typer.Option(False, "--si", help="No pedir confirmación"),):    try:        motor = Motor(config.cargar(ctx.obj))        accion = motor.acciones.get(nombre)        if accion and accion.destructiva and not simular and not si:            typer.confirm(f"«{nombre}» borra ficheros. ¿Seguro?", abort=True)        resultados = motor.ejecutar(nombre, carpeta, simular)    except TareasError as e:        consola.print(f"[red]✘ {e}[/red]")        raise typer.Exit(e.codigo_salida)    pintar_tabla(resultados, simular)  # Rich: fichero → destino → estado

Lo que deberías ver

Fíjate en el sufijo « (1)»: ya había una factura.pdf en el destino.

tareas ejecutar --simular
uv run tareas ejecutar ordenar-descargas ~/pruebas-tareas/Descargas --simular
ordenar-descargas (SIMULACIÓN: no se ha tocado nada)┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓┃ Fichero ┃ Destino ┃ Estado ┃┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩│ apuntes de redes.docx │ ~/Documentos/PDF/apuntes de redes.docx │ simulado ││ factura.pdf │ ~/Documentos/PDF/factura (1).pdf │ simulado │└───────────────────────┴─────────────────────────────────────────┴──────────┘2 ficheros · 0 hechos · 2 simulados · 0 saltadosPara hacerlo de verdad, repite la orden sin --simular.

Las acciones las ejecutas TÚ, no el agente

  • shell · *

    En tu opencode.json, uv run tareas ejecutar … no está entre las permitidas: si el agente quiere lanzarla, OpenCode te pregunta.

Recházalo: podría mover tus ficheros reales. Las pruebas las haces tú, en tu terminal o con !uv run tareas … dentro de OpenCode.

Regla de oro: --simular primero

Prueba siempre primero en ~/pruebas-tareas y con --simular. Nunca sobre tu carpeta de Descargas de verdad hasta que la simulación diga exactamente lo que esperas.

Mientras desarrollas, usa uv run tareas … desde la carpeta del repo (ejecuta tu código actual sin reinstalar).

Ojo con el destino

La carpeta de pruebas protege el origen, pero destino sigue apuntando a tus carpetas reales (~/Documentos/PDF).

Mientras pruebas, cambia también el destino a algo como ~/pruebas-tareas/Documentos/PDF en tu acciones.json (o usa un --config de pruebas) y vuelve a tus rutas reales solo cuando todo funcione.

Pruebas en Linux y macOS (bash/zsh)

Terminal · bash / zsh
# 1) Una carpeta de pruebas con ficheros feos (tildes, espacios, mayúsculas)mkdir -p ~/pruebas-tareas/Descargascd ~/pruebas-tareas/Descargastouch factura.pdf "apuntes de redes.docx" FOTO1.JPG "cumpleaños 2.png" viejo.tmptouch -d "40 days ago" viejo.tmp   # macOS: touch -t "$(date -v-40d +%Y%m%d%H%M)" viejo.tmp​# 2) Desde la carpeta del repocd ~/cli-tareasuv run tareas validaruv run tareas accionesuv run tareas ejecutar ordenar-descargas ~/pruebas-tareas/Descargas --simularuv run tareas ejecutar limpiar-temporales ~/pruebas-tareas/Descargas --simular​# 3) Solo cuando la simulación dice lo que esperasuv run tareas ejecutar ordenar-descargas ~/pruebas-tareas/Descargasecho $?   # 0 si todo ha ido bien​# 4) Otro acciones.json (por ejemplo, uno roto a propósito)uv run tareas --config pruebas/roto.json validarecho $?   # debe ser 3

Pruebas en Windows (PowerShell)

Terminal · PowerShell
# 1) Una carpeta de pruebas con ficheros feos (tildes, espacios, mayúsculas)New-Item -ItemType Directory -Force "$HOME\pruebas-tareas\Descargas"Set-Location "$HOME\pruebas-tareas\Descargas"New-Item -ItemType File factura.pdf, "apuntes de redes.docx", FOTO1.JPG, "cumpleaños 2.png", viejo.tmp(Get-Item viejo.tmp).LastWriteTime = (Get-Date).AddDays(-40)​# 2) Desde la carpeta del repoSet-Location "$HOME\cli-tareas"uv run tareas validaruv run tareas accionesuv run tareas ejecutar ordenar-descargas "$HOME\pruebas-tareas\Descargas" --simular​# 3) Solo cuando la simulación dice lo que esperasuv run tareas ejecutar ordenar-descargas "$HOME\pruebas-tareas\Descargas"$LASTEXITCODE   # 0 si todo ha ido bien​# 4) Otro acciones.json (por ejemplo, uno roto a propósito)uv run tareas --config pruebas\roto.json validar$LASTEXITCODE   # debe ser 3

Paso 5 · Tu comando /nueva-accion

Añadir una acción siempre sigue los mismos pasos: proponer el JSON, revisarlo, validar y probar con --simular. Cuando repites un prompt, lo conviertes en un comando personalizado: un fichero Markdown en .opencode/commands/ que se invoca con / y su nombre.

Tú lo lanzas/nueva-accion y tu ideaEl comando rellena$ARGUMENTS y git statusbuild proponela entrada JSON, y esperaTu visto bueno¿filtro, plantilla, destino?Edita y validauv run tareas validarTú lo pruebasen pruebas, con --simular

Desliza el diagrama de lado para verlo entero

El paso de tu visto bueno es el que mantiene la decisión en tus manos.

nueva-accion.md

Crea .opencode/commands/nueva-accion.md:

.opencode/commands/nueva-accion.md
---description: Añade una acción nueva a acciones.json y, si hace falta, el código que la soportaagent: build---Quiero añadir la acción: $ARGUMENTS1. Carga la skill acciones-json.2. Propón primero la entrada JSON y espera mi visto bueno.3. Si el tipo ya existe, solo edita acciones.json. Si no, añade la clase en src/tareas/acciones.py siguiendo el patrón de las demás.4. Termina ejecutando `uv run tareas validar` y dime qué orden con --simular debo probar yo.Estado actual del repo:!`git status --short`

Piezas del comando

nueva-accion.md → /nueva-accion

El nombre del fichero es el nombre del comando.

Frontmatter del comando

description es lo que ves en la lista al escribir /; agent: build lo ejecuta con el agente que puede editar (igualmente te pedirá permiso para cada cambio).

$ARGUMENTS

Se sustituye por todo lo que escribas detrás del comando. $1, $2…: cada argumento por separado (entre comillas si lleva espacios).

!`git status --short`

Ejecuta esa orden antes de enviar el prompt y mete su salida: el agente sabe qué ficheros tienes sin guardar. Va fuera de tus permisos: solo órdenes de confianza.

«Espera mi visto bueno»

El paso 2 del comando («propón primero la entrada JSON») es el que mantiene la decisión en tus manos.

@fichero no se adjunta

Un @fichero escrito dentro del comando no se adjunta: adjúntalo en la caja al lanzarlo.

Más detalle en la guía: Comandos personalizados.

Úsalo para tu 2.ª acción

Vuelve a abrir OpenCode (o opencode reload) y lánzalo en la caja de entrada:

Caja de entrada de OpenCode
/nueva-accion renombrar-capturas "renombra capturas de pantalla con su fecha"
/nueva-accionel comando
renombrar-capturas$1
"renombra capturas de pantalla con su fecha"$2

Antes de dar el visto bueno

Lee la entrada JSON que te propone y corrige lo que no te guste antes de dar el visto bueno:

  • ¿El filtro coge solo las capturas?
  • ¿La plantilla es la que tú quieres?
  • ¿El destino está en ~/pruebas-tareas mientras pruebas?

Al final te dirá qué orden con --simular debes probar: la ejecutas tú. Repite con tu 3.ª acción (una idea tuya, no un ejemplo de esta página).

El comando ahorra escribir, no decidir

Las 3 acciones tienen que ser tuyas: qué hacen, con qué ficheros y por qué te sirven. En la defensa te preguntaré por ellas.

Paso 6 · Tu subagente revisor

El agente que escribe el código no es el mejor para revisarlo: ya está convencido de que está bien. Un subagente es otro agente, con su propio prompt y sus propios permisos, que trabaja en una conversación aparte y devuelve el resultado. Crea .opencode/agents/revisor.md:

Puede, sin preguntarNo puede: denyLeer tu códigogit diffgit loggit statusEditar ficherosNavegar por la webOtras órdenesEjecutar tus acciones

Desliza el diagrama de lado para verlo entero

Un subagente tuyo solo tiene sus permisos: no hereda los del agente que lo llama.

revisor.md

.opencode/agents/revisor.md
---description: Revisa el código de la CLI tareas sin modificar nada y señala errores, casos feos y problemas multiplataformamode: subagentpermissions:  - { action: edit, resource: "*", effect: deny }  - { action: webfetch, resource: "*", effect: deny }  - { action: shell, resource: "*", effect: deny }  - { action: shell, resource: "git diff *", effect: allow }  - { action: shell, resource: "git log *", effect: allow }  - { action: shell, resource: "git status *", effect: allow }---Eres el revisor de código del proyecto (1º DAM). Revisa lo que te indiquen y responde en español con:1. Errores seguros (con fichero y línea).2. Casos feos sin cubrir: ruta inexistente, carpeta vacía, nombres con tildes o espacios, JSON roto, destino que ya existe.3. Problemas en Windows/macOS (rutas, encoding, shell).4. Una pregunta que el alumno debería saber responder sobre ese código.No reescribas el código: señala y explica.

Cómo está hecho el revisor

revisor.md → revisor

El nombre del fichero es el id del agente.

mode: subagent

No aparece al cambiar con shift+tab (eso es para plan y build). Se le pide con palabras, o el agente principal lo lanza solo si su description encaja con lo que necesita.

El cuerpo, su prompt

Qué revisar y en qué formato responder.

Los permisos del revisor

permissions es una lista de reglas (acción · recurso). Va primero la general y después las excepciones: gana la última que coincide.

  • edit · *

    No puede editar ningún fichero: solo lectura.

  • webfetch · *

    No puede navegar por la web.

  • shell · *

    Ninguna orden de la terminal…

  • shell · git diff *

    …salvo ver los cambios,

  • shell · git log *

    el historial

  • shell · git status *

    y qué ficheros han cambiado.

Aunque quisiera, no puede «arreglarte» nada ni ejecutar tus acciones.

Cómo se usa el revisor

Sal y vuelve a abrir OpenCode (en la terminal, opencode debug agents debe mostrar revisor). Se usa pidiéndoselo con palabras:

Caja de entrada de OpenCode
Usa el subagente revisor para revisar src/tareas/motor.py

Además, OpenCode trae /review, que revisa los cambios sin commitear. La rutina a partir de hoy: antes de cada commit de código, /review o el revisor.

Más detalle en la guía: Agentes y subagentes.

Tú decides qué se arregla

El revisor también se equivoca: a veces ve fallos que no existen o propone cosas que no tocan esta semana. Por cada punto, compruébalo (léelo, pruébalo en ~/pruebas-tareas) y decide: lo arreglas (con build, en otra petición), lo apuntas como mejora en el README o lo descartas sabiendo por qué.

Y contesta tú la pregunta que te hace al final.

Paso 7 · Tu primer ADR

Un ADR (Architecture Decision Record, registro de decisión de arquitectura) es un documento corto que cuenta una decisión técnica importante: qué decidiste, por qué y qué alternativas descartaste. Se escribe para la persona que llegue dentro de seis meses (muchas veces, tú mismo) y se pregunte «¿por qué narices está hecho así?». Los equipos profesionales los guardan numerados en docs/adr/. Tu primera decisión es la de esta semana: crea docs/adr/0001-configuracion-externa.md y termínalo con TUS razones (los huecos [...]).

Un ADR, cuatro partesContextoqué pasa y por quéhay que decidirDecisiónqué haces:acciones en JSONAlternativasqué descartastey por quéConsecuenciaslo bueno, lo maloy qué harás si cambiaNo se borran: si cambias de opinión, un ADR nuevo sustituye al anterior

Desliza el diagrama de lado para verlo entero

ADR: contexto y decisión

docs/adr/0001-configuracion-externa.md
# ADR-0001: Las acciones viven en acciones.json, no en el código​- Estado: aceptada- Fecha: 2026-11-04- Autor/a: [tu nombre]​## Contexto​Mi herramienta «tareas» automatiza tareas repetitivas con ficheros(ordenar Descargas, renombrar fotos, limpiar temporales...). Cada personaque la use tendrá carpetas y manías distintas, y yo mismo voy a quererañadir acciones nuevas cada pocas semanas. [Añade TU situación: quéacciones tienes y quién más la va a usar.]​## Decisión​Las acciones se describen en un fichero JSON externo (acciones.json) conun esquema documentado en el README. El código solo contiene el MOTOR quelee, valida y ejecuta ese fichero. Añadir una acción = editar el JSON.

ADR: alternativas y consecuencias

docs/adr/0001-configuracion-externa.md
## Alternativas consideradas​1. Escribir cada acción como una función en Python.   - A favor: [...]   - En contra: cada cambio exige tocar el código y volver a instalar; quien     no programa no puede añadir acciones.2. Usar YAML o TOML en vez de JSON.   - A favor: [...]   - En contra: [...]3. [Otra que se te ocurra o que te propusiera la IA]​## Consecuencias​- Positivas: añadir una acción no toca el código; el JSON se puede validar  antes de ejecutar nada; [...]- Negativas: hay que mantener la validación al día cuando el esquema  crezca; los errores de escritura en el JSON solo se ven al ejecutar  validar; [...]- Qué haré si el esquema cambia: [por ejemplo, subir "version" a 2 y ...]

El agente, abogado del diablo

Puedes usar al agente en plan (no puede editar) como abogado del diablo:

Prompt · agente plan
Lee @docs/adr/0001-configuracion-externa.md y dame 3 argumentos en contra de mi decisión y una alternativa que no haya considerado

Pero el texto final es tuyo: en la defensa te preguntaré por él.

Paso 8 · Audita, prueba y commitea

«Lo que no sabes explicar, no lo entregas». Antes de dar por buena cada acción, pasa esta auditoría en ~/pruebas-tareas:

¿Qué pasa si ejecuto dos veces la misma acción?

Mover: la segunda vez no encuentra nada en origen (bien). Renombrar: no debería generar 2026-10-26_001_001… ni cambiar números a lo loco. Copiar: aparecen «(1)», no se machaca nada.

¿Y si la carpeta de destino no existe?

Se crea al ejecutar de verdad; con --simular NO se crea (compruébalo con ls / dir).

¿Y si el destino ya tiene un fichero con ese nombre?

Sufijo « (1)» y la tabla lo enseña. Nunca se pierde un fichero.

¿Nombres con tildes, eñes o espacios?

«cumpleaños 2.png» y «apuntes de redes.docx» se mueven y se ven bien en la tabla.

Más preguntas de la auditoría

¿Mayúsculas en la extensión?

FOTO1.JPG entra en el filtro de .jpg.

¿La carpeta de origen no existe o la acción no existe?

Mensaje humano en rojo y código de salida 1, sin traceback.

¿Borrar sin --si?

Pregunta antes. Si contestas que no, no borra nada y sale con código distinto de 0.

¿Dos ficheros que se renombran al MISMO nombre en una simulación?

Caso traicionero: destino_libre mira el disco, y en simulación el primero aún no existe. ¿Tu tabla lo detecta? Si no, apúntalo como mejora en el README.

Prueba en otro sistema si puedes

En el aula tienes Linux; si en casa usas Windows o macOS, clona el repo allí y repite los bloques de prueba del paso 4. Los fallos típicos aparecen aquí:

Rutas con barra invertida

Rutas montadas a mano con \ o con /: en otro sistema no existen.

Tildes que salen como ñ

Falta encoding="utf-8" al leer o escribir.

Colores raros

En una consola antigua, los colores de Rich pueden salir como códigos extraños.

Cada fallo que encuentres y arregles es un commit con historia.

Un commit por pieza, hecho por ti

El agente no hace commits ni push: se lo prohíbe tu AGENTS.md, y tu opencode.json bloquea el push y te pregunta antes de cualquier commit.

mainEsquema de acciones.json con mi primera acción, documentado en el READMESkill acciones-json: el agente carga las reglas de mi esquemaValidación de acciones.json con ConfigError/AccionNoValida y orden validar (sale con 3)Motor y clases Accion: --simular no toca el disco y nunca sobrescribeÓrdenes acciones y ejecutar con tabla Rich, --si y --configComando /nueva-accion: propone el JSON y espera mi visto buenoAcción renombrar-capturas creada con /nueva-accion y probada con --simularSubagente revisor de solo lectura (edit: deny)Arreglo del revisor: nombres con tildes al renombrarADR-0001: por qué configuración externa; prompts clave de la semanagit push → GitHub

Desliza el diagrama de lado para verlo entero

Tus commits, del 1 al 5

Los ficheros de .opencode/ también se commitean: son parte de tu proyecto. Algo así, con tus palabras:

Terminal · commits de la semana
git add acciones.json README.mdgit commit -m "Esquema de acciones.json con mi primera acción, documentado en el README"​git add .opencode/skills/acciones-json/SKILL.mdgit commit -m "Skill acciones-json: el agente carga las reglas de mi esquema"​git add src/tareas/errores.py src/tareas/config.py src/tareas/cli.pygit commit -m "Validación de acciones.json con ConfigError/AccionNoValida y orden validar (sale con 3)"​git add src/tareas/acciones.py src/tareas/motor.pygit commit -m "Motor y clases Accion: --simular no toca el disco y nunca sobrescribe"​git add src/tareas/cli.pygit commit -m "Órdenes acciones y ejecutar con tabla Rich, --si y --config"

Tus commits, del 6 al 10

Terminal · commits de la semana
git add .opencode/commands/nueva-accion.mdgit commit -m "Comando /nueva-accion: propone el JSON y espera mi visto bueno"​git add acciones.jsongit commit -m "Acción renombrar-capturas creada con /nueva-accion y probada con --simular"​git add .opencode/agents/revisor.mdgit commit -m "Subagente revisor de solo lectura (edit: deny)"​git add src/tareas/acciones.pygit commit -m "Arreglo del revisor: nombres con tildes al renombrar"​git add docs/adr/0001-configuracion-externa.md docs/prompts.mdgit commit -m "ADR-0001: por qué configuración externa; prompts clave de la semana"git push

docs/prompts.md: la prueba de que auditaste

En docs/prompts.md, los prompts de la validación, del motor y de la CLI, con una línea por prompt de qué tuviste que corregir de lo que hizo el agente y qué te señaló el revisor.

Checklist de la semana

Los ocho pasos de un vistazo, y lo que tiene que estar hecho al acabar:

1 · Esquemaa mano, sin IA2 · Skillenseñas tu esquema3 · Validarantes de ejecutar4 · Motorclases y --simular5 · Comandotus acciones 2 y 36 · Revisorsolo lectura7 · ADRtus razones8 · Commitsy push a GitHub

Desliza el diagrama de lado para verlo entero

Checklist: tu herramienta

  • acciones.json con al menos 3 acciones TUYAS (no las del ejemplo) y el esquema documentado en el README.
  • «tareas validar» detecta los casos feos con mensajes que dicen qué acción y qué campo fallan, y sale con 3.
  • errores.py con TareasError, ConfigError y AccionNoValida; ningún traceback ante errores previsibles.
  • acciones.py con la clase base Accion, la fábrica desde_config y una subclase por tipo; motor.py con la clase Motor.
  • «tareas acciones» y «tareas ejecutar NOMBRE [CARPETA] --simular / --si» funcionando, y --config RUTA.
  • Probado en ~/pruebas-tareas y con el destino también en pruebas: siempre --simular primero; nada sobrescrito, nada perdido.

Checklist: tu proceso

  • .opencode/skills/acciones-json/SKILL.md en el repo y visible en /skills.
  • .opencode/commands/nueva-accion.md en el repo y usado para tu 2.ª y 3.ª acción.
  • .opencode/agents/revisor.md en el repo; el subagente revisor o /review antes de cada commit de código.
  • docs/adr/0001-configuracion-externa.md terminado con TUS razones.
  • docs/prompts.md con los prompts clave de la semana y qué tuviste que corregir de lo que hizo el agente.
  • ≥ 10 commits tuyos acumulados (los de la Sesión 1 cuentan) con mensajes que cuentan el proceso, y push a GitHub.

Lo que cuenta en la rúbrica

Antes que nada, los 4 mínimos de CLI «tareas con IA»: si falla uno, el proyecto no se evalúa. Esta semana ya puedes cumplir el segundo y avanzar mucho en el cuarto.

  1. Se instala siguiendo el README y la orden de ayuda (--help) funciona.
  2. Al menos 3 acciones propias definidas en el fichero de configuración (acciones.json) funcionan.esta semana lo cumples
  3. Ninguna clave ni secreto en el repositorio ni en su historial.
  4. Historial git real: mínimo 10 commits con mensajes que cuentan el proceso.esta semana avanzas mucho

Peso de cada criterio

Y estos criterios se juegan casi enteros con el trabajo de hoy:

Acciones predefinidas funcionando · 20Configuración externa (acciones.json) · 15Capa IA, secretos y modo sin red · 15Robustez: excepciones y entradas feas · 15Diseño en clases y módulos · 10Pruebas y calidad · 15Instalación, documentación y proceso · 10

Desliza el diagrama de lado para verlo entero

En azul, los criterios que se juegan casi enteros esta semana. Suman 60 de los 100 puntos.

Criterios: acciones y configuración

Acciones predefinidas funcionando

peso 20

Lo que tu herramienta hace de verdad con tus ficheros.

Insuficiente · 0 %
Ninguna acción funciona de principio a fin, o solo el ejemplo de partida.
En desarrollo · 50 %
1-2 acciones propias que funcionan en el caso fácil; salida confusa o efectos inesperados.
Competente · 80 %
3-4 acciones propias útiles, con salida clara (qué se ha hecho y sobre qué ficheros) y modo simulación.
Excelente · 100 %
5 o más acciones propias útiles, combinables, con salida clara y sin efectos sorpresa (simulación previa o confirmación antes de borrar o sobrescribir).

Configuración externa (acciones.json)

peso 15

Las acciones viven en un fichero que escribes tú, no dentro del código.

Insuficiente · 0 %
Las acciones están escritas a mano dentro del código.
En desarrollo · 50 %
Existe acciones.json pero el código lo lee sin comprobar nada: un error en el JSON rompe el programa.
Competente · 80 %
Esquema propio documentado en el README; el JSON se valida antes de ejecutar y los errores dicen qué campo falla.
Excelente · 100 %
Además: añadir una acción no exige tocar el código y hay un ADR que justifica por qué configuración externa y no código.

Criterios: robustez y diseño

Robustez: excepciones y entradas feas

peso 15

Qué pasa cuando el usuario se equivoca o el disco no es como esperabas.

Insuficiente · 0 %
Cualquier error (ruta inexistente, JSON roto) termina en un traceback.
En desarrollo · 50 %
Se capturan algunos errores, con mensajes genéricos («error»).
Competente · 80 %
Errores previsibles controlados con mensajes humanos y código de salida distinto de 0; nunca se pierde un fichero por un fallo a medias.
Excelente · 100 %
Excepciones propias (ConfigError, AccionNoValida…) con mensajes humanos; ningún traceback ante errores previsibles; aserciones en desarrollo.

Diseño en clases y módulos

peso 10

Cómo está organizado el código por dentro.

Insuficiente · 0 %
Todo en un único fichero sin funciones ni clases.
En desarrollo · 50 %
Funciones separadas, pero interfaz, lógica y ficheros mezclados.
Competente · 80 %
Módulos separados (cli, motor, acciones, configuración) y clases con una responsabilidad clara.
Excelente · 100 %
Responsabilidades separadas (interfaz, motor, acciones, proveedor IA), visibilidad cuidada y métodos estáticos con sentido (p. ej., fábricas desde la configuración).

Qué viene después

estás aquíSemana 1ArranqueSemana 2acciones.json y motorSemana 3MCP y capa IASemana 4pruebas y releaseEntregasemi: 20 nov

Desliza el diagrama de lado para verlo entero

Las próximas semanas

  1. Semana 3 · MCP y capa IA

    9-13 nov

    Sesión 3 · La capa IA →
    • OpenCode con MCP: el servidor context7 para consultar documentación de librerías, activado solo cuando hace falta.
    • La capa IA de tu CLI: acciones que deciden con los mismos modelos del centro, llamados desde Python.
    • La clave, fuera del repo, y un modo sin red.
  2. Semana 4 · Pruebas y release

    16-20 nov

    Sesión 4 · Pruebas y release v1.0 →
    • Pruebas con pytest que escribe el agente y auditas tú.
    • opencode run sin interfaz (por ejemplo, en scripts).
    • README de instalación y release v1.0.
  3. Semipresencial · Quincena 4

    Del 9 al 20 de noviembre

    • IA, pruebas y release.
    • Entrega el viernes 20 de noviembre.