Lo que necesita un repo antes de que los agentes de IA escriban casi todo su código

Nuestro método tiene una versión corta en Cómo construimos: los agentes escriben el código y un ingeniero responde por cada cambio. El ingeniero escribe el spec, planea cada cambio y revisa cada diff. El agente teclea. El ingeniero decide qué entra.

El repo de farcholabs.com funciona así. Del 26 de septiembre al 12 de octubre de 2026 se le hizo merge a 108 pull requests: el sitio, el admin y el CRM, la API y su worker. Todos pasaron por el mismo camino.

Un agente es rápido y no recuerda lo de ayer. Cada sesión empieza con lo que dice el repo. Así que el repo tiene que decir tres cosas: cómo funciona el proyecto, qué ya se decidió y cuándo un cambio está mal.

En la raíz está CLAUDE.md, de 155 líneas. Los agentes lo leen al empezar cada sesión. Tiene la estructura del repo, los comandos para correr cada app y sus checks, y las reglas que no se ven en el código: quién puede llamar a la API, dónde y cómo se guarda el dinero, qué nunca va en el sitio.

Cada app suma las suyas. apps/web/AGENTS.md tiene 126 líneas solo de la app web: dónde se registra una página nueva, cómo funciona la caché, con qué componentes se arma el admin. También trae un bloque que escribe el propio Next.js, que le avisa al agente que esta versión del framework no es la que quizás recuerda y lo manda a la documentación instalada con el paquete.

## Rules

- **Contract:** a change to API routes or models regenerates `apps/api/openapi.json` and
  `apps/web/lib/api/schema.d.ts` in the same commit. Both workflows fail on drift.
- **Owner decisions in content:** copy that depends on an open D item (prices, legal name,
  contact, the founder) reads it from `apps/web/lib/launch.ts` and leaves the detail out
  while it is open; never write a guess into a page.
- **Before committing,** run the checks of every app you touched (commands above).
  All must pass.

Las buenas reglas aquí son concretas. "Mantén la API y el frontend sincronizados" es un consejo. "Regenera estos dos archivos en el mismo commit, CI falla si no coinciden" es una regla que un agente puede seguir y un check puede hacer cumplir.

El repo tiene ocho registros de decisiones de arquitectura en docs/adr: la plataforma, el inicio de sesión del admin, el hosting, el dominio, la salida de Cloudflare, el blog y el chat del sitio. Cada uno dice qué se eligió, qué se comparó y qué implica. Cuando un agente se pregunta por qué el worker es un job de Cloud Run, la respuesta es un archivo, no una suposición.

Hay preguntas que solo responde el dueño: el nombre legal, los precios, cómo pagan los clientes. docs/PLAN.md las lista como D1 a D19, y CLAUDE.md lo dice sin rodeos: las D las decide el dueño, nunca se resuelven en silencio en el código. Mientras una sigue abierta, la página que depende de ella deja fuera el detalle.

Las respuestas viven en un solo archivo, apps/web/lib/launch.ts. Una abierta es null, y un script corto las lista y falla mientras quede alguna:

// apps/web/scripts/check-launch.mjs
const { openDecisions } = await import("../lib/launch.ts");

const pending = openDecisions();
if (pending.length === 0) {
  console.log("Every owner decision the site needs is answered.");
} else {
  console.error(`Not ready to publish: ${pending.length} owner decision(s) open (answer them in lib/launch.ts).`);
  for (const decision of pending) console.error(`  ${decision.id} (${decision.key}): ${decision.question}`);
  process.exitCode = 1;
}

La revisión atrapa lo que ve una persona. Los checks atrapan el resto, en cada pull request, antes de que alguien mire. Nuestro CI corre 13, repartidos en dos workflows que solo corren cuando cambia su app:

• En la web, 8: los tipos de la API coinciden con su archivo OpenAPI, el chequeo de tipos, el lint, el contraste WCAG AA de cada token de color en los dos temas, cada título y descripción dentro de los límites de los buscadores, los tres idiomas al día, las figuras de las guías seguras y descritas, y el build.
• En la API, 5: el lint, el formato, el chequeo de tipos, las pruebas contra un MongoDB real y el archivo OpenAPI igual al código.

Cada check es un error que ya no puede llegar a producción: un título de más de 60 caracteres, una página en español a la que le falta una clave del inglés, un diagrama con un color fijo que desaparece en modo oscuro. Quien revisa no tiene que acordarse; lo recuerda un script. CI solo valida. No despliega nada; eso lo hace el dueño.

líneas en el CLAUDE.md de la raíz

155

registros de decisiones de arquitectura

8

checks en CI en cada pull request

13

Una tarea programada escribió el borrador de este artículo. Tomó el siguiente tema que aprobó el fundador en una lista que vive en el repo, leyó las reglas de los artículos y los archivos que cita el tema, lo escribió en inglés y en español, y lo guardó como borrador. La API lo revisó antes de guardarlo: las palabras, las imágenes, los dos idiomas, un diagrama seguro. No puede publicar.

Después el fundador lo lee, cambia lo que haga falta y lo publica desde el admin. Publicar es su firma, igual que un merge.

El agente teclea. El ingeniero decide qué entra.

1. 01Un archivo de notas para el agente en la raíz, con la estructura, los comandos y las reglas que el código no muestra. Tan concretas que un script podría revisar cada una.
2. 02Un registro corto por cada decisión de arquitectura, con las opciones que descartaste.
3. 03Una lista de las preguntas que solo responde el dueño, y una regla para que la página deje fuera el detalle hasta que lo haga.
4. 04Un check por cada error que no quieres que quien revisa tenga que recordar, en cada pull request.
5. 05Una persona que lee cada diff y es la única que puede hacer merge.

Cada repo que entregamos a un cliente trae estos archivos. Cómo construimos tiene el método completo, y si tienes un producto en mente, envíanos un brief. Una persona lo lee.