La teoría es barata. Aquí va un ticket real que entregué la semana pasada con Claude Code, exactamente como pasó — qué le pedí, qué hizo el agente, qué pillé, qué dejé que enviara.

Estoy usando las técnicas de los artículos 3-7 (prompts en cuatro partes, sub-agentes, slash commands, pipeline lineal). Sin magia, sin salsa secreta.

El ticket

Título: Añadir rate limiting por usuario a los endpoints /api/notes/*
Aceptación:
- 60 req/min/usuario, ventana deslizante
- 429 con header Retry-After al desbordar
- Bypass para usuarios con `internal: true`
- Los tests existentes deben seguir verdes
- Añadir cobertura para la nueva lógica

Una feature pequeña de manual: objetivo claro, restricciones claras, testeable. El tipo de ticket que Claude Code se desayuna.

Paso 1 — Encuadrar el prompt con /feature

> /feature
> Objetivo: Añadir rate limiting con ventana deslizante por usuario en /api/notes/*.
>   60 req/min/usuario, respuesta 429 + header Retry-After al desbordar.
>   Bypass cuando user.internal === true.
>
> Restricciones:
>   - Reusar el cliente redis existente en lib/redis.ts.
>   - NO añadir nueva dependencia.
>   - Implementar como middleware Next.js en middleware.ts (path-scoped).
>   - NO tocar los tests existentes.
>
> Definition of Done:
>   - pnpm test pasa.
>   - Nuevo vitest cubre: bajo límite, sobre límite 429, bypass internal.
>   - pnpm lint limpio.
>
> Archivos:
>   - middleware.ts (punto de entrada)
>   - lib/redis.ts (cliente existente)
>   - lib/rate-limit.ts (NUEVO)
>   - tests/rate-limit.test.ts (NUEVO)

Fíjate en las cuatro partes: Objetivo, Restricciones, DoD, Contexto. El artículo 3 no bromeaba.

Paso 2 — El implementer toma el mando

Cambié a mi sub-agente implementer y lo dejé correr. Esto es, más o menos, lo que hizo, narrado:

1. cat middleware.ts, cat lib/redis.ts — montó contexto.
2. Esbozó lib/rate-limit.ts con ventana deslizante usando Redis sorted sets.
3. Escribió middleware.ts para llamar al limiter en /api/notes/* y respetar el flag internal.
4. Escribió tests/rate-limit.test.ts con los tres casos de la DoD.
5. Corrió pnpm test. Un test falló — el 429 no incluía Retry-After.
6. Releyó su propio código, encontró el header faltante, arregló, reejecutó. Verde.
7. Corrió pnpm lint. Limpio.
8. Emitió un handoff estructurado: status: ok, artifacts: [...].

Wall clock: ~6 minutos. Tokens: ~14k. Mi intervención: cero hasta aquí.

Paso 3 — code-reviewer segundo par de ojos

> /agents code-reviewer
> Revisa el diff.

Veredicto del reviewer (parafraseado):

SHIP, con dos notas:

1. Casi-bug: la ventana deslizante usa Date.now() dentro del ZADD de Redis.
   En despliegue multi-región con drift de reloj puede causar evicciones por
   uno. Recomienda usar ZADD con redis TIME en su lugar.

2. Estilo: rate-limit.ts exporta una clase pero se usa como función en otros
   sitios. Recomienda exportar una factory function por consistencia con
   lib/cache.ts.

Ninguno bloquea el ticket, pero merecen seguimiento.

Esto es exactamente el valor de un agente reviewer separado. El código del implementer funcionaba; el reviewer marcó dos preocupaciones reales que el implementer nunca señalaría sobre su propio trabajo.

Tomé una decisión rápida: enviar la feature, abrir tickets de seguimiento para ambas notas. Esa es una decisión humana, no del agente.

Paso 4 — Revisión del diff por mí (el humano)

Abrí el diff. ~180 líneas en 3 archivos. Lo leí de arriba abajo.

Lo que pillé que no vio ningún agente:

• El nuevo lib/rate-limit.ts tenía un comentario que decía // rate limit logic. Lo borré (anti-patrón del artículo 3: no narres el código).
• Los imports del test no estaban ordenados. Pequeño hueco de config de lint mío, no del agente.

Así es la review en este workflow: 5 minutos de lectura, 2 micro-ediciones, enviar.

Paso 5 — Notas de release + descripción del PR

> /agents release-bot
> Redacta una descripción de PR y entrada de CHANGELOG.

Salida (ligeramente editada):

## Añadir rate limiting por usuario en /api/notes/*

- Ventana deslizante, 60 req/min/usuario, soporte Redis.
- 429 con header `Retry-After`.
- Bypass para `user.internal === true`.

Closes ENG-2451.

Lo copié en gh pr create y empujé. Wall clock total para el ticket: unos 22 minutos. De ellos, ~6 fue el agente, ~5 fue el reviewer, ~7 mi review del diff, ~4 PR + push.

Cómo se vería este workflow hace un año, a mano

Para mí, este mismo ticket habría sido un trabajo de 90 minutos:

• 20 min leyendo código existente.
• 30 min implementando.
• 20 min en el test (sobre todo mockeando el sorted set de Redis).
• 10 min en lint / cleanup.
• 10 min en la descripción de PR.

22 min vs 90 min es la cifra titular. Pero el desbloqueo más honesto es la reducción de carga cognitiva. No estuve en concentración profunda durante 22 minutos; estuve activamente revisando durante 12 de ellos, y esperando / pensando en el siguiente ticket el resto.

Lo que NO delegué

• La decisión de qué primitiva de Redis usar (sorted set vs contador con TTL). Se la dije al agente.
• La decisión de la semántica del bypass (internal: true vs un nuevo rol). Decidida en el prompt.
• El push al remoto. Siempre humano.

Esa es la división correcta del trabajo. El agente posee la implementación. Yo poseo el diseño y las acciones irreversibles.

Un patrón para robar

Para todo ticket de "feature pequeña":

1. Dedica 5 minutos a escribir un prompt en cuatro partes. Literalmente escríbelo.
2. implementer corre hasta tests verdes.
3. code-reviewer corre, lee el diff, anota riesgos.
4. Tú lees el diff. 5 minutos.
5. release-bot redacta la descripción de PR.
6. Tú empujas.

Hazlo 10 veces en una semana. El viernes será el workflow más natural que hayas tenido nunca.

---

Próximo artículo: Tests y depuración — cómo dejar que Claude Code dueñe todo el bucle de tests, incluidas las partes que ponen nerviosos a los ingenieros (regresiones, flakies, integración).