STACK DE SPECS · 1 DE 3
EL README
PARA AGENTES.
Un archivo. Markdown plano. La diferencia entre un agente que lee el repo durante 15 minutos antes de tocar algo, y uno que arranca a programar en el segundo cero.
¿QUÉ ES?
UN ESTÁNDAR ABIERTO
PARA HABLARLE A LOS AGENTES.
AGENTS.md es una propuesta de OpenAI y la comunidad de agentic coding (formalizada en 2025) para resolver un problema concreto: los agentes de código no saben tu proyecto. Llegan, abren archivos al azar, infieren convenciones a medias y a veces aciertan. A veces no.
La solución es vergonzosamente simple: un archivo AGENTS.md en la raíz del repo con instrucciones para agentes. No para humanos. Comandos, convenciones, restricciones, en lenguaje directo.
Lo respetan Claude Code, OpenAI Codex, Cursor, Aider, Continue, Windsurf y prácticamente cualquier agente de coding que haya salido en 2025-2026. Si tu repo tiene CLAUDE.md, ya tienes el 90% del trabajo — solo renómbralo o duplícalo como AGENTS.md.
ESTRUCTURA
QUÉ SECCIONES LLEVA.
No hay schema rígido. Pero estas 6 secciones aparecen en casi todos los AGENTS.md que rinden bien.
Project Overview
2-3 líneas. Qué es el proyecto, stack, dónde vive en producción. Lo primero que el agente necesita para no inventar contexto.
Dev Environment
Cómo correr el proyecto local: package manager, comando de dev server, variables de entorno mínimas, puertos. Sin esto el agente arranca a ciegas.
Build & Test
Comandos exactos para `build`, `test`, `lint`, `typecheck`. El agente los corre antes de marcar trabajo como terminado. Cero ambigüedad.
Code Style & Conventions
Naming, estructura de carpetas, patrones de import, qué frameworks usar. Evita que el agente meta clases cuando todo el repo es funcional.
PR / Commit Rules
Formato de commit, rama base, cómo abrir PR, qué pasa con hooks. Si tienes Conventional Commits o Linear IDs, va aquí.
Don’t Touch
Carpetas o archivos prohibidos: secrets, generated, legacy. La sección que más dolor evita en repos grandes.
EJEMPLO REAL
UN AGENTS.md EN PRODUCCIÓN.
# AGENTS.md — gabrielneuman.com ## Project Overview Sitio personal de Gabriel Neuman / GNB Labs. Stack: Next.js 15 (App Router), React 19, Tailwind 3, MongoDB, NextAuth v5 beta, Vercel. ## Dev Environment - Node 20+ - pnpm install - pnpm dev # http://localhost:3000 - Variables en .env.local (ver .env.example) ## Build & Test - pnpm build # debe pasar antes de PR - pnpm typecheck # tsc --noEmit - pnpm lint # eslint No hay test runner aún. ## Code Style - Server Components por defecto. "use client" solo si hace falta. - TailwindCSS, sin CSS modules. - Imports absolutos con alias @/. - Naming: kebab-case en archivos, PascalCase en componentes. ## PR Rules - Rama: claude/<descripcion-corta> - Commit en español, imperativo, sin prefijo conventional. - No abrir PR sin permiso explícito del usuario. ## Don't Touch - segundo-cerebro/ (contenido privado del usuario) - wiki/ (solo se edita cuando se cierra sesión) - raw/ (inputs sin procesar) - /api/auth/ (NextAuth, frágil)
Versión adaptada del CLAUDE.md real de este sitio.
MEJORES PRÁCTICAS
QUÉ HACER. QUÉ NO.
Sí hacer
- →Hazlo escaneable. Headers cortos, listas, código en bloques. Un agente que lo lee en un solo pase rinde más.
- →Pon comandos exactos, no descripciones. `pnpm test` vence a "corre los tests".
- →Versiona la verdad. Si el repo cambia de package manager o de framework, AGENTS.md se actualiza en el mismo PR.
- →Mantén un Don’t Touch explícito. Es más barato listar 5 carpetas prohibidas que reparar un destroze.
- →Si hay subproyectos, deja un AGENTS.md por carpeta. Override jerárquico — el más específico gana.
No hacer
- ×Copiar-pegar el README de humanos. El humano lee diagonal; el agente lee literal y obedece.
- ×Mezclar específicación con tutoriales. El "por qué histórico" va en docs/ — aquí solo el "cómo".
- ×Dejar comandos obsoletos. Un AGENTS.md desactualizado es peor que no tenerlo: el agente sigue las instrucciones rotas con confianza.
- ×Esconder secrets ahí. Es un archivo público. Los secrets viven en `.env` y en el secret manager.
CÓMO LO USO
EN GNB LABS,
ESTO ES LO QUE HAGO.
CLAUDE.md como AGENTS.md
En este repo el archivo se llama CLAUDE.md porque arrancó cuando Claude Code lo leía por convención. Funciona idéntico. Si alguien clona el repo y usa Codex, copio el contenido a AGENTS.md y listo.
Protocolo de sesión arriba del archivo
Lo primero que ve el agente es un checklist de arranque: leer el wiki, revisar el último log, no editar ciertas carpetas. En 5 líneas el agente sabe el contexto vivo del proyecto sin yo tener que recontárselo cada vez.
Una sola fuente de verdad por dominio
Las reglas de voz no viven inline en AGENTS.md — viven en skills/voz-gnb/ y AGENTS.md solo apunta ahí. Si extiendo la lista de palabras prohibidas, edito un solo archivo y todos los agentes lo respetan.
Don’t Touch explícito
Tengo carpetas privadas (segundo-cerebro/, wiki/) que el agente nunca debe editar en flujos normales. Listadas explícitamente. Cero ambigüedad, cero accidentes.