Entorno, acceso y primer programa
Las herramientas cambian de interfaz, pero comparten la misma base: una carpeta de trabajo, archivos reales, un proceso y credenciales que deben protegerse. Aprenderás a leer este sistema antes de pedir cambios.
Qué trabajarás, paso a paso
Cuatro superficies, responsabilidades distintas
CLI, editor, web y API no son cuatro versiones de la misma pantalla. Exponen capacidades y responsabilidades distintas. La elección correcta depende de dónde esté el estado real y de qué prueba necesites al final.
La CLI trabaja cerca de los archivos y hace visibles comandos y salida. La extensión del editor añade contexto sobre la selección y el proyecto. La web es adecuada para razonamientos y sesiones no ligadas a una sola shell. La API habilita integraciones programáticas y exige una gestión explícita de claves y costes.
No existe una interfaz siempre mejor. Elige la que exponga las evidencias necesarias: para corregir un repositorio local hacen falta archivos y tests; para discutir una arquitectura puede bastar un contexto documental.
Tienes que entender los cambios de Task Notes, discutir el mensaje, revisar un archivo y luego generar borradores de forma repetible.
- Empiezas por la CLI para leer el historial de Git y producir la lista verificable de commits incluidos. Si te basta un borrador local, puedes quedarte aquí.
- Si quieres comparar dos estructuras narrativas, puedes usar la web proporcionando la lista como contexto; no finjas, sin embargo, que el chat ve el repositorio.
- Si necesitas pulir `RELEASE_NOTES.md` junto a los archivos modificados, el editor facilita comprobar referencias y nombres. No estás obligado a usar también la web.
- Introduce la API solo cuando el procedimiento sea realmente recurrente y merezca un script. Para este primer borrador todavía no hace falta: no añadas automatización antes de tener un trabajo repetible.
Resultado: Puedes resolver la tarea con una sola superficie o combinar varias. La elección depende de la prueba que necesitas, no de la idea de que el recorrido deba pasar por todas ellas.
Leer el terminal sin miedo
En el terminal no tienes que adivinar una fórmula secreta. Tienes que leer una secuencia: dónde estás, qué comando has ejecutado, qué salida has recibido y con qué estado ha terminado el proceso.
El prompt indica que la shell espera un comando. El comando se ejecuta en la carpeta actual, produce salida y termina con un estado de éxito o error. Estos tres elementos explican la mayoría de los primeros problemas.
Antes de volver a instalarlo todo, comprueba dónde estás, qué archivos ves y qué versión se encuentra. Un diagnóstico ordenado cambia una variable cada vez y repite la comprobación que antes fallaba.
- Comprueba la carpeta actual.
- Lista los archivos.
- Verifica el comando y la versión.
- Ejecuta el caso mínimo.
- Lee el primer error útil.
En la carpeta de Task Notes ejecutas `python app.py`, pero la shell responde `command not found: python`.
- No tocas `app.py`: el error indica que la shell no ha encontrado el programa llamado `python`, así que el archivo no se ha ejecutado.
- Compruebas `command -v python3` para ver qué programa se iniciaría, y luego `python3 --version`; ahora conoces tanto la ruta como la versión del runtime.
- Verificas `pwd` y `ls` para asegurarte de que `app.py` está en la carpeta actual, y luego ejecutas `python3 app.py`.
- Anotas el comando y la salida correcta como baseline. Si el programa ahora falla con un traceback, ese es un nuevo nivel del problema y debe leerse por separado.
Resultado: Has corregido la causa más externa sin reinstalar paquetes ni cambiar código. La baseline distingue el entorno que funciona de los problemas de la aplicación.
Credenciales y variables de entorno
Una clave API permite a un programa actuar y consumir recursos en tu nombre. Trátala como una contraseña operativa: no debe convertirse en parte del código, del historial de Git ni de una captura de pantalla compartida.
Una clave API es un secreto, no una preferencia. No debe introducirse en el código, en prompts compartidos ni en commits. La shell puede entregársela al proceso mediante una variable de entorno; un gestor de secretos es más adecuado en entornos compartidos.
Un archivo local con secretos debe excluirse del control de versiones. Antes de mostrar logs o capturas, comprueba que no contengan tokens completos. Si una clave queda expuesta, borrarla del archivo no basta: debe revocarse y sustituirse.
En `client.py` encuentras `api_key = "<CLAVE_DE_PRUEBA>"`. El repositorio es local, pero podría compartirse más adelante.
- Interrumpes el uso de la clave y compruebas si el archivo ya se ha committeado o enviado a otro sitio; esa información determina si hace falta una revocación inmediata.
- Modificas el código para que lea `os.environ["ANTHROPIC_API_KEY"]` y produzca un error claro cuando falte la variable, sin imprimir el valor.
- Configuras el secreto en el entorno local o en el gestor previsto y añades solo un archivo de ejemplo con un valor vacío.
- Ejecutas una búsqueda en el repositorio y revisas los diff y logs pertinentes para asegurarte de que no queda ningún token completo en artefactos compartibles.
Resultado: El programa sigue recibiendo la credencial, pero el secreto ya no vive en el código fuente. Si ya estaba expuesto, la rotación cierra también la credencial anterior.
El primer ciclo ejecución-error-corrección
El primer error no es un suspenso: es la primera observación fiable sobre el sistema. Si conservas el comando y cambias una causa cada vez, el ciclo error-corrección se vuelve legible incluso sin gran experiencia de programación.
Un programa pequeño permite separar el entorno del problema de la aplicación. Créalo, ejecútalo sin agente, observa la salida y solo después pide un cambio. Así sabrás si el error pertenece a la configuración o al código.
Cuando aparece un traceback, lee desde abajo: el tipo de error y el mensaje indican el síntoma, las líneas superiores reconstruyen el recorrido. Corrige una causa cada vez y vuelve a ejecutar el mismo comando.
El script imprime `task["prioridad"]`, pero la tarea creada solo contiene `titulo` y `completada`. Python termina con `KeyError: 'prioridad'`.
- Lees la última línea del traceback: `KeyError` significa que el diccionario, un registro formado por pares clave-valor, no posee la clave solicitada. Python ha arrancado: no hace falta reinstalarlo.
- Subes hasta la primera línea de tu archivo indicada en el traceback y comparas la lectura `task["prioridad"]` con el objeto realmente creado.
- Decides el comportamiento esperado: para las tareas antiguas la prioridad debe ser `normal`; por tanto usas `task.get("prioridad", "normal")` y añades un caso explícito.
- Vuelves a ejecutar exactamente el mismo comando y luego un segundo caso con prioridad presente, verificando tanto la compatibilidad como el nuevo valor.
Resultado: El programa no se limita a evitar el error: tiene un comportamiento definido para datos antiguos y nuevos, sostenido por dos casos observables.
Primer script de Task Notes
Partimos de un archivo autónomo que crea una sola actividad.
def crear_tarea(titulo):
return {"titulo": titulo, "completada": False}
print(crear_tarea("Probar el parser"))