Plantilla · Básico · 5 min

Generador de CLAUDE.md y AGENTS.md en español, gratis

Rellena un formulario y descarga un CLAUDE.md, un AGENTS.md o los dos, con avisos en vivo de reglas vagas, claves pegadas e imports mal escritos.

Probado con Claude Code 2.1.316 · revisado 2026-11-01

Ver los archivos en GitHub Gratis · licencia MIT

Qué incluye

La herramienta está arriba: rellenas nombre, stack, comandos, reglas y trampas de tu proyecto, y genera un CLAUDE.md, un AGENTS.md o los dos (un AGENTS.md compartido + un CLAUDE.md que lo importa con @AGENTS.md). Mientras escribes, valida lo que la documentación oficial desaconseja, y al final descargas los archivos. Funciona sin conexión, sin registro y sin enviar nada: todo ocurre en tu navegador.

El código (un único archivo JavaScript sin dependencias, un index.html de ejemplo y sus pruebas con Node) está en el repositorio gratuito ctrlia-generador-claude-md.

Qué genera y por qué con esas reglas

La documentación oficial dice que Claude trata CLAUDE.md como contexto, no como configuración obligatoria, y da tres reglas que la herramienta aplica: instrucciones concretas y comprobables («usa 2 espacios», «ejecuta npm test antes de hacer commit»), menos de 200 líneas por archivo y nada contradictorio. Por eso el formulario no pide el árbol de carpetas ni la lista de dependencias (Claude las lee del código), y sí pide lo que no se ve: cómo comprobar el trabajo, convenciones ocultas, rutas que no debe tocar y trampas conocidas. La salida se organiza en secciones con encabezados y viñetas, como recomienda la documentación.

Encaja con la receta CLAUDE.md que funciona: la receta explica el porqué y los niveles (usuario, proyecto, local, reglas por ruta); el generador produce el archivo de proyecto.

Campos del formulario

• Proyecto: nombre (obligatorio, máx. 80 caracteres), stack y una frase de descripción.
• Comandos, copiados tal cual se ejecutan: instalar, servidor de desarrollo, todos los tests (muy recomendado), un solo test, lint, tipos y compilar. Los vacíos no salen.
• Reglas, una por línea: cómo dar algo por terminado (si se deja vacío y hay comando de tests, se rellena con «Pasa <test> sin errores»), convenciones que no se ven en el código (admite imports @docs/estilo.md), rutas que no debe tocar sin preguntar, trampas conocidas, ramas, estilo de commits e idioma de respuesta (por defecto «español»).
• Salida: solo CLAUDE.md, solo AGENTS.md o los dos; un campo «solo para Claude Code» (por ejemplo «usa el modo plan en src/pagos/») que va únicamente en CLAUDE.md; y una casilla «uso también un CLAUDE.local.md» para avisar de su efecto sobre AGENTS.md.

Lógica de AGENTS.md (verificada en la documentación)

Desde la 2.1.277, con el valor por defecto de /config → Project instructions (claude-md-or-agents-md), Claude Code lee AGENTS.md solo si no hay CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo o por encima; ~/.claude/CLAUDE.md y .claude/rules/ no cuentan. Si hay los dos, gana CLAUDE.md.

Por eso la opción «los dos» genera un CLAUDE.md cuya primera línea es @AGENTS.md, seguido de una sección «Claude Code» con lo específico: es el patrón oficial «Share one file with other coding tools», no lee AGENTS.md dos veces y funciona también en sesiones donde la lectura directa no está disponible. No proponemos el enlace simbólico ln -s AGENTS.md CLAUDE.md por defecto: la documentación avisa de que en Windows Git lo convierte en un archivo de texto de una línea y de que las herramientas Edit y Write no escriben a través del enlace. Dentro de AGENTS.md, Claude Code expande los @imports, pero otras herramientas pueden no hacerlo, y la herramienta lo avisa.

Validaciones

Errores (bloquean la descarga):

• Falta el nombre del proyecto.
• El texto contiene algo con forma de secreto (sk-ant-…, claves de 20+ caracteres tipo sk-, tokens ghp_/gho_ de GitHub, claves AKIA de AWS, cabeceras de clave privada o «password/token/secret: valor»), porque el archivo se sube a git.

Avisos (no bloquean):

• Sin comando de tests.
• Reglas vagas («buen código», «código limpio», «buenas prácticas», «formatea bien»…).
• Prohibiciones con «nunca/jamás/prohibido», que según la receta deberían ir a permisos o hooks para que se cumplan siempre.
• Un @import entre comillas (la documentación dice que no se importa) o con espacios sin \ .
• Más de 200 líneas en algún archivo.
• @imports dentro de AGENTS.md.
• Con «los dos» y la casilla de CLAUDE.local.md, el recordatorio de que ese archivo bloquea la lectura directa de AGENTS.md.

Las comillas invertidas de los comandos se limpian para no romper el formato. La vista previa usa textContent, así que nada de lo que escribas se interpreta como HTML.

Privacidad y accesibilidad

La página no tiene scripts en línea ni orígenes externos: un único script servido desde ctrlia.dev, sin fetch, sin almacenamiento y sin analítica propia de la herramienta. La descarga se hace con un Blob y un enlace temporal con atributo download, que se revoca al segundo; no hay servidor que reciba el texto. Cada campo tiene su label, los grupos van en fieldset con legend, la lista de avisos tiene aria-live="polite" para lectores de pantalla y la vista previa es enfocable con teclado. La lógica (generar y validar) está separada de la interfaz para poder probarla con Node.

Cómo usarla

1. Rellena lo que Claude no puede ver en el código

Empieza por el comando de todos los tests y el de un solo test: es lo más útil del archivo. Luego las convenciones que no se deducen del código, las rutas que no debe tocar sin preguntar y las trampas conocidas. Deja fuera el árbol de carpetas y las dependencias.

2. Elige la salida

Si solo usas Claude Code, «Solo CLAUDE.md». Si el repositorio lo usan también Codex, Cursor u otros agentes, «AGENTS.md + CLAUDE.md que lo importa», y pon lo exclusivo de Claude en el campo «Solo para Claude Code».

3. Corrige los avisos y descarga

Los errores bloquean la descarga; los avisos no, pero léelos: una regla vaga no sirve y una prohibición sin excepción va mejor en permisos o en un hook. Descarga el archivo y guárdalo en la raíz del repositorio.

4. Comprueba que Claude Code lo carga

Abre Claude Code en esa carpeta y ejecuta /context: CLAUDE.md debe aparecer en Memory files (si usas solo AGENTS.md verás la línea «no CLAUDE.md found; AGENTS.md loaded: …»). Haz una pregunta que dependa del archivo, por ejemplo «¿cómo ejecuto un solo test?», y comprueba que responde con tu comando.

/context
/doctor prompt-audit

/doctor prompt-audit (2.1.283 o posterior) hace que Claude busque instrucciones contradictorias o que apuntan a archivos que no existen.

5. Mantenlo corto

Con el tiempo, añade solo lo que ya le hayas tenido que corregir dos veces, mueve los procedimientos largos a skills (receta tu primera skill) y las prohibiciones a permisos o hooks. Si tu archivo crece de 200 líneas, divide por ruta con .claude/rules/. Y si quieres revisar también tu settings.json, usa el comprobador de settings.

Los archivos

Salida real de la herramienta con la opción «AGENTS.md + CLAUDE.md que lo importa» para un proyecto FastAPI. AGENTS.md:

# Proyecto: api-pedidos (Python 3.12 + FastAPI)

API REST de pedidos.

## Comandos
- Instalar: `uv sync`
- Servidor de desarrollo: `uv run fastapi dev app/main.py`
- Todos los tests: `uv run pytest -q`
- Un solo test: `uv run pytest tests/test_x.py -q`
- Lint: `uv run ruff check .`
- Tipos: `uv run mypy app`

## Cómo dar algo por terminado
- Pasa `uv run pytest -q` sin errores.

## Convenciones (lo que no se ve en el código)
- Indentación de 4 espacios
- Las consultas SQL van en app/repos/, nunca en los endpoints
- Estilo detallado: @docs/estilo.md

## No tocar
- `migrations/` (pregunta antes de cambiarlo)
- `.github/workflows/` (pregunta antes de cambiarlo)

## Trampas conocidas
- Los tests de integración necesitan Postgres: docker compose up -d db

## Git
- Ramas: feat/… o fix/…
- Commits: en español, en imperativo

## Idioma
- Responde y escribe comentarios en español.

Y el CLAUDE.md que lo importa:

@AGENTS.md

## Claude Code
- Usa el modo plan para cambios en app/pagos/

Con esos datos la herramienta muestra dos avisos: la línea con «nunca» iría mejor como regla de permisos o hook, y el @docs/estilo.md dentro de AGENTS.md lo expande Claude Code, pero otras herramientas pueden leerlo como texto.

En el repositorio están todos los archivos de la herramienta:

Para probarla en tu equipo:

git clone https://github.com/carlosp5751258-lgtm/ctrlia-generador-claude-md
cd ctrlia-generador-claude-md
node pruebas.js        # → ok: generador … ok: ejemplo

Y abre index.html en el navegador. Fuentes: memoria de Claude Code, comandos y el CHANGELOG.

Preguntas frecuentes

¿CLAUDE.md o AGENTS.md?

Si solo usas Claude Code, CLAUDE.md. Si el repositorio lo usan también Codex, Cursor u otros agentes, AGENTS.md compartido y un CLAUDE.md con @AGENTS.md para lo específico de Claude. Desde la 2.1.277 Claude Code lee AGENTS.md solo cuando no hay CLAUDE.md.

¿Se envía mi información a algún sitio?

No. El archivo se genera en tu navegador con un script de ctrlia.dev y se descarga directamente; la página no hace peticiones con lo que escribes.

¿Cuántas líneas debe tener?

La documentación oficial recomienda menos de 200 por archivo; la herramienta avisa si te pasas. Lo que solo importa en una carpeta va a reglas por ruta en .claude/rules/.

¿Por qué me avisa de «nunca» en una regla?

Porque CLAUDE.md es contexto, no una garantía. Lo que no admite excepciones (no leer .env, no hacer push --force) se cumple siempre con reglas deny de permisos o con un hook.

¿Puedo usar un enlace simbólico en vez de @AGENTS.md?

Funciona si nadie usa Windows; la documentación avisa de que Git en Windows lo convierte en un archivo de una línea y de que Claude no edita a través del enlace. El import @AGENTS.md no tiene esos problemas.

Tengo un CLAUDE.local.md y Claude ya no lee mi AGENTS.md, ¿por qué?

Es lo documentado: CLAUDE.local.md cuenta como CLAUDE.md. Pon @AGENTS.md en un CLAUDE.md o cambia /config → Project instructions a claude-md-and-agents-md.

Toda la biblioteca