Arranque: la terminal y tu primera orden

Esta semana pierdes el miedo a la pantalla negra y empiezas a programar como se programa ya: con un agente. Aprendes a moverte por la terminal, instalas las herramientas, creas tu proyecto en Python y construyes tu primera orden con OpenCode: tú decides y apruebas, el agente escribe. Todo paso a paso: si nunca has abierto una terminal, empiezas en el paso 0 y llegas igual que el resto.

Paso 0 · Abre la terminal 10 min

La terminal es una ventana donde escribes órdenes en lugar de hacer clic. Es más rápida, se puede automatizar y es donde vive casi todo lo que hace un programador: Git, Python, servidores. Ábrela así:

Lee el prompt antes de escribir

El prompt es el texto que la terminal escribe sola antes del cursor. Te dice quién eres, en qué máquina y, lo más importante, en qué carpeta estás:

Paso 1 · Supervivencia en la terminal 15 min de práctica + reto

Con quince órdenes te mueves por cualquier ordenador. Antes, dos ideas: todo fichero vive en un árbol de carpetas, y para llegar a él escribes una ruta.

Las órdenes básicas (bash: Linux y macOS)

Escríbelas una a una, no las pegues todas a la vez: el objetivo es que tus dedos las aprendan.

Las mismas en PowerShell (Windows)

PowerShell entiende muchos nombres de bash (ls, cd, pwd, cat, cp, mv, rm) como alias, pero las opciones cambian. Los nombres «de verdad» son estos:

Cuatro trucos que te ahorran horas

• •↑ y ↓: recorren las órdenes que ya escribiste. No vuelvas a teclear una orden larga.
• •Tab: autocompleta nombres de carpetas y ficheros. Escribe cd pru + Tab. Si no completa, pulsa Tab dos veces y verás las opciones. Así no hay erratas.
• •Ctrl+C: corta la orden que está en marcha (si algo se queda «colgado»). En la terminal no sirve para copiar: usa Ctrl+Shift+C / Ctrl+Shift+V en Linux, o selecciona con el ratón.
• •--help: casi toda orden explica sus opciones con orden --help. Tu herramienta también lo hará.

Mini-reto: tu carpeta de pruebas para toda la semana

Tu herramienta va a mover, renombrar y borrar ficheros. Nunca la pruebes con tus ficheros reales: créate una carpeta de pruebas con ficheros de mentira (vacíos). Ejecuta el bloque de tu sistema y comprueba el resultado con ls -la. Si lo rompes, bórrala y vuelve a crearla: para eso está.

🐧🍎 bash (Linux y macOS)

🪟 PowerShell (Windows)

Comprueba que tienes 3 .pdf (uno con espacios), un .docx, 5 .tmp (dos de ellos con fecha de septiembre), 3 imágenes en fotos/ y un notas.txt con texto en docs/. En ls -la, fíjate en la columna de la fecha de los viejo-*.tmp: la usarás en la semana 2 para «borrar temporales de más de 30 días».

Permisos: por qué a veces dice «Permiso denegado»

En Linux y macOS cada fichero tiene permisos de lectura (r), escritura (w) y ejecución (x) para ti, tu grupo y el resto. ls -l los enseña en la primera columna. Pruébalo con un script de una línea:

En Windows no hay chmod: lo que decide si algo se ejecuta es la extensión (.exe, .ps1) y la política de ejecución de PowerShell. Tu comando tareas lo instalará uv con los permisos correctos en los tres sistemas.

El PATH: la lista de sitios donde la terminal busca órdenes

¿Por qué ls funciona en cualquier carpeta y saludo.sh no? Porque cuando escribes una orden sin ruta, la terminal la busca en una lista de carpetas llamada PATH, por orden, y ejecuta la primera que encuentra. ls está en /usr/bin, que está en el PATH. Tu carpeta de pruebas no; por eso hay que escribir ./saludo.sh (ruta relativa).

Guárdate la idea: en el paso 6 instalarás tareas en una carpeta que debe estar en el PATH. Si un día escribes una orden y te dice «orden no encontrada» o «no se reconoce como nombre de un cmdlet», el 99 % de las veces es el PATH.

Paso 2 · Instala las herramientas: git, uv y OpenCode 35 min

Necesitas tres cosas: git (ya lo usaste en la web de marca), uv, el gestor de proyectos Python que usaremos (crea el proyecto, instala Python, gestiona dependencias y entornos virtuales y convierte tu código en un comando: una sola herramienta en lugar de pip, venv, pipx y pyenv), y OpenCode, el agente que va a escribir código contigo. En los equipos del aula puede que ya estén instalados: compruébalo con git --version, uv --version y opencode --version antes de instalar nada.

2.1 · git y uv

🐧🍎 Linux y macOS

🪟 Windows (PowerShell)

Debes ver git (cualquiera reciente), uv y un Python 3.12 o superior. Fíjate en que el instalador de uv es un script descargado de internet que se ejecuta en tu máquina: está bien porque viene de la web oficial de Astral, pero nunca lo hagas con una URL que no conoces.

Alternativa clásica (solo si uv no te funciona y ya lo has consultado): Python 3.12 de python.org, python -m venv .venv + pip install typer, y pipx para instalar el comando. Funciona, pero son más pasos y en clase todo irá con uv.

2.2 · OpenCode 1.18.35 (versión fijada)

En clase usamos exactamente la 1.18.35. Conviven OpenCode 1 y OpenCode 2, con configuraciones incompatibles: si instalas «la última» te llevas la 2 y nada de lo que copies de estas páginas funcionará.

🐧🍎 Linux y macOS

🪟 Windows (PowerShell)

• •El script de Linux/macOS instala en ~/.opencode/bin y añade esa carpeta al PATH: por eso hay que abrir una terminal nueva.
• •En Windows, OpenCode necesita Git for Windows porque ejecuta sus órdenes con Git Bash, y Node LTS para instalarse con npm. Alternativa que recomienda su documentación: WSL (Ubuntu dentro de Windows) y el script de Linux.
• •No uses brew install opencode ni pacman -S opencode: instalan la versión 2.
• •Si un tutorial habla de permissions o agents en plural, es de OpenCode 2. Nosotros escribimos permission, agent y provider en singular.

2.3 · Conéctalo con los modelos del centro

OpenCode no trae inteligencia propia: habla con un modelo de IA. Usaremos los modelos locales del instituto (un servidor del centro con API compatible con OpenAI). La configuración va en tu carpeta personal, no en el repo: crea la carpeta y abre el fichero con tu editor.

Pega esto tal cual (no cambies nada: la dirección y la clave salen de variables de entorno):

• •provider.centro: un proveedor que llamamos «centro», compatible con la API de OpenAI.
• •{env:CENTRO_IA_URL} y {env:CENTRO_IA_KEY}: OpenCode lee la dirección y la clave de dos variables de entorno. Así la clave no está escrita en ningún fichero que pueda acabar en git.
• •model: el modelo que usa por defecto, en formato proveedor/modelo.
• •"autoupdate": false: que no se actualice solo (y se pase a la 2).
• •Si tu editor marca provider como «deprecated», ignóralo: el esquema publicado ya es el de la versión 2.

Ahora las dos variables. La dirección (termina en /v1) y la clave te las da el profesor en clase o en el aula virtual. No las publiques en el repo, en el README ni en ningún chat.

🐧🍎 bash (Linux y macOS)

🪟 PowerShell (Windows)

En una terminal nueva, comprueba que todo encaja:

Paso 3 · Crea el proyecto a mano y haz el primer commit 35 min

El esqueleto lo haces tú, sin agente: son cuatro órdenes y así sabes qué hay en tu repo antes de dejar entrar a nadie. Ve a la carpeta donde guardas tus proyectos (no dentro de pruebas-tareas ni dentro del repo de la web de marca):

Qué significa cada trozo de la orden importante:

• •uv init: crea un proyecto Python nuevo.
• •--package: con estructura de paquete instalable (carpeta src/). Es lo que permite convertirlo en un comando.
• •--name tareas: el paquete se llama tareas. Sin esto, uv lo llamaría cli_tareas (el nombre de la carpeta con guion bajo).
• •--python 3.12: fija la versión mínima de Python.
• •cli-tareas: la carpeta que crea (y el nombre de tu repo).
• •uv add typer: añade Typer, la librería para hacer CLIs (trae Rich, la de colores y tablas), y crea el entorno virtual .venv/.

Dos ajustes a mano

Abre la carpeta en tu editor (en casa, code . abre VS Code aquí). Primero, en pyproject.toml, cambia la línea de [project.scripts]: ese bloque dice «cuando instalen esto, crea un comando tareas que ejecute el objeto app del módulo tareas/cli.py». Rellena también la descripción.

Segundo, sustituye el contenido de src/tareas/__init__.py (uv pone una función main de ejemplo que ya no usaremos) por solo la versión:

Todavía no funciona uv run tareas: falta cli.py, que construirá el agente en el paso 5. Si lo pruebas ahora verás ModuleNotFoundError: No module named 'tareas.cli', y es normal.

.gitignore y .gitattributes antes de nada

Antes del primer commit decides qué no entra nunca en el repo. Un secreto que llega a un commit se queda en el historial aunque lo borres después, y en la semana 3 tendrás una clave en .env. Sustituye el .gitignore que ha creado uv por este (el de uv no incluye .env):

Y crea .gitattributes con una sola línea. Hace que Git guarde los saltos de línea igual venga el fichero de Windows (CRLF) o de Linux/macOS (LF): sin ella, un compañero con Windows te cambiaría todas las líneas de todos los ficheros en un solo commit.

Primer commit, ANTES de abrir OpenCode

Si Git te pregunta quién eres o no lo tienes configurado en este equipo, repasa la configuración global de la sesión 2 de la web de marca.

Fíjate en que añadimos los ficheros por su nombre y no con git add . a ciegas: así ves qué entra. Si en el git status aparece .venv o .env, para: tu .gitignore no está bien guardado.

Sube el repo a GitHub (público)

Si al hacer push te pide usuario y contraseña, la contraseña es un token, no la de tu cuenta: lo tienes explicado en «Usuario y contraseña: qué escribir exactamente». Abre tu repo en el navegador y comprueba que se ven src/, pyproject.toml y .gitignore, y que no se ve .venv.

Paso 4 · Prepara a tu agente: permisos y AGENTS.md 35 min

Un chat solo genera texto y tú copias y pegas. Un agente además usa herramientas: lee tus ficheros, los edita y ejecuta órdenes en tu terminal, mira el resultado y decide el siguiente paso. Por eso, antes de dejarlo trabajar, decides qué puede hacer solo, qué te tiene que preguntar y qué tiene prohibido. Eso va en un opencode.json en la raíz de cli-tareas, que sí se sube al repo (no lleva ninguna clave).

Abre OpenCode en la carpeta del proyecto

Trabaja con dos terminales: una con OpenCode y otra para ti (git, pruebas). En VS Code, el botón + o «dividir» de la terminal; en el aula, otra pestaña.

Lo que ves es una TUI (interfaz de texto): un programa de terminal con ventanas y atajos. La herramienta con la que vas a programar tu CLI es… otra CLI. Fíjate en cómo está hecha: es lo que estás aprendiendo a construir.

/init: el AGENTS.md del proyecto

AGENTS.md es un fichero en la raíz con las normas de tu proyecto para el agente: con qué está hecho, cómo se ejecuta y qué no debe hacer nunca. OpenCode lo lee al empezar cada sesión, así no tienes que repetirlo en cada mensaje. Escribe en OpenCode (agente build):

/init

Analiza el repo y te propone un AGENTS.md. Como tienes edit: ask, te enseñará el fichero antes de escribirlo: léelo y acéptalo. Después edítalo tú en tu editor hasta que diga esto (o algo muy parecido; si /init no lo genera bien, créalo tú directamente con esta plantilla):

Cada línea tiene un motivo: la de ~/pruebas-tareas protege tus ficheros reales, la de .env tus claves y la de «explica antes de cambiar» te da tiempo a decir que no. Los cambios en opencode.json no se aplican en caliente: si lo tocas, sal (ctrl+c) y vuelve a abrir opencode.

En tu otra terminal, el commit de la configuración del agente:

Paso 5 · Tu primera orden, de forma agéntica 75 min

Así trabajaremos todo el curso, en todas las sesiones: tú decides, el agente propone, tú corriges el plan, el agente implementa, tú apruebas cada cambio, tú pruebas y tú commiteas. El agente no decide qué hace tu herramienta.

1. 1Tú

   Escribes la intención: spec, criterio de aceptación.

2. 2plan

   «Explícame cómo lo harías»: lees y corriges el plan.

3. 3build

   «Hazlo»: apruebas cada edición y cada orden leyendo el diff.

4. 4Tú

   Auditas y pruebas con !uv run tareas …. Si falla: /undo o le explicas el fallo.

5. 5Tú

   Commit pequeño hecho por ti. Prompt clave a docs/prompts.md.

6. 6/new

   Sesión nueva para la siguiente tarea.

5.1 · Escribe la spec en el README (tú, sin IA · 15 min)

Copia esta plantilla en tu README.md y rellena los huecos tú. Piensa en una tarea real que te aburra: ordenar descargas, renombrar fotos del móvil, limpiar temporales, organizar apuntes por asignatura... Es lo que leerá el agente para saber qué construir.

# tareas

Mi herramienta de línea de órdenes para automatizar tareas repetitivas con ficheros.

## Spec (versión 0 · 26/10/2026)
1. **Problema:** cada semana pierdo tiempo en ________ (ej.: ordenar Descargas a mano).
2. **Para quién:** para mí y para ________.
3. **Cómo se usa:** `tareas ORDEN [CARPETA] [opciones]` desde cualquier terminal.
4. **Órdenes de la semana 1:** `tareas --help`, `tareas version`, `tareas listar [CARPETA]`.
5. **Órdenes previstas:** `tareas acciones`, `tareas validar`, `tareas ejecutar NOMBRE --simular`.
6. **Mis 3 acciones (borrador):** ________, ________, ________.
7. **Nunca hará:** borrar sin preguntar ni tocar ficheros fuera de la carpeta que le indique.
8. **Plataformas:** Linux primero; también Windows y macOS.
9. **Códigos de salida:** 0 bien · 1 fallo al ejecutar · 2 uso incorrecto · 3 configuración inválida.
10. **Instalación:** `uv tool install --editable .` (lo completo en la semana 4).

5.2 · Agente plan: que te cuente cómo lo haría

Pulsa Tab hasta que abajo ponga plan. En plan no puede tocar ningún fichero (lo dice tu opencode.json), así que puedes pedirle ideas sin miedo. Envía:

Lee @README.md y @pyproject.toml. Quiero src/tareas/cli.py (app de Typer llamada app) y src/tareas/__main__.py con dos órdenes: version y listar [CARPETA].
No escribas código todavía: dime qué ficheros crearías, qué funciones tendría cada uno y cómo tratarías la carpeta inexistente, la vacía, los nombres con corchetes y los ficheros que no se pueden leer.

Criterio de aceptación:
- uv run tareas sin argumentos muestra la ayuda, en español y sin autocompletado.
- version imprime «tareas 0.1.0» leyendo __version__ del paquete.
- listar (por defecto la carpeta actual, acepta ~) pinta una tabla Rich: Nombre, Tipo (extensión o «carpeta»), Tamaño legible, Modificado (AAAA-MM-DD HH:MM). Carpetas primero, luego alfabético sin distinguir mayúsculas.
- Carpeta inexistente o que no es carpeta: mensaje en stderr, sin traza, código 1. Carpeta vacía: aviso en vez de tabla vacía.
- pathlib, sin os.system ni subprocess, sin dependencias nuevas. uv run python -m tareas también funciona.

El texto es corto porque el agente lee tu repo: con @README.md y @pyproject.toml ya tiene el contexto. Lo que no puede faltar es el criterio de aceptación: cómo sabrás tú que está bien. Lee su plan buscando esto:

• ¿Toca solo src/tareas/cli.py y src/tareas/__main__.py? Si quiere cambiar más ficheros, pregunta por qué.
• ¿Añade dependencias nuevas? No hacen falta: Typer ya trae Rich.
• ¿Usa pathlib y expanduser()? ¿Dice qué hace con la carpeta inexistente, la vacía y los corchetes?
• ¿Hay algo que no entiendes? Pregúntalo ahora, antes de que escriba código.

Corrige el plan con un mensaje corto, por ejemplo:

Dos cambios al plan:
1. Escapa los nombres con rich.markup.escape para que [borrador].pdf salga entero.
2. Si un fichero da error al leer su fecha o tamaño (enlace roto, sin permisos), sáltalo sin romper la tabla.
Repíteme el plan corregido en 5 líneas.

5.3 · Agente build: «hazlo», y tú apruebas cada cambio

Pulsa Tab para volver a build y envía:

Hazlo con el plan corregido. Toca solo src/tareas/cli.py y src/tareas/__main__.py.
Cuando acabes, ejecuta uv run tareas --help y dime qué órdenes pruebo yo en ~/pruebas-tareas.

Ahora el agente trabaja y, cada vez que quiera escribir un fichero o ejecutar una orden que no está en tu lista de allow, se para y te pregunta. Puedes contestar:

Qué mirar en cada diff (líneas en verde: se añaden; en rojo: se quitan):

• ¿Es el fichero que esperabas? ¿Toca algo fuera de src/tareas/? Ojo especial con pyproject.toml y uv.lock.
• ¿Borra algo tuyo (líneas en rojo que no esperabas)?
• ¿Rutas escritas a mano con "/" o "\", os.system, subprocess o shell=True? Rechaza y pide pathlib.
• ¿Los mensajes al usuario están en español y los errores van por stderr?
• Si te pide ejecutar una orden: léela entera. ¿Sabes qué hace? ¿Toca algo fuera de cli-tareas? Si no lo tienes claro, reject y pregunta.

5.4 · Pruébalo tú

Que el agente diga «hecho» no significa que funcione. Pruébalo sin salir de OpenCode con ! (la salida le llega también al agente):

!uv run tareas version
!uv run tareas listar ~/pruebas-tareas
!uv run tareas listar /no/existe; echo $?

Y en tu otra terminal, la batería completa:

echo $? (bash) y $LASTEXITCODE (PowerShell) muestran el código de salida de la última orden: 0 si fue bien y otro número si falló. Los scripts y GitHub Actions deciden con él si algo ha funcionado, así que tu herramienta debe devolver el correcto. Nuestro convenio: 0 bien · 1 fallo al ejecutar · 2 error de uso (lo pone Typer) · 3 configuración inválida (semana 2).

5.5 · Si algo sale mal: /undo o explícale el fallo

• •Lo ha estropeado o se ha ido por las ramas: Esc si aún está trabajando y luego /undo (o ctrl+x u). Tus ficheros vuelven a como estaban antes de ese mensaje. Reformula y vuelve a intentarlo.
• •Funciona casi, pero falla un caso: no lo arregles a ciegas ni le digas «no funciona». Dale la orden, lo que sale y lo que esperabas, con el fichero:

!uv run tareas listar ~/pruebas-tareas/contrato.docx; echo $?
Sale una traza de Python y código 1; esperaba el mensaje de error en stderr y código 1, sin traza.
Corrige solo eso en @src/tareas/cli.py y explícame en 2 líneas qué fallaba.

/undo deshace ficheros, pero no lo que ya salió de tu equipo (un git push) ni lo que instaló. Por eso el push lo tiene prohibido y lo haces tú.

5.6 · Lo que deberías tener: audítalo contra esto

No hace falta que tu cli.py sea idéntico, pero debe hacer lo mismo. Compáralo línea a línea: si al tuyo le falta algo de lo que hay aquí (el escape, el typer.Exit(code=1), el expanduser()), pregúntale al agente en plan por qué no lo puso y decide tú.

• •@app.command() convierte una función en una orden. El docstring ("""...""") es lo que sale en --help.
• •El argumento carpeta tiene tipo Path: Typer convierte lo que escribes en una ruta de pathlib, que funciona igual en Linux, Windows y macOS.
• •raise typer.Exit(code=1) termina el programa con código 1 sin soltar una traza de Python al usuario.
• •El error va a Console(stderr=True): la salida de errores, separada de la normal. Así otro programa puede distinguir resultado y error.

Paso 6 · Instálala como comando de verdad 15 min

uv run tareas solo funciona dentro de la carpeta del proyecto. Para que tareas funcione en cualquier sitio, como git, ls u opencode, instálala (en tu terminal, no se lo pidas al agente):

uv tool install crea un entorno aislado para tu herramienta y deja un ejecutable tareas en la carpeta de comandos de uv (~/.local/bin en Linux y macOS). --editable significa que apunta a tu código: cuando cambies cli.py, el comando instalado cambia también, sin reinstalar. Solo hay que reinstalar si tocas pyproject.toml (dependencias o el nombre del comando): uv tool install --editable . --force.

Si dice «orden no encontrada», esa carpeta no está en tu PATH (¿te suena?):

Para quitarla (por ejemplo, para probar la instalación desde cero como hará quien use tu repo):

Paso 7 · Audita y commitea TÚ 30 min

«Lo que no sabes explicar, no lo entregas». Aprobar los diffs no basta: antes del commit, repasa esta lista. Si algo falla, pídele el arreglo al agente, pero entiende qué ha cambiado.

• ¿Entiendo cada línea de cli.py? Si hay una que no, pregúntale en plan: «explícame la línea N de @src/tareas/cli.py como si fuera mi primer año».
• ¿Qué pasa con una carpeta vacía? mkdir ~/pruebas-tareas/vacia && tareas listar ~/pruebas-tareas/vacia
• ¿Y con una ruta con espacios? tareas listar "~/pruebas-tareas/carpeta con espacios" (créala antes). Ojo: entre comillas, ~ no lo expande la terminal; lo tiene que hacer tu código con expanduser().
• ¿Y con un fichero en vez de carpeta? tareas listar ~/pruebas-tareas/contrato.docx; echo $? → mensaje y 1.
• ¿Y un nombre con corchetes? touch ~/pruebas-tareas/"[borrador].pdf" y lístalo: el nombre tiene que salir entero.
• ¿Funciona en Windows? Busca en el código barras escritas a mano dentro de rutas ("/"), os.system, shell=True o ficheros abiertos sin encoding="utf-8". Si tienes Windows, pruébalo; si no, pide a alguien que lo pruebe.
• ¿tareas --help se entiende sin haber leído el código? ¿Está en español?
• ¿El agente ha añadido dependencias u órdenes que no pediste? Mira git diff pyproject.toml y git status.

El agente propone el mensaje; el commit lo haces tú

El agente tiene prohibido el push y los commits los tiene que preguntar; además tu AGENTS.md le dice que no los haga. Pídele solo el texto:

Mira git diff y git status y propón un mensaje de commit en español, en imperativo, de una línea, que cuente qué cambia y para qué. No hagas el commit.

Léelo, cámbialo si no cuenta bien lo que hiciste, y commitea tú en tu terminal. Un commit = un paso con sentido. El mensaje dice qué cambia y para qué, en imperativo, como si terminara la frase «Este commit...».

Guarda tus prompts en docs/prompts.md

Crea docs/prompts.md y apunta los prompts clave con lo que corregiste tú. Es tu cuaderno de bitácora y una parte de la nota de proceso: demuestra que dirigiste al agente, no al revés. Si quieres guardar la conversación entera, /export (o ctrl+x x) la exporta a Markdown y la abre en tu editor; guárdala dentro de docs/ y revisa que no contenga ninguna clave antes del commit.

# Prompts clave del proyecto

## 2026-10-27 · Primera orden: listar
**Herramienta:** OpenCode 1.18.35 · modelo centro/qwen3.8-flash-next
**Prompt del plan (agente plan):** (pégalo tal cual lo enviaste)
**Qué corregí del plan:** ej.: no escapaba los nombres con corchetes; [foto].jpg salía sin corchetes.
**Diffs que rechacé o deshice (/undo) y por qué:** ej.: quería añadir la librería humanize.
**Funcionaba a la primera:** sí / no. Qué fallo le expliqué: ________
**Qué aprendí:** ej.: typer.Exit(code=1) termina con código 1 sin traza.

Checklist de la semana (el producto)

Si te atascas

Antes de pedir ayuda, lee el mensaje de error entero: casi siempre dice qué pasa. Si no lo entiendes, pégalo en el chat con la orden que escribiste y tu sistema operativo (sin claves). Estos son los habituales:

Terminal, uv y Git

OpenCode