Llevo meses usando Claude Code a diario y esta semana he escuchado un episodio que me ha hecho replantearme cómo tengo montados los repos. Es un episodio en solitario de Greg Isenberg en The Startup Ideas Podcast, patrocinado por Anthropic, donde monta en directo lo que él llama un «empleado de IA».
Resumo lo que cuenta y luego te explico las dos cosas que yo cambio para que esto encaje en repos de WordPress, que es donde trabajo yo y donde el planteamiento original se queda un poco corto.
La idea de fondo: tratar a Claude como a alguien que acaba de entrar
La premisa de Greg es sencilla y funciona: dale a Claude lo mismo que le darías a una persona que se incorpora a tu equipo. Un sitio donde trabajar, contexto del negocio, un briefing antes de tocar nada, una tarea concreta, ojos para comprobar su propio trabajo, una revisión contra tus estándares, unas tareas recurrentes y unos permisos claros.
Lo monta todo en directo sobre una idea que saca de ideabrowser.com, un responder de leads perdidos para clínicas de estética. Da igual el caso, lo interesante es la estructura.
Las nueve piezas, en corto
- Workspace. El repo. Carpetas para el producto, el contexto de negocio, las notas de cliente, las especificaciones, las demos y las tareas recurrentes. Más tres ficheros raíz: claude.md (cómo trabajas), roadmap.md (qué importa ahora) y review.md (cuándo algo está bien).
- Briefing. Plan mode antes de editar. Que lea el contexto, proponga enfoque, liste ficheros a tocar y riesgos, y espere aprobación. Medir dos veces, cortar una.
- Ticket. Una tarea, una meta visible, un cambio revisable. «Mejora la app» no es un ticket. «Añade un formulario de lista de espera con estado de éxito» sí.
- Ojos. Que abra la app en el preview, haga clic por el flujo, mire consola y red, y te diga qué entendería un cliente en cinco segundos. Esta parte casi nadie la usa y es la que más cambia el resultado.
- Revisión. Primero la tuya en el diff, buscando lo que sobra. Después la de Claude contra review.md, separando en «hay que arreglar», «convendría arreglar» y «se puede publicar».
- Horario. Las routines. Un brief cada mañana, una revisión de issues los viernes, una revisión automática de cada pull request.
- Agentes en paralelo. Sesiones separadas con aislamiento por worktree, cada una con un encargo distinto y un entregable claro.
- Permisos. Tres niveles: lo que puede hacer solo, lo que tiene que preguntar y lo que se queda en manos de una persona.
- Skills, conectores y hooks. Lo repetible se convierte en skill, los conectores le dan contexto externo y los hooks ponen las barreras alrededor del trabajo.
Mi primer cambio: toda la documentación en /docs
Aquí es donde me separo del planteamiento original. Greg propone colgar /context, /customers, /specs, /demos y /routines directamente en la raíz. En un proyecto que nace de cero y vive en Vercel, vale. En un plugin de WordPress, eso es ensuciar el repo.
Piensa en cómo es la raíz de un plugin: el fichero principal con la cabecera, readme.txt, composer.json, package.json, phpcs.xml.dist, phpunit.xml.dist, .distignore, la carpeta .github con los workflows, includes, assets, languages. Meterle cinco carpetas más de documentación en ese nivel hace dos cosas malas. La primera, que cuesta encontrar lo que importa. La segunda, y esta es la seria, que si no lo excluyes bien acaba en el ZIP que se sube al directorio de WordPress.org.
Así que todo lo que sea documentación para agentes se va a una sola carpeta:
mi-plugin/
├── AGENTS.md
├── CLAUDE.md
├── REVIEW.md
├── mi-plugin.php
├── readme.txt
├── includes/
├── assets/
└── docs/
├── roadmap.md
├── context/
│ ├── product.md
│ ├── decisions.md
│ └── daily-brief.md
├── specs/
├── routines/
└── customers/Una regla que sigo sin excepciones: carpetas y nombres de fichero siempre en inglés. Si mañana entra en el repo alguien de fuera o una herramienta nueva, docs/customers/ se entiende en cualquier sitio y docs/clientes/ no. Es lo mismo que ya hacemos con los nombres de funciones y de hooks, no veo motivo para cambiar de criterio con la documentación.
Con el contenido el criterio es todavía más simple: repo privado, en español; repo público, en inglés. Los proyectos de la agencia los lee mi equipo y nadie más, así que escribir el contexto de negocio en español va más rápido y sale más preciso. En cuanto el repo es público entra cualquiera desde cualquier parte, y ahí el inglés no es una preferencia, es lo que hace que la documentación sirva de algo.
Y esto hay que dejarlo escrito en el AGENTS.md, no darlo por hecho. Una línea del tipo «toda la documentación de este repo se escribe en inglés» evita que el agente te devuelva un fichero mezclando los dos idiomas, que es lo que pasa siempre si no se lo dices, porque tú le estás hablando en español y él deduce lo que puede.
La ventaja práctica de tenerlo todo bajo una carpeta es que con una sola línea lo dejas fuera de la distribución. En .distignore metes docs/ y ya no viaja al ZIP. Si además usas git archive para generar releases, en .gitattributes pones docs/ export-ignore y tienes el mismo efecto. Una carpeta, una regla, sin sorpresas en el deploy a SVN.
Ojo con una cosa: Claude Code no lee automáticamente todo lo que hay en /docs. Lee el fichero de instrucciones de la raíz, y de ahí tira del resto. Así que la carpeta solo funciona si el fichero raíz apunta a ella de forma explícita, con rutas concretas y una frase de cuándo usar cada documento. Si escribes «la documentación está en docs», el agente unas veces la abre y otras no.
Mi segundo cambio: AGENTS.md en vez de CLAUDE.md
En mis repos no trabaja un solo agente. Entra Claude Code, entra Codex, a veces Copilot en un pull request, y en los repos de la comunidad puede entrar cualquiera con la herramienta que le guste. Tener un fichero que se llama CLAUDE.md y que solo entiende una herramienta no tiene mucho sentido cuando el contenido, el estilo de código, los comandos de test, las reglas de WPCS, sirve para todas.
AGENTS.md es el estándar abierto que se ha ido asentando para esto. Lo leen Codex, Cursor, Copilot, Zed y unos cuantos más. Mi fuente de verdad va ahí.
Pero aquí hay un detalle técnico que conviene tener claro, porque circulan bastantes guías que lo cuentan mal: Claude Code no lee AGENTS.md. Lee CLAUDE.md. No hay fallback automático, aunque lleva tiempo siendo una de las peticiones más votadas del repositorio de Claude Code.
La solución que documenta Anthropic es un CLAUDE.md de una línea que importa el otro fichero:
@AGENTS.mdY ya está. La sintaxis @ruta de Claude Code carga el contenido de ese fichero como si estuviera escrito ahí mismo. Un fichero de una línea, cero duplicación, cero riesgo de que los dos textos se vayan separando con el tiempo. La otra opción es un enlace simbólico de CLAUDE.md a AGENTS.md, que funciona igual de bien, aunque en equipos con gente en Windows me he encontrado más de un problema, así que yo me quedo con el import.
Si en algún repo necesito reglas que solo apliquen a Claude Code, por ejemplo cosas de skills o de hooks que las demás herramientas no van a usar, las pongo debajo del import en CLAUDE.md. El resto vive en AGENTS.md.
Cómo traduzco las carpetas a mi trabajo real
El nombre de las carpetas del episodio está pensado para una startup con clientes que llaman por teléfono. En mi caso hay dos escenarios bastante distintos y no uso lo mismo en cada uno.
Proyecto de cliente en la agencia. Aquí sí encaja casi todo tal cual. En docs/customers/ van las actas de reunión, las objeciones que salen en las llamadas, el vocabulario que usa el cliente para describir su propio negocio. Eso último vale mucho más de lo que parece cuando le pides a Claude que escriba copy o que revise una landing, porque deja de escribir con mis palabras y empieza a escribir con las del sector.
Herramienta de la comunidad, tipo Plugin Check o las utilidades de revisión. Aquí no hay clientes, hay usuarios y hay un equipo. La carpeta de customers se convierte en docs/context/decisions.md, donde anoto por qué se hizo algo de una manera y no de otra. Y el roadmap deja de ser «lo que quiero esta semana» para ser «lo que hay abierto y en qué orden». El review.md es el que más me importa de los tres, porque las reglas de revisión de un plugin son muy concretas y son exactamente el tipo de cosa que un agente olvida entre sesiones.
Los permisos, en versión WordPress
Esta parte del episodio la firmo entera, solo hay que traducir los ejemplos. Los tres niveles quedan así en mis proyectos:
- Puede hacerlo solo: leer el código, pasar PHPCS con WPCS, ejecutar PHPUnit, correr Plugin Check, trabajar en una rama pequeña, actualizar documentación en /docs, abrir un pull request en borrador.
- Tiene que preguntar: instalar o subir dependencias de Composer y npm, tocar el proceso de build, cambiar la estructura de la base de datos, meter mano en autenticación, capabilities o nonces, borrar ficheros.
- Solo yo: el tag en SVN de WordPress.org, subir una versión al directorio, cualquier cosa que toque datos reales de un cliente, un cambio de seguridad que ya esté en producción.
La frase del episodio que más me ha gustado es que los permisos son una estrategia, no un obstáculo. Cuanto mejor está el review.md y más pequeños son los tickets, más margen le puedes dar. Al revés no funciona: dar barra libre con un repo sin contexto es cómo se acaba limpiando trabajo en vez de dirigiéndolo.
Por dónde voy a empezar con las routines
De todo el episodio, esto es lo que tengo menos rodado y lo que más curiosidad me da. La recomendación de Greg es empezar por algo útil y controlado, que no toque producción. Un brief por la mañana que lea las notas y los issues abiertos y te diga la tarea del día.
Traducido a lo mío, hay dos que voy a montar esta semana. La primera, una revisión automática de cada pull request contra docs/review.md, que comente solo lo que pueda provocar un bug, un problema de seguridad o un comportamiento raro, y que acabe diciendo si está listo para que lo mire una persona. La segunda, un repaso semanal de issues que agrupe los que hablan de lo mismo y me señale el arreglo con más recorrido. Las dos son de leer y escribir en /docs, sin tocar código, que es justo donde quiero estar mientras aprendo cómo se comportan.
Lo que me llevo
El fondo del episodio no va de prompts, va de que el repo se explique a sí mismo. Y eso es una tarea de documentación, algo que llevamos haciendo mal en desarrollo web desde siempre porque nunca había un incentivo inmediato. Ahora sí lo hay: la calidad de lo que te devuelve el agente es más o menos la calidad de lo que has escrito en esos ficheros.
Mis dos cambios son pequeños pero me ahorran problemas. Todo en /docs para que la raíz siga limpia y el ZIP no se llene de markdown. Y AGENTS.md como fuente de verdad, con un CLAUDE.md de una línea, para que cualquier agente que entre en el repo lea las mismas reglas.
Si tienes repos de WordPress y te animas a montarlo, cuéntame cómo lo has organizado tú. Y si ya tienes routines funcionando, me interesa mucho saber cuáles.
