iadevprogramar con IA · con método

Capítulo 06 de 10 · 10 min de lectura

El contexto del agente

Un agente empieza cada tarea sin recordar nada. Sabe lo que lee, y lo que lee lo decides tú en dos ficheros y un encargo.

Lo que no lee, no existe

Un agente de código no tiene memoria entre tareas. Cuando arranca, no sabe qué es el proyecto, qué se decidió ayer ni qué reglas sigue el equipo. Lo que sabe en cada momento es exactamente lo que ha leído desde que empezó, y eso cabe en un espacio limitado que se llama contexto.

Esto cambia dónde se guarda el conocimiento de un proyecto. Entre personas, mucho vive en la cabeza de alguien y se transmite preguntando. Con un agente, lo que no está en un fichero que vaya a leer no existe para él, y decidirá por su cuenta, como los once programas del capítulo 1.

Los capítulos anteriores han ido dejando reglas: la spec primero, preguntas antes que código, tests antes que implementación, el identificador en cada test. Este capítulo es sobre dónde viven esas reglas para que el agente las lea sin que nadie se acuerde de repetírselas.

Tres sitios

El contexto de un agente llega por tres caminos, y conviene saber cuál es cuál porque no pesan igual.

Lo que lee siempre. Al arrancar, las herramientas de agente leen por su cuenta un fichero de reglas en la raíz del proyecto. Casi todas leen AGENTS.md; Claude Code lee CLAUDE.md. Es el único sitio del que puedes estar seguro de que se lee en cada tarea, y por eso es donde van las reglas que tienen que cumplirse siempre. El CLAUDE.md de acorta no repite nada: apunta al otro.

Las reglas del proyecto están en @AGENTS.md y el contrato en `specs/`.

Lo que le dices en el encargo. Cada tarea lleva su propia información: qué leer, qué hacer, qué no tocar. Se escribe cada vez, y por eso no es sitio para reglas generales.

Lo que abre por su cuenta. El resto del repositorio. El agente lo lee si el encargo se lo pide o si decide que lo necesita. Las specs, el código vecino, un METODO.md: contexto a demanda. Vale para lo que solo hace falta a veces, y no vale para nada que tenga que pasar siempre, porque no controlas si lo abre.

Lo que cambia una línea

Para medir cuánto pesa cada sitio, repetimos el encargo de una línea del capítulo 1 con dos agentes y cuatro carpetas distintas, de la vacía a la plantilla entera. Monta aquí el AGENTS.md que quieras con las once reglas de la plantilla y mira qué pasó con esa combinación.

Combinaciones probadas
AGENTS.md 11 reglas · 372 palabras
# AGENTS.md — cómo se trabaja en este proyecto

Este proyecto se desarrolla con especificaciones (SDD) y tests primero (TDD). Estas reglas valen para cualquier agente de código y para cualquier persona. El método completo, con ejemplos, está en `METODO.md`.

1. **La spec es el contrato.** `specs/` dice qué hace el sistema. Léela antes de tocar código. Nada se implementa si no está especificado.
2. **Algo nuevo empieza por preguntas, no por código.** Ante un proyecto nuevo, una funcionalidad nueva o un encargo ambiguo, no escribas código ni spec todavía. Haz como mucho cinco preguntas: solo las que cambien qué se construye, cada una con opciones y con tu recomendación razonada.
3. **Lo que decidas tú, enuméralo.** Todo lo que resuelvas sin preguntar va a una lista en `bitacora/`: la pregunta que nadie hizo, lo que has decidido y dónde está en la spec. Es lo que se revisa.
4. **Criterios comprobables.** Cada comportamiento es un criterio numerado (`ABC-01`) con la forma Dado / Cuando / Entonces, con valores y mensajes de error exactos. La spec dice también lo que queda fuera.
5. **Sin visto bueno no se implementa.** Escrita la spec y la lista de decisiones, párate y pide revisión.
6. **Tests primero.** Al menos un test por criterio, con el identificador escrito tal cual (`ABC-01`) en el nombre del test; si el lenguaje no admite guiones en un nombre, en un comentario justo encima. Ejecútalos y enseña que fallan antes de implementar. Después, lo mínimo para que pasen. El refactor, al final y con todo en verde.
7. **No modifiques un test para que pase.** Si crees que un test o un criterio están mal, párate y dilo.
8. **Si el código contradice la spec, la spec cambia en el mismo cambio**, y se dice en el informe. Una spec desactualizada es un fallo.
9. **Terminado** es toda la suite en verde y el formateador y el linter sin avisos, en todo el repositorio y no solo en lo tocado. Las órdenes exactas están en `specs/001-plan-tecnico.md`.
10. **Dependencias**: solo las del plan técnico. Añadir otra exige cambiar antes esa spec.
11. **Informe al acabar**: ficheros tocados, decisiones y su porqué, desviaciones de cualquier spec y el resultado de la suite.

Qué pasó con esta carpeta Los siete ficheros de la plantilla, con las once reglas. · 2 oct 2026

Codex GPT-6.1-Sol

4 preguntas con recomendación. Sin código.

Su respuesta, tal como llegó
Antes de escribir la spec, necesito concretar cuatro decisiones:

1. **¿Dónde se usará?** Node.js, navegador o ambos. Recomiendo **ambos con módulos ES**, para mantenerlo reutilizable y sin dependencias.
2. **¿Qué devuelve al acortar?** Solo un código (`abc123`) o una URL con una base configurable (`https://corto.es/abc123`). Recomiendo **URL completa con base configurable**, y un método para recuperar el enlace original.
3. **¿Qué ocurre al acortar dos veces la misma URL?** Reutilizar el enlace corto o generar otro. Recomiendo **reutilizarlo**, para evitar duplicados en memoria.
4. **¿Qué validación quieres?** Solo URLs absolutas HTTP/HTTPS o cualquier cadena. Recomiendo **HTTP/HTTPS**, rechazando entradas inválidas con un error explícito.

Puedes aceptar todas las recomendaciones o cambiar alguna. Después escribiré las specs y la bitácora y pediré tu revisión antes de implementar, como exige la regla 5 de [AGENTS.md](/home/claude/Projects/iadev-codex/plantilla-prueba/AGENTS.md).

pi deepseek-v4-pro

5 preguntas con opciones, y la lista de lo que decidiría él. Sin código.

Su respuesta, tal como llegó
El proyecto está en la plantilla vacía (specs son esqueleto, no hay código). Según `AGENTS.md`, algo nuevo empieza por preguntas, no por código ni por spec. Antes de escribir nada necesito cerrar **cinco decisiones**. El resto lo decido yo por defecto y quedará anotado en `bitacora/`.

**1. Entorno y formato del módulo**
- (a) Node.js, ESM (`export`/`import`) — *recomendado*: estándar moderno, y permite testar con `node:test` sin añadir dependencias.
- (b) Node.js, CommonJS (`require`/`module.exports`).
- (c) Navegador (ESM/IIFE).

**2. Forma de la API**
- (a) Función fábrica `createShortener()` que devuelve `{ shorten, expand }` — *recomendado*: encapsula el estado sin `this` y es trivial de testar.
- (b) Clase `Shortener` con `shorten(url)` y `expand(code)`.

**3. Cómo se generan los códigos**
- (a) Aleatorios, base62, 6 caracteres, con reintento si colisiona — *recomendado*: no revela cuántos enlaces hay.
- (b) Secuenciales (contador codificado en base62).
- (c) Hash de la URL.

**4. Mismo URL acortado dos veces**
- (a) Devuelve el mismo código (deduplicación) — *recomendado*: es lo que la gente espera de un acortador.
- (b) Código nuevo en cada llamada.

**5. Comportamiento ante errores**
- (a) Lanza `Error` con mensaje exacto para entrada inválida; `expand` de un código desconocido devuelve `null` — *recomendado* (los mensajes exactos casan con los criterios "Dado/Cuando/Entonces").
- (b) Todo con excepciones, incluido código no encontrado.
- (c) Todo con valores de retorno (`null`/objeto de resultado), sin excepciones.

**Por defecto, si no me dices lo contrario**, decidiré y anotaré en la bitácora:
- URL válida = `http://` o `https://` con host; se rechazan vacías, con espacios y malformadas (en el `shorten`).
- Alfabeto base62: `0-9 A-Z a-z`; longitud 6.
- **Fuera de esta versión**: persistencia (ya es en memoria, como pediste), caducidad/TTL, alias personalizados, borrado, estadísticas.

Responde con algo como `1a 2a 3a 4a 5a` (o tus variantes) y sigo con la spec y la bitácora. Me paro antes de implementar para tu visto bueno.

Es la prueba de la página de la plantilla. Con las once reglas, los dos preguntan y los dos se paran.

Las cuatro carpetas cuentan una historia corta:

  • Nada. Los dos escribieron el módulo sin preguntar. Es el capítulo 1.
  • Solo la regla 2. Un fichero de tres líneas. Los dos preguntaron antes de escribir nada, uno tres cosas y el otro cinco, y los dos se pararon.
  • La plantilla sin la regla 2. Aquí se separan. La instrucción de preguntar seguía en METODO.md y en la skill, que son ficheros que el agente abre si quiere. Uno los abrió, encontró la instrucción y preguntó. El otro leyó METODO.md, no preguntó, escribió la spec con sus decisiones a la vista y se paró a pedir el visto bueno, porque esa regla sí estaba en AGENTS.md.
  • La plantilla entera. Los dos preguntaron y los dos se pararon.

La tercera carpeta es la que importa. Mismo contenido, dos resultados, y la diferencia no fue el modelo sino qué ficheros decidió abrir cada uno. Lo que tiene que pasar siempre va en el fichero que se lee siempre. Lo demás es contexto a demanda, y a demanda quiere decir a veces.

Qué va en el fichero

El AGENTS.md de acorta tiene diez reglas y 292 palabras. Se lee en diez segundos, y un agente lo lee al principio de cada una de las tareas del proyecto. Lo que hay:

Regla De qué va
1, 2 Las dos del método: la spec es el contrato; tests primero y en rojo
3 No modificar un test para que pase
4 Qué es «terminado»: gofmt, go vet y la suite entera en verde
5, 6 Qué ficheros puede tocar cada fase, y que no se añaden dependencias
7 Idioma de identificadores, comentarios y textos
8 Temporales fuera del repo; los commits los hace el orquestador
9 Qué lleva el informe final
10 Algo nuevo empieza por preguntas

Todas cumplen tres condiciones, y son las que sirven para decidir si una línea va aquí:

  • Vale para todas las tareas. Nada de una fase concreta. Lo que solo importa en el servidor va en el encargo del servidor.
  • Se puede comprobar. «Terminado es gofmt -l . vacío» se verifica con una orden. «Escribe código limpio» no se verifica con nada, y una regla que no se puede comprobar es un deseo.
  • Dice dónde están las cosas, no las copia. La spec no está en AGENTS.md; está specs/, y el fichero dice que se lea. Si copias la spec en las reglas tendrás dos versiones y una se quedará vieja.

Qué no va

Lo que se lee siempre tiene un coste siempre. Cada párrafo de AGENTS.md compite por el mismo contexto que la spec y el código, y un fichero largo se lee peor que uno corto. Tres cosas que suelen acabar ahí y no deberían:

  • Lo que una herramienta puede imponer. Las normas de formato las impone el formateador; en AGENTS.md basta con exigir que se haya pasado. Una regla de estilo que el formateador ya aplica es ruido.
  • Lo que cambia con la tarea. Qué ficheros tocar, qué criterios cubrir, qué leer. Eso es el encargo. Si lo metes en las reglas, tendrás que editarlas cada vez.
  • Secretos y rutas de tu máquina. Un agente lo copia a donde haga falta sin pensar en ello, y el fichero se sube al repositorio.

Y una cosa que conviene añadir aunque parezca una obviedad: lo que no hay que leer. El encargo del servidor de acorta lo dice así:

De specs/002-enlaces.md te basta con saber qué errores devuelve el servicio.

Son ciento y pico líneas que el agente no necesitaba. Decir qué no leer ahorra contexto, y el contexto que no se gasta en lo irrelevante se gasta en la tarea.

El encargo

El tercer sitio, el encargo de cada tarea, tiene en acorta una forma fija. Los seis que recibieron los agentes del paso rojo empiezan igual y tienen las mismas seis partes, en negrita:

  1. Qué leer antes. Los ficheros, en orden, y qué partes.
  2. La tarea. Qué hay que hacer, numerado.
  3. El método. Cómo: tests de tabla, reloj fijo, qué se simula y qué no.
  4. Los límites. Qué no tocar, qué no hacer, cuándo parar y preguntar.
  5. Terminado es. La condición de salida, comprobable.
  6. El informe. Qué tiene que contener la respuesta.

El primero es el que conecta con este capítulo. Este es el del servidor, entero:

Qué leer antes. Trabajas en el repositorio /home/claude/Projects/acorta. Antes de escribir nada lee, en este orden: AGENTS.md, specs/001-plan-tecnico.md y specs/004-api.md entera. De specs/002-enlaces.md te basta con saber qué errores devuelve el servicio. Mira el código que vas a usar: link/link.go y shortener/shortener.go (su Service cumple la interfaz Service de tu paquete).

Nada en ese párrafo es una regla general: es el mapa de lectura de una tarea concreta. Con eso, un agente que arranca sin saber nada tiene en un minuto lo mismo que sabría alguien del equipo. El capítulo siguiente recorre una sesión entera con encargos así.

Lo que el fichero no garantiza

Que una regla esté en un fichero que el agente ha leído no significa que se cumpla. El encargo del servidor de acorta decía que leyera el plan técnico, y lo leyó. Aun así, repartió las rutas a mano cuando el plan las asignaba a la biblioteca estándar, y entregó el informe con «desviaciones de la spec: ninguna». La revisión lo explicó así:

El agente solo había leído como contrato la spec de su fase (la 004) y trató el plan técnico como contexto.

Leer no es obedecer. Y en el experimento de arriba, la instrucción estaba en la carpeta y uno de los dos agentes no la abrió. AGENTS.md es la forma de que el agente sepa las reglas. Comprobar que las ha seguido es otro trabajo, y es el del capítulo 8.

Lo que viene

Con las reglas en su sitio, queda ver cómo es una sesión de trabajo entera: tarea a tarea, encargo, rojo confirmado, verde, revisión y commit. El capítulo siguiente repite la de acorta commit a commit.