Phase 14 - Lesson 42

Proyecto Final: Entregar un Paquete Reutilizable de Workbench de Agente

La minitrayectoria termina con un paquete que se introduce en cualquier repositorio. Once lecciones de superficies comprimidas en un directorio que puedes copiar con cp -r y tener un agente funcionando de manera confiable a la mañana siguiente. El proyecto final es el artefacto en el que se basa este plan de estudios.

Tipo: Construcción Lenguajes: Python (stdlib) Prerrequisitos: Fases 14 · 31 a 14 · 41 Tiempo: ~75 minutos

Objetivos de Aprendizaje

  • Empaquetar las siete superficies de workbench en un único directorio listo para usar.
  • Fijar los esquemas, scripts y plantillas para que un nuevo repositorio obtenga una línea de base conocida y funcional.
  • Agregar un único script instalador que configure el paquete de manera idempotente.
  • Decidir qué se queda en el paquete y qué se queda fuera, defendiendo la exclusión o inclusión de cada uno.

El Problema

Un workbench que vive en un Google Doc, un historial de chat y tres scripts recordados a medias es un workbench que se reconstruye cada trimestre. La cura es un paquete versionado: un repositorio o directorio con las superficies, los esquemas, los scripts y un instalador de comando único.

Terminarás esta lección con outputs/agent-workbench-pack/ guardado en el disco y un bin/install.sh que lo instala en cualquier repositorio de destino.

El Concepto

flowchart TD
  Pack[agent-workbench-pack/] --> Docs[AGENTS.md + docs/]
  Pack --> Schemas[schemas/]
  Pack --> Scripts[scripts/]
  Pack --> Bin[bin/install.sh]
  Bin --> Repo[repositorio de destino]
  Repo --> Surfaces[las siete superficies de workbench conectadas]

La estructura del paquete

outputs/agent-workbench-pack/
├── AGENTS.md
├── docs/
│   ├── agent-rules.md
│   ├── reliability-policy.md
│   ├── handoff-protocol.md
│   └── reviewer-rubric.md
├── schemas/
│   ├── agent_state.schema.json
│   ├── task_board.schema.json
│   └── scope_contract.schema.json
├── scripts/
│   ├── init_agent.py
│   ├── run_with_feedback.py
│   ├── verify_agent.py
│   └── generate_handoff.py
├── bin/
│   └── install.sh
└── README.md

Qué se queda dentro, qué se queda fuera

Dentro:

  • Esquemas de las superficies. Son el contrato.
  • Los cuatro scripts anteriores. Son el entorno de ejecución.
  • Los cuatro documentos. Son las reglas y la rúbrica.

Fuera:

  • Tareas específicas del proyecto. Las tareas pertenecen al tablero del repositorio de destino, no al paquete.
  • Llamadas a SDK de proveedores. El paquete es agnóstico con respecto a los frameworks.
  • Prosa de integración (onboarding). El paquete vive junto a la integración existente del equipo, no dentro de ella.

El instalador

Un breve bin/install.sh (o bin/install.py):

  1. Se niega a instalar sobre un paquete existente sin --force.
  2. Copia el paquete en el repositorio de destino.
  3. Conecta CI si existe un directorio .github/workflows/.
  4. Muestra los siguientes pasos: completar el tablero, establecer comandos de aceptación, ejecutar el script de inicialización.

Versionado

El paquete incluye un archivo VERSION. Los cambios de esquema y de script que requieren migraciones incrementan la versión mayor (major). Los cambios que solo afectan a la documentación incrementan la versión de corrección (patch). El archivo agent_state.json del repositorio de destino registra con qué versión del paquete fue inicializado.

Constrúyelo

code/main.py ensambla el paquete en outputs/agent-workbench-pack/ al lado de la lección, alimentado con los esquemas y scripts de las lecciones anteriores en esta minitrayectoria y los documentos que ya escribiste.

Ejecútalo:

python3 code/main.py

El script copia y fija las superficies, escribe el README, imprime el árbol del paquete y finaliza correctamente (exit zero). Volver a ejecutarlo es idempotente.

Patrones de producción en el mundo real

Un paquete solo es valioso si sobrevive a bifurcaciones (forks), actualizaciones y a cambios inesperados en el repositorio de origen (upstream hostil). Cuatro patrones hacen que eso funcione.

VERSION es el contrato, no el marketing. Los cambios de versión mayor (major bumps) requieren una migración de estado. Los cambios de versión menor (minor bumps) requieren volver a ejecutar el verificador. Los cambios de versión de corrección (patch bumps) son solo para la documentación. El instalador escribe .workbench-version en el repositorio de destino en cada instalación; lint_pack.py se niega a realizar el envío si el archivo de bloqueo (lock) del destino no coincide con el VERSION del paquete. Así es como npm, Cargo y pyproject.toml sobreviven a 10 años de cambios continuos; nada en los agentes cambia las reglas.

Fuente única para distribución entre herramientas. Nx distribuye un comando nx ai-setup que configura AGENTS.md, CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md y un servidor MCP a partir de una única configuración. El paquete debería hacer lo mismo; el instalador crea los enlaces simbólicos (ln -s AGENTS.md CLAUDE.md) para que una única fuente de verdad se extienda a todos los agentes de programación. Bifurcar el paquete para dar soporte a una herramienta sobre otra es un patrón de falla.

uninstall.sh que se niega en caso de estado no trivial. Desinstalar el paquete no debe eliminar los archivos agent_state.json, task_board.json o outputs/ del usuario. El desinstalador elimina los esquemas, scripts, documentos y AGENTS.md (con la opción de exclusión --keep-agents-md) y se niega a continuar si los archivos de estado tienen cambios sin confirmar (uncommitted). El estado pertenece al usuario; el paquete no es su dueño.

Habilidad como publicable. Distribución al estilo SkillKit. El paquete se distribuye como una habilidad de SkillKit: skillkit install agent-workbench-pack lo configura en 32 agentes de IA a partir de una única fuente. El repositorio del paquete es la fuente de verdad; SkillKit es el canal de distribución. El bloqueo de proveedor (vendor lock-in) colapsa; las siete superficies se mantienen iguales.

Úsalo

Tres lugares donde se distribuye el paquete:

  • Como un directorio que se introduce en un repositorio. cp -r outputs/agent-workbench-pack /path/to/repo.
  • Como un repositorio de plantilla pública. Haz un fork y personalízalo, con VERSION controlando los desvíos.
  • Como una habilidad de SkillKit. Integrado en el producto de tu agente de modo que un solo comando lo configure.

El paquete es la receta. Cada instalación es una porción.

Envíalo

outputs/skill-workbench-pack.md genera un paquete ajustado al proyecto: reglas adaptadas al historial del equipo, globs de alcance que coinciden con el repositorio y dimensiones de la rúbrica extendidas con una entrada específica del dominio.

Ejercicios

  1. Decide qué quinto documento opcional merece ser promovido al paquete canónico. Defiende tu elección.
  2. Reescribe el instalador en Python con una bandera --dry-run. Compara su ergonomía frente a bash.
  3. Agrega un bin/uninstall.sh que elimine el paquete de forma segura y se niegue a hacerlo si los archivos de estado tienen un historial no trivial. ¿Qué se considera no trivial?
  4. Agrega un lint_pack.py que falle cuando el paquete se desvíe de VERSION. Conéctalo al CI del propio repositorio del paquete.
  5. Redacta la guía de migración (runbook) de un workbench artesanal a este paquete. ¿Cuál es el orden de operaciones que minimiza el tiempo de inactividad?

Términos Clave

Término Lo que la gente dice Lo que realmente significa
Workbench pack "El kit de inicio" Un directorio versionado que contiene las siete superficies
Instalador "Script de configuración" bin/install.sh que configura el paquete de manera idempotente
Versión del paquete "VERSION" Versiones mayores para cambios de esquema/script, de corrección para solo docs
Paquete drop-in "cp -r y listo" El paquete funciona sin personalización por repositorio desde el primer día
Plantilla bifurcable "Plantilla de GitHub" Repositorio público del cual se puede clonar mediante la opción "Usar esta plantilla" de GitHub

Lectura Adicional

0 lifetime access. Curriculum based on AI Engineering from Scratch by Rohit Ghumare (MIT, used under attribution).