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.
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:
Desliza el diagrama de lado para verlo entero
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.
Desliza el diagrama de lado para verlo entero
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
Lo interpreta: npm / Node
package.json
Lo interpreta: Docker
docker-compose.yml
Lo interpreta: VS Code
settings.json de VS Code
Lo interpreta: uv / pip
pyproject.toml
Lo interpreta: OpenCode
opencode.json · AGENTS.md · .opencode/
Lo interpreta: TU motor
acciones.json
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.
Desliza el diagrama de lado para verlo entero
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.
Desliza el diagrama de lado para verlo entero
Los seis pasos, uno a uno
1 · Tú escribes la intención
2 · Agente plan
3 · Agente build
4 · Auditas
~/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
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:
{ "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
tareas ejecutar ordenar-descargasDespués de ordenar
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.
{ "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
tareas ejecutar renombrar-fotos ~/pruebas-tareas/DescargasDespués de renombrar
La acción limpiar-temporales
{ "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
tareas ejecutar limpiar-temporales ~/pruebas-tareas/Descargaspregunta antes de borrarDespués de limpiar
Campo a campo
Desliza el diagrama de lado para verlo entero
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.
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:
- FácilMover las capturas de pantalla del escritorio a
~/Imágenes/Capturas(filtro por extensión). - MediaCopiar los apuntes de DAM modificados hace menos de 7 días a una carpeta de copia, o borrar instaladores
.exe/.debde más de 60 días. - DifícilRenombrar las fotos del móvil a
{fecha:%Y-%m-%d}_{n:03}{ext}usando unpatronregex que solo coja las que empiezan porIMG_oPXL_.
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.
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.
La skill acciones-json
---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
---. 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
Se carga cuando encaja
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
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
- 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. - Escribe
/skills: tiene que apareceracciones-json. - Y a git, que la skill es parte de tu proyecto:
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.
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:
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 validaredit · *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:
Desliza el diagrama de lado para verlo entero
errores.py de referencia
# src/tareas/errores.pyclass TareasError(Exception): """Base de todos los errores previsibles de la herramienta.""" codigo_salida = 1class ConfigError(TareasError): """acciones.json no existe, no es JSON o no cumple el esquema.""" codigo_salida = 3class 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 = campoconfig.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.
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
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?
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 accionesPruébalo y mira el código de salida
En tu terminal, o desde OpenCode con ! delante:
uv run tareas validarecho $? # Linux/macOS: 0 si es válido, 3 si no$LASTEXITCODE # lo mismo en PowerShellCasos 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.
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
simulado
--simular: dice qué haría, sin tocar nada.saltado
Motor: plan y luego build
Sesión nueva (/new). Primero en plan; cuando el plan te cuadre, en build:
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 discoCarga 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.Pathsiempre: ninguna ruta montada con+ "/" +ni con\.Path.expanduser()para~;encoding="utf-8"en todoopen()oread_text().shutil.moveyshutil.copy2; nada deos.system,subprocessnishell=True.- Nombres con tildes y espacios funcionan.
- Con
simular=Trueno se llama amkdir,move,renameniunlink. - 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:
@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 libreacciones.py: la clase base Accion
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
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
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
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
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
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 elegidosmotor.py: ejecutar una acción
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:
tareasprogramaejecutarordenordenar-descargasNOMBRE de la acción~/pruebas-tareas/Descargas[CARPETA], opcional--simularopcióntareas acciones
--simular · --si
--config RUTA
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:
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 --helpcli.py: --config para todas las órdenes
# 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 = configcli.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.
@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 → estadoLo que deberías ver
Fíjate en el sufijo « (1)»: ya había una factura.pdf en el destino.
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)
# 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 3Pruebas en Windows (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 3Paso 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.
Desliza el diagrama de lado para verlo entero
nueva-accion.md
Crea .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
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
$1, $2…: cada argumento por separado (entre comillas si lleva espacios).!`git status --short`
«Espera mi visto bueno»
@fichero no se adjunta
@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:
/nueva-accion renombrar-capturas "renombra capturas de pantalla con su fecha"/nueva-accionel comandorenombrar-capturas$1"renombra capturas de pantalla con su fecha"$2Antes 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-tareasmientras 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:
Desliza el diagrama de lado para verlo entero
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
mode: subagent
description encaja con lo que necesita.El cuerpo, su prompt
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:
Usa el subagente revisor para revisar src/tareas/motor.pyAdemá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 [...]).
Desliza el diagrama de lado para verlo entero
ADR: contexto y decisión
# ADR-0001: Las acciones viven en acciones.json, no en el código- Estado: aceptada- Fecha: 2026-11-04- Autor/a: [tu nombre]## ContextoMi 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ónLas 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
## Alternativas consideradas1. 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:
Lee @docs/adr/0001-configuracion-externa.md y dame 3 argumentos en contra de mi decisión y una alternativa que no haya consideradoPero 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?
¿Y si la carpeta de destino no existe?
¿Y si el destino ya tiene un fichero con ese nombre?
¿Nombres con tildes, eñes o espacios?
Más preguntas de la auditoría
¿Mayúsculas en la extensión?
¿La carpeta de origen no existe o la acción no existe?
¿Borrar sin --si?
¿Dos ficheros que se renombran al MISMO nombre en una simulación?
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
\ o con /: en otro sistema no existen.Tildes que salen como ñ
encoding="utf-8" al leer o escribir.Colores raros
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.
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:
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
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 pushdocs/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:
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.
- Se instala siguiendo el README y la orden de ayuda (--help) funciona.
- Al menos 3 acciones propias definidas en el fichero de configuración (acciones.json) funcionan.esta semana lo cumples
- Ninguna clave ni secreto en el repositorio ni en su historial.
- 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:
Desliza el diagrama de lado para verlo entero
Criterios: acciones y configuración
Acciones predefinidas funcionando
peso 20Lo 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 15Las 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 15Qué 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 10Có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
Desliza el diagrama de lado para verlo entero
Las próximas semanas
- 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.
- 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.
Semipresencial · Quincena 4
Del 9 al 20 de noviembre
- IA, pruebas y release.
- Entrega el viernes 20 de noviembre.
