Plantilla para empezar proyectos cuando trabajas con agentes de código
sin que se pongan a escribir antes de entender qué estás construyendo.
Una plantilla de repositorio que impone un protocolo simple: antes de tocar código, el agente lee la documentación del proyecto.
Si los documentos están vacíos, empieza haciendo preguntas — no escribiendo código. Si están rellenos, arranca con todo el contexto cargado y sin tener que volver a explicárselo en cada sesión.
Es agnóstica al stack. El protocolo funciona igual con Next.js, Astro, FastAPI o cualquier otra cosa que decidas usar.
- Founders y equipos pequeños que construyen productos con ayuda de agentes de IA y quieren reducir el rework.
- Cualquiera que se haya cansado de explicarle al modelo el mismo contexto en cada conversación nueva.
AGENTS.md— Contrato de entrada para el agente, sea cual sea: Claude Code, Codex, Cursor, Copilot… Define qué leer, cómo se trabaja una feature, cómo registrar cambios, cómo configurar los MCPs del stack, qué no hacer y dónde están los límites de lo que puede ejecutar por su cuenta.CLAUDE.md— ImportaAGENTS.mdpara Claude Code y añade solo lo específico de esa herramienta.docs/— Ocho archivos vivos que capturan las decisiones que típicamente se pierden entre conversaciones: producto, arquitectura, modelo de datos, design system, business, roadmap, flujos de usuario y testing. No todos aplican a todos los proyectos: hay una tabla que decide cuáles según el tamaño.docs/features/— Una ficha por unidad de trabajo acordada: qué se construye, qué requisitos cierra y cómo se va a comprobar cada uno. Es el contrato que se firma antes de escribir código. Llega vacía.changelog/— Registro estructurado de cada cambio importante: qué, cuándo, por qué y qué requisitos cierra. Llega vacío: solo con el archivo que explica el formato.mejoras/— Backlog de ideas que no entran en el sprint actual pero no se quieren perder..claude/— Configuración de Claude Code con permisos sensatos y siete skills (.claude/skills/) que llevan los procedimientos del protocolo. Se lanzan con/nombre, y el agente también las carga solo cuando la tarea encaja con su descripción.scripts/— Una verificación ejecutable: comprueba que ninguna ficha deje un requisito sin validar y que los tests prometidos existan de verdad. Node sin dependencias..github/— Plantillas de pull request e issues alineadas con el protocolo, y el workflow que ejecuta esa verificación en cada PR. El PR pide evidencia pegada, no casillas marcadas..template/— Historial de la plantilla en sí. Se borra al inicializar tu proyecto, así no arrastras cambios que no son tuyos.- Lo aburrido pero necesario:
.gitignore,.env.example,LICENSE.
- Cualquier sesión empieza leyendo
docs/. Si están vacíos o incompletos, el agente pregunta antes de actuar. Y no pide los ocho documentos: pide los que correspondan al tamaño del proyecto. - Cada funcionalidad del PRD lleva ID y criterio de aceptación comprobable. "Dado…, cuando…, entonces…", con un resultado que se pueda mirar. Ese criterio es el que después se convierte en test.
- Antes de construir una feature se escribe su ficha en
docs/features/, con una tabla que dice cómo se validará cada requisito. Antes de darla por acordada, el agente la revisa como un QA: ambigüedades, contradicciones y casos límite sin cubrir, sin proponer soluciones, para que las resuelvas tú. Después se construye una fila de la tabla cada vez, y el agente para a enseñarte cada una. Ningún requisito se queda sin tercera columna: o lleva la ruta de su test, o una revisión humana que dice qué se mira y qué tiene que verse, o la razón concreta por la que no se puede validar de ninguna de las dos formas. Y esto no es honor system: un script lo verifica en cada PR, y falla si un test prometido no existe. - Los tests se escriben después de implementar, leyendo el código real. Escritos antes apuntan a selectores imaginados, y acaban vaciándose de aserciones hasta que pasan.
- Cada cambio importante deja registro en
changelog/con qué se hizo, qué se modificó, por qué y qué requisitos cierra. - Si el cambio afecta a algo documentado, se actualiza el doc en la misma sesión. No hay documentación desincronizada.
- Con el stack ya decidido, el agente pregunta qué MCPs quieres y con qué alcance: los globales que ya tengas, o servidores configurados a nivel de proyecto en
.mcp.json. No instala nada por su cuenta ni antes de que haya stack. - El PR se cierra con evidencia, no con casillas. La salida real de los comandos va pegada en el PR; lo que no se ha ejecutado se dice.
- Antes de mergear a producción, se ejecuta
/security-reviewpara detectar vulnerabilidades, credenciales filtradas y problemas comunes. - Las ideas que no entran ahora se anotan en
mejoras/sin interrumpir el flujo actual.
Ningún requisito se queda sin su tercera columna: o lleva la ruta del test que lo valida, o una revisión humana que dice qué se mira y qué tiene que verse, o la razón concreta por la que no se puede validar de ninguna de las dos formas. Y no es una norma de buena voluntad — hay un script que la comprueba, y corre en CI con cada pull request.
La gracia está en cuándo aprieta y cuándo no. Mientras la ficha está en construcción no exige nada: los tests se escriben después de implementar. En el momento en que la das por Verificada, el test prometido tiene que existir.
Cada una vive en .claude/skills/<nombre>/SKILL.md. Las invocas tú con /nombre, o el agente las carga por su cuenta cuando lo que estás haciendo encaja con la description de su cabecera: no hace falta acordarse de lanzarlas.
| Skill | Qué hace |
|---|---|
/feature |
Crea la ficha de una feature antes de construirla, con su tabla de cobertura |
/changelog |
Registra un cambio con el formato del proyecto |
/mejora |
Añade una idea al backlog sin romper el flujo de trabajo |
/diagnostico |
Parte del estado: documentación, fichas a medias, entorno, variables, MCPs y tests |
/mcp-setup |
Configura los servidores MCP del stack, preguntando alcance y credenciales |
/documentacion |
Decide qué documentos de docs/ necesita tu proyecto según su tamaño y en qué orden se rellenan |
/init-proyecto |
Arranca el proyecto: rellena docs/ contigo y convierte la plantilla en tu repositorio (una sola vez) |
- Pulsa Usar esta plantilla en GitHub, o clona el repo directamente.
- Abre el proyecto en Claude Code, Cursor o el agente que prefieras.
- Cuando el agente lea
AGENTS.mdpor primera vez, te preguntará qué quieres construir y para quién. Responde y deja que vaya completando los docs contigo, uno a uno. - Con los docs rellenos, el agente inicializa el proyecto: reescribe este README para tu producto, rellena los datos de
AGENTS.md, ajusta la licencia y.env.example, borra los documentos que tu proyecto no necesite y.template/, y deja el changelog con su primera entrada real. Lo hace solo; si quieres forzarlo, usa/init-proyecto. - A partir de ahí, arranca el desarrollo. Cada feature empieza por su ficha (
/feature) y termina con su evidencia. Cada sesión nueva entra ya con todo el contexto cargado.
El atajo, si empiezas proyectos a menudo: la skill new-project hace los pasos 1 y 2 por ti. Le dices al agente "vamos a empezar un nuevo proyecto", le das un nombre, y crea un repositorio privado a partir de esta plantilla, lo clona en tu carpeta de proyectos y te deja dentro, ya en el paso 3. Se instala una sola vez, a nivel de usuario:
git clone https://github.com/polmarza/new-project ~/.claude/skills/new-project¿Algo no cuadra en cualquier momento? /diagnostico revisa documentación, fichas a medias, entorno, variables, MCPs y tests, y te dice qué falta y cómo arreglarlo. Para problemas del propio Claude Code, o para auditar si las instrucciones del proyecto y las skills se han quedado desfasadas, está su /doctor nativo (/doctor prompt-audit).
- Gestor de paquetes: pnpm v11 (no npm, no yarn).
- El resto de convenciones (idioma, naming, estilo) se decide al rellenar
AGENTS.mdydocs/architecture.md.
No tienes que hacerlo a mano: el agente lo hace en la inicialización, siguiendo el checklist de la skill /init-proyecto. Lo que cambia:
| Archivo | Qué pasa con él |
|---|---|
README.md |
Se reescribe entero para tu producto (este texto y sus badges desaparecen) |
AGENTS.md |
Se rellenan nombre, stack, estructura y convenciones |
CLAUDE.md |
Se queda tal cual: solo importa AGENTS.md |
LICENSE |
El copyright pasa a ser el tuyo |
.env.example |
Se queda solo con las variables de tu stack |
docs/ |
Se borran los documentos que tu proyecto no necesita, según su tamaño |
docs/features/ |
Se queda vacía, lista para la primera ficha |
scripts/ |
Se queda tal cual: la verificación no depende del stack |
changelog/ |
Recibe la primera entrada real del proyecto |
mejoras/backlog.md |
Se limpia el ejemplo |
.template/ |
Se borra |
.claude/skills/init-proyecto/ |
Se borra: la inicialización solo se hace una vez |
El criterio es simple: cuando termina la inicialización, ningún archivo del repo se describe a sí mismo como plantilla. Todo habla de tu proyecto.
MIT © 2026 Pol Marzà. Ver LICENSE.