Lesson 01 — Rules before code

Starter prompt

Pegalo en tu coding agent (Claude Code, Cursor, Codex…) o usá academy lesson prompt 1 --copy.

Rol: consultor que me ayuda a definir un workshop de deep agents.

Inspeccioná los siguientes archivos y luego interrogame como si fuese tu cliente:
- data/acme/README.md
- data/acme/customers.md
- data/acme/invoices-q1.md
- .skills/README.md
- VISION.md (template incompleto)
- AGENTS.md

Meta: al final tenemos VISION.md completo con:
1) 3-5 preguntas de negocio concretas que el agente debe responder al final del taller.
2) Definición de "listo" en una oración.
3) 1 approval gate adicional (además de los ya listados en AGENTS.md).

Reglas del interrogatorio:
- Una pregunta a la vez.
- Referí evidencia del dataset (nombres de clientes, montos, trimestres).
- Cuando yo apruebe una decisión, escribila directo en VISION.md.
- No toques src/ ni pyproject.toml.

Duración: 14 min · Prereq: ./scripts/check.sh verde en el repo recién clonado.

Challenge

Antes de que el DeepAgent exista, negocia las reglas del juego: qué preguntas de negocio va a resolver, qué puede tocar, qué gates lo detienen. Sin esto, cualquier autonomía es peligrosa.

Producto de la lección: VISION.md y AGENTS.md acordados y explícitos.

Manual path (si prefiere escribirlo a mano)

Edite VISION.md y reemplace los TODO(Lesson-01). Sugerencia mínima:

## Preguntas de negocio target
1. ¿Cuánto facturó Café del Valle en Q3?
2. ¿Qué cliente creció más entre Q2 y Q3?
3. ¿Qué cliente bajó su facturación de Q2 a Q3 y por qué?

## Approval gates
- El agente pide OK humano antes de sobreescribir un SKILL.md existente.

## Definición de "listo"
El agente responde 2 preguntas del listado con evidencia (fuente + monto) y el JSONL de lifecycle muestra `raw → learning → answering`.

Discuss abierta con la sala · 3 min

Definición de "listo" — ¿outcome o process?

Antes de escribir la definición de "listo" en su VISION.md, paramos y discutimos con la sala. La decisión define qué evidencia espera ver al final de Lesson 05 — y no es obvia.

La pregunta: ¿cómo sabe que su agente "funciona" al terminar el taller?

(a) Outcome-based · resultado correcto

El agente responde N de 3 preguntas con evidencia verificable — un valor que matchea data/acme/.

Ejemplos concretos (N=2):

Pregunta: "¿qué cliente creció más entre Q2 y Q3?"
Respuesta ✅: "Andes Tecnología creció +49.9M COP (Q2: 111.9M → Q3: 161.8M)"
Fuente citada: invoices-q2.md + invoices-q3.md
Verificación: grep "49" en el output del agente.

Pregunta: "¿top-3 clientes por facturación acumulada?"
Respuesta ✅: "1) Andes (347.5M) 2) Frutas Caribe (217.5M) 3) Textiles Medellín (178.1M)"
Verificación: grep "347" && grep "217" && grep "178".

Cuándo elegirlo: quiere poder decirle a un CFO/PM "sí, mi agente respondió esto y estos son los números que usted verifica".

(b) Process-based · el agente aprendió a aprender

El agente escribe N de 3 skills válidos (validan contra SkillManifest) e invoca cada uno al menos una vez. La respuesta final puede ser imperfecta.

Ejemplos concretos (N=3):

$ ls .skills/*/SKILL.md
.skills/compare_periods/SKILL.md      ← escrito por skill_author
.skills/rank_customers/SKILL.md       ← escrito por skill_author
.skills/map_services_to_revenue/SKILL.md ← escrito por skill_author

$ academy skills
Skills discovered                       ← los 3 pasan validación Pydantic

$ tail .receipts/lifecycle.jsonl
{"event":"skill_created","payload":{"name":"compare_periods"}}
{"event":"skill_created","payload":{"name":"rank_customers"}}
{"event":"skill_created","payload":{"name":"map_services_to_revenue"}}

Cuándo elegirlo: le importa demostrar la capacidad de aprendizaje autónomo, aunque el LLM invente un monto en la respuesta final. Es el bar más honesto para un workshop de 90 min — el retrieval/LLM tuning es otro taller.

(c) Mix · resultado + capacidad

Combinación explícita. Ejemplo concreto:

"El agente:
 - Escribe 3/3 skills válidos (compare_periods, rank_customers,
   map_services_to_revenue), y
 - Invoca cada uno al menos una vez, y
 - Al menos 1/3 respuestas tiene el monto correcto verificable
   contra data/acme/."

Esto acepta que el LLM puede alucinar montos (proceso robusto) pero al menos una respuesta tiene que ser correcta (outcome anclado). Es la más pragmática para producción.

Trade-offs

Observe

• git diff VISION.md muestra decisiones concretas, no plantilla.
• AGENTS.md no cambió (todavía) — sus reglas base ya son buenas para arrancar.

Discuss · por qué reglas antes que código

Regla: si el agente arranca sin restricciones, las inventa mal.

Un LLM sin boundaries explícitos va a improvisar qué es "responder bien", qué archivos puede tocar, cuándo pedir aprobación. Va a decidir esas cosas cada vez que se lanza — y esas decisiones se derivan del prompt del momento, no de su intención estable.

Su VISION.md es el contrato. Lo va a inyectar literalmente en el system prompt del DeepAgent en la Lesson 03. Si es vago, el agente será vago. Si es específico (nombres de clientes, montos, gates), el agente será específico.

Es el mismo principio que en cualquier producto SaaS: se define el contrato antes de escribir el endpoint. Aquí el "endpoint" es un LLM, pero la lógica es idéntica.

Fade

En la próxima lección ya no le acompaño con "defina qué quiere". Asumo que sabe qué respuestas espera y que el agente respetará las boundaries que acaba de escribir.

Rol: implementador rápido, Lesson 01.
Lea workshop/deepagents-memory-skills/lessons/01-rules-before-code.md
y aplique la sección "Manual path" a VISION.md, reemplazando todos los
TODO(Lesson-01). Corra `academy validate 1`. Confirme exit code 0.
No agregue features. No re-diseñe.

Siguiente → Lesson 02 — Reliability floor

Validation prompt

Bash puro. Corré academy validate 1 para ejecutarlo, o pegalo en tu shell.

# 1) VISION.md ya no tiene TODOs
! grep -q "TODO(Lesson-01)" VISION.md && echo "✅ VISION.md completo"

# 2) La rig sigue verde
./scripts/check.sh

Checkpoint

Marcá cada item cuando tengas evidencia. Se persiste en tu navegador (localStorage). No avanzás a la próxima lección hasta que estén todos verdes.