Práctica integrada: agregar funcionalidad a una herramienta TODO desde cero y realizar una confirmación
📚 Navegación de la serie: El artículo anterior 〔33 Pautas de uso en Windows〕 detalló la resolución de errores comunes relativos a rutas, saltos de línea y políticas de seguridad del sandbox en este sistema operativo. En esta sección no explicaremos nuevas características, sino que realizaremos un ejercicio más práctico: conectar todos los componentes aprendidos en los artículos anteriores para consolidar el flujo de trabajo de desarrollo. El siguiente artículo 〔35 Hojas de referencia de comandos y configuraciones〕 reunirá los comandos y propiedades de configuración en una tabla de consulta rápida.
Amigos, hoy realizaremos un ejercicio práctico para construir una pequeña utilidad desde cero.
Contamos con una utilidad de consola simple escrita en Python: un archivo todo.py que permite añadir y listar tareas pendientes. Sin embargo, tiene una limitación obvia: las tareas completadas no pueden eliminarse, lo que provoca que la lista crezca indefinidamente. En esta sección desarrollaremos la funcionalidad de "eliminar tareas", cubriendo desde la definición del contexto y las pautas del prompt, pasando por la asignación de permisos del sandbox, hasta la validación de pruebas y la confirmación final en Git.
En esta sección analizaremos cómo integrar y estructurar la secuencia de pasos de desarrollo de forma coordinada en un proyecto real.
Recomiendo seguir el ejercicio en su sistema de desarrollo. En la sección 01 crearemos el archivo base todo.py en dos minutos, permitiéndole ejecutar las pruebas y comprobar los resultados. Le sugerimos realizar las modificaciones indicadas de forma activa en su terminal para asimilar el flujo de trabajo de desarrollo.
Al terminar de leer este artículo, obtendrás:
- Un flujo de desarrollo completo desde la inicialización hasta la confirmación de cambios, asimilando la secuencia lógica de pasos de programación asistida.
- Plantillas de configuración para el archivo
AGENTS.md, prompts estructurados bajo la regla de las cuatro secciones y comandos de validación reales. - El procedimiento para requerir al agente ejecutar y validar las pruebas de forma autónoma antes de entregar el resultado.
- Cómo delegar el análisis de diferencias (diff) y la redacción del mensaje de commit en Codex, manteniendo usted el control sobre la confirmación final en Git.
- Una tabla de referencia del flujo de desarrollo completo para aplicar en futuros proyectos de software.
⚠️ Los comandos, parámetros y comportamientos predeterminados se contrastan con la documentación oficial de Codex. Las versiones y nombres de los modelos son ilustrativos y pueden variar con el tiempo.
01 Crear el archivo base: todo.py
Antes de iniciar con Codex, estructuraremos los archivos del proyecto para realizar las pruebas.
Analogía: Disponer de la estructura base de la casa antes de la remodelación. Sin los cimientos y paredes base, no es posible aplicar cambios de diseño. El archivo todo.py constituye nuestra estructura de pruebas, con un alcance acotado y legible que expone las funciones de almacenamiento, consulta y entrada de comandos, listo para agregar la nueva funcionalidad de eliminación.
Cree un directorio de pruebas en su terminal y guarde el archivo todo.py con el siguiente código (compatible con Python 3 en sistemas Mac, Linux y Windows):
# todo.py
import sys
TODOS = []
def add(item):
TODOS.append(item)
print(f"已添加：{item}")
def list_todos():
if not TODOS:
print("（暂无待办）")
return
for i, item in enumerate(TODOS, 1):
print(f"{i}. {item}")
def main():
if len(sys.argv) < 2:
print("用法：python todo.py [add <内容> | list]")
return
cmd = sys.argv[1]
if cmd == "add":
add(" ".join(sys.argv[2:]))
elif cmd == "list":
list_todos()
else:
print(f"未知命令：{cmd}")
if __name__ == "__main__":
main()Una vez guardado, compruebe que se ejecuta correctamente desde su consola:
python todo.py add Buy coffee beans
python todo.py listResultado esperado:
已添加：Buy coffee beans
（暂无待办）Tenga en cuenta que al ejecutarse en memoria y finalizar el proceso, la lista TODOS se inicializa vacía en cada ejecución. Este es el comportamiento esperado para este ejercicio; considere esta condición al verificar los cambios en la sección 05.
Inicialice el repositorio Git y confirme los archivos base:
git init
git add todo.py
git commit -m "init: initial version of TODO utility"Resultado esperado: Git confirma la creación del commit inicial. Con el repositorio preparado, iniciaremos el desarrollo asistido.
💡 Resumen en una frase: Estructure el archivo de pruebas
todo.pyy agréguelo al control de versiones Git para establecer el punto de partida del ejercicio de desarrollo.
02 Definir el archivo de reglas AGENTS.md
Cuando Codex accede a un repositorio por primera vez, no dispone de contexto sobre las librerías del proyecto, comandos de arranque o restricciones de codificación. El paso inicial consiste en proveerle el archivo de reglas locales del proyecto. Como explicamos en el artículo [11], esto se gestiona mediante AGENTS.md.
Analogía: Entregar un manual de normas a un técnico externo antes de iniciar la obra. Aunque el técnico sea calificado, requiere conocer la ubicación de las instalaciones, qué áreas no alterar y qué normativas respetar en el edificio. AGENTS.md representa este manual de normas, el cual Codex consulta al iniciar su análisis.
Cree el archivo AGENTS.md en el directorio raíz del proyecto con la siguiente estructura limpia y acotada:
# TODO Utility
A simple command-line TODO utility written in Python 3 standard library with no external dependencies.
Una utilidad de consola simple para tareas pendientes en Python 3, sin dependencias externas.
## Execution / Ejecución
- Add / Añadir: `python todo.py add <content>`
- List / Listar: `python todo.py list`
## Rules / Reglas
- Use only the standard library; do not import external packages.
- Utilizar únicamente la librería estándar; no importar dependencias externas.
- Maintain the existing command-line style (`python todo.py <command> <args>`).
- Mantener el estilo de comandos existente (`python todo.py <comando> <argumentos>`).
- Verify changes using the defined test suite before completing.
- Validar las modificaciones con las pruebas antes de entregar los resultados.
## Testing / Pruebas
- Use the standard `unittest` library. If the file `test_todo.py` does not exist, create it.
- Utilizar la librería estándar `unittest`. Si no existe, crear el archivo `test_todo.py`.
- Run tests / Ejecutar pruebas: `python -m unittest`Evite saturar el archivo de reglas con descripciones extensas que no aporten valor técnico al agente (como la historia de la empresa o planes de negocio), manteniendo las instrucciones precisas para optimizar la ventana de contexto de Codex.
💡 Resumen en una frase: Escriba un archivo
AGENTS.mdclaro y conciso que describa la tecnología del proyecto, las convenciones de estilo de código y la forma de ejecutar las pruebas unitarias.
03 Estructurar la instrucción del prompt de desarrollo
Con las reglas locales configuradas, envíe la solicitud de desarrollo. La precisión de la respuesta de Codex dependerá del nivel de detalle provisto en el prompt, estructurándolo bajo el formato de Objetivo, Contexto, Restricciones y Criterios de Aceptación descrito en el artículo [13].
Analogía: Redactar las especificaciones técnicas en una orden de trabajo. Si solicita únicamente "repara la pared", el resultado puede no coincidir con las expectativas de materiales o acabados. Al detallar las dimensiones, la pintura a utilizar, los límites de la estructura y cómo validar que la superficie está nivelada, el entregable se ajustará al diseño técnico requerido.
Inicie la sesión de Codex en su terminal:
codexEnvíe el siguiente prompt estructurado (puede copiar y pegar el texto en el chat):
Add a "delete todo" feature to todo.py.
Agrega la funcionalidad de "eliminar tarea" en todo.py.
Goal: Support the command `python todo.py done <index>`, deleting the corresponding todo item using the 1-based index shown in the list command.
Objetivo: Soportar el comando `python todo.py done <index>`, eliminando la tarea según el índice base 1 mostrado al listar las tareas.
Scope: Modify only todo.py, and add/update test cases in a test file. Do not alter the command-line style or add external dependencies.
Alcance: Modificar únicamente todo.py, y añadir/actualizar casos de prueba en el archivo de test; no alterar el estilo de comandos ni agregar dependencias.
Constraints: The index is 1-based. If the index is out of bounds or not a number, print a user-friendly error message instead of crashing.
Restricciones: El índice es base 1. Si el índice se encuentra fuera de rango o no es numérico, imprimir un mensaje de error descriptivo en lugar de fallar catastróficamente.
Done when: Unittest coverages include "successful delete", "out of bounds", and "non-numeric input", and `python -m unittest` passes with all tests green.
Criterios de Aceptación: Las pruebas unitarias con unittest cubren los casos de "eliminación exitosa", "índice fuera de rango" e "entrada no numérica", y se aprueban todos los test de `python -m unittest`.Comparación de prompts:
| Prompt ambiguo (Ineficaz) | Prompt estructurado (Recomendado) |
|---|---|
| Agrega la opción de eliminar | Define la sintaxis del comando: done <index> |
| Sin delimitar el alcance | Restringe los cambios a todo.py y las pruebas locales |
| Sin prever fallos de validación | Detalla el comportamiento ante índices incorrectos o caracteres |
| Sin criterios de prueba | Especifica los casos de prueba unitaria y el runner a ejecutar |
Definir los criterios de aceptación en el prompt actúa como un control de calidad automático que instruye al modelo sobre qué escenarios debe validar de forma obligatoria en su código antes de proponer la entrega.
💡 Resumen en una frase: Envíe la solicitud estructurando el Objetivo, Alcance, Restricciones y Criterios de Aceptación, garantizando que Codex desarrolle las pruebas unitarias y controle los errores de validación del índice.
04 Configuración de permisos del Sandbox
Antes de procesar la solicitud, determine el alcance de los permisos de escritura de archivos que concederá al agente (los conceptos analizados en el artículo [15]).
Analogía: Configurar los accesos de la credencial de seguridad del personal. Si restringe el acceso en exceso, el desarrollador no podrá modificar los archivos del proyecto sin solicitar autorización en cada paso, demorando el flujo. Si otorga accesos de administrador globales al sistema, expone archivos externos a modificaciones no deseadas.
Para este ejercicio, el sandbox estándar recomendado es workspace-write con aprobación de comandos en modo on-request (el agente puede modificar los archivos locales del repositorio de forma autónoma, solicitando confirmación si intenta ejecutar llamadas al sistema externo o red).
Inicie el CLI declarando los parámetros de seguridad en la consola:
codex --sandbox workspace-write --ask-for-approval on-requestO configure los valores por defecto en su archivo global de preferencias ~/.codex/config.toml:
# Archivo: ~/.codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"Límites por defecto del sandbox workspace-write:
- La conexión a red externa está bloqueada por defecto.
- La carpeta del historial de versiones Git
.gitestá protegida contra modificaciones directas. - La escritura de archivos está acotada estrictamente a la ruta del directorio de trabajo activo.
Evite configurar el sandbox en modo danger-full-access por defecto en su sistema, reservando esta opción únicamente para entornos aislados o de pruebas en contenedores.
💡 Resumen en una frase: Configure los privilegios de la sesión en
workspace-writecon aprobaciónon-requestpara permitir a Codex crear y modificar los archivos de código y pruebas del proyecto de forma segura.
05 Delegar la validación y ejecución de pruebas unitarias
Una vez que Codex aplica las modificaciones en el código, el sistema debe validar de forma autónoma el cumplimiento de los criterios de aceptación.
Analogía: Requerir que el técnico compruebe el funcionamiento del equipo antes de retirarse de la obra. En lugar de evaluar visualmente cada línea de código en busca de posibles fallos de sintaxis, solicite la ejecución de las pruebas unitarias. Si las pruebas fallan, el agente debe depurar y corregir el código internamente hasta que el resultado sea exitoso.
Dado que hemos definido el runner de pruebas unitarias en AGENTS.md y en los criterios de aceptación del prompt, Codex creará el archivo de pruebas test_todo.py y ejecutará la suite de pruebas. El reporte de ejecución en la terminal se mostrará de la siguiente manera:
...
----------------------------------------------------------------------
Ran 3 tests in 0.003s
OKSi el agente no inicia la ejecución de pruebas de forma automática, envíe un mensaje complementario en el chat indicando:
Ejecuta la suite de pruebas mediante python -m unittest y comparte el reporte; corrige el código si se reportan fallos hasta que todos los test finalicen en verde.Como se analizó en la sección 01, la ejecución del comando list en una nueva sesión de consola no retendrá los cambios de las llamadas previas de add debido a que la lista de tareas TODOS opera en memoria y se limpia al cerrar el proceso. Por lo tanto, la validación de la lógica de eliminación debe evaluarse mediante pruebas unitarias estructuradas que ejecuten las funciones en una secuencia continua en el mismo proceso, confirmando la importancia de implementar flujos de pruebas unitarias en lugar de revisiones manuales en consola.
💡 Resumen en una frase: Delegue la validación del código solicitando la ejecución de
unittesthasta obtener un resultado exitoso (OK), asegurando la cobertura de los casos límite de inyección de índices definidos.
06 Uso de subagentes y herramientas MCP en el proyecto
Al evaluar la complejidad de este ejercicio, la funcionalidad de eliminación puede ser resuelta directamente por el agente principal, sin requerir subagentes o herramientas MCP externas. El alcance del desarrollo es acotado y se resuelve sobre un único archivo.
Criterios de escalabilidad en futuros desarrollos:
- Lógica distribuida y procesamiento por lotes: si requiere refactorizar múltiples archivos en el repositorio de forma paralela, delegue la tarea de análisis y cambios a subagentes equipados con el modelo ligero
gpt-5.4-mini(ver pautas del artículo [21]). - Integración con servicios y APIs de datos externas: si la lógica requiere validar si la tarea ha sido archivada consultando sistemas de incidencias externos como Linear o bases de datos remotas, configure la conexión mediante herramientas MCP (ver artículo [20]).
| Complejidad de la tarea | Arquitectura recomendada | Notas |
|---|---|---|
| Cambios simples en archivos acotados | Agente principal individual | Suficiente para la mayoría de requerimientos de edición |
| Edición y refactorización de múltiples directorios en paralelo | Delegación en Subagentes | Acelera la velocidad usando modelos ligeros para tareas secundarias |
| Consultas de bases de datos externas o integraciones | Integración con MCP servers | Expone datos de sistemas de red al contexto de Codex |
Evite incorporar componentes complejos en tareas simples de desarrollo para mantener limpio el flujo de trabajo.
💡 Resumen en una frase: Resuelva las tareas acotadas mediante el agente principal individual; delegando a subagentes o MCP únicamente si el alcance del proyecto requiere paralelismo o integraciones externas.
07 Confirmación de cambios en Git
Una vez validada la consistencia de las modificaciones en el código y aprobadas las pruebas unitarias, proceda a confirmar los cambios en el historial de Git del repositorio (los conceptos de integración del artículo [26]).
Analogía: Firmar la entrega final del proyecto. El asistente redacta los reportes de cambios y prepara la documentación técnica (Codex analiza las diferencias del código y redacta la propuesta de commit); el responsable técnico valida los entregables y aplica la firma definitiva para cerrar la transacción (el desarrollador aprueba y realiza la confirmación local).
Envíe la siguiente instrucción en el chat de la sesión:
Muestra el estado de git status y git diff de los cambios realizados. Redacta una propuesta de mensaje de commit en español con el prefijo "feat:" describiendo las modificaciones aplicadas y espérame a que apruebe la confirmación.Flujo de control para la confirmación de cambios:
- El agente lee el estado de
git statuspara listar los archivos creados o modificados. - Lee
git diffpara auditar las líneas de código añadidas o eliminadas. - Propone un mensaje de confirmación formateado según las convenciones del repositorio.
El acceso de escritura a la carpeta de versiones .git se encuentra protegido por el sandbox de solo lectura de metadatos de Git. De este modo, se aconseja al desarrollador leer la propuesta de mensaje provista por Codex y ejecutar el comando git commit directamente en su terminal de sistema, manteniendo el control sobre la integración final de los archivos.
Ejemplo de mensaje de commit sugerido por el modelo:
feat: agregar comando done para eliminar tareas por índice y tests de validación unitariosUna vez ejecutado el commit en su consola, compruebe el historial reciente del repositorio:
git log --oneline -1Resultado esperado:
[hash-id] feat: agregar comando done para eliminar tareas por índice y tests de validación unitariosMantener la confirmación de cambios Git como un paso supervisado por el desarrollador garantiza la consistencia del historial de versiones de su proyecto.
💡 Resumen en una frase: Delegue en Codex el análisis de las diferencias y la redacción del mensaje de commit, ejecutando la confirmación de cambios manualmente en su consola para validar los archivos incluidos en el historial.
08 Flujo de trabajo de desarrollo integrado
Al consolidar los pasos de este ejercicio práctico, la secuencia de desarrollo integrada para cualquier requerimiento de desarrollo se estructura de la siguiente manera:
| Fase de desarrollo | Propósito del paso | Recurso técnico asociado |
|---|---|---|
| 1. Estructura base | Disponer del código base bajo control de versiones Git | Inicialización de repositorio |
| 2. Pautas locales | Definir las tecnologías y comandos del proyecto | Archivo AGENTS.md (Art. 11) |
| 3. Delimitar permisos | Configurar las fronteras de escritura del agente | Parámetros del Sandbox (Art. 15) |
| 4. Instrucciones | Indicar el objetivo y criterios de éxito de la tarea | Prompt estructurado (Art. 13) |
| 5. Escalabilidad | Evaluar si requiere subprocesos o accesos de red | Subagentes y MCP (Art. 21 y 20) |
| 6. Validación | Ejecutar las pruebas unitarias hasta obtener éxito | Auto-validación en tests (Art. 13) |
| 7. Commit | Auditar las diferencias y confirmar los cambios | Integración con Git (Art. 26) |
Esta secuencia lógica organiza los conceptos analizados a lo largo de los artículos en un flujo de trabajo práctico aplicable al desarrollo de sus proyectos de software.
💡 Resumen en una frase: La programación asistida por IA se organiza en el ciclo: reglas de proyecto (AGENTS.md) → permisos del sandbox → prompt estructurado → validación automatizada de pruebas unitarias → auditoría de diferencias y commit manual; estructurando las habilidades aprendidas en una secuencia de desarrollo sólida.
Resumen
En esta práctica integrada hemos estructurado un flujo de desarrollo completo para incorporar una funcionalidad de eliminación a un proyecto TODO base:
- Contexto local: configuramos el archivo
AGENTS.mdpara guiar al modelo en la ejecución de las pruebas y convenciones del proyecto. - Prompt estructurado: definimos la orden de trabajo mediante las pautas de Objetivo, Alcance, Restricciones y Criterios de Aceptación para evitar interpretaciones ambiguas.
- Aislamiento seguro: aplicamos los límites de escritura del sandbox
workspace-writecon aprobación de comandoson-request. - Auto-validación: requerimos que el modelo ejecutara la suite de pruebas unitarias de forma autónoma hasta obtener un resultado favorable.
- Firma definitiva: auditamos las diferencias del código y aplicamos la confirmación de cambios en Git manualmente para garantizar la consistencia del repositorio.
Consolidar estas fases de desarrollo le permite implementar las capacidades de asistencia de Codex en sus proyectos de forma ordenada y bajo control de calidad técnico.
El siguiente artículo 35 · Hojas de referencia de comandos y configuraciones: proveerá un compendio de consulta rápida con todos los comandos de consola, variables de configuración de TOML y atajos de teclado de Codex para facilitar su uso diario.