senior-mindset: que Claude Code programe como un senior de verdad

El código que escribe la Inteligencia Artificial tiene un problema que no sale en las demos: funciona hoy y mañana nadie lo entiende. Ni tú, ni el siguiente que lo toque, ni la propia Inteligencia Artificial en la siguiente sesión, que no se acuerda de por qué eligió PostgreSQL, ni de que ya existía una función para consultar la base de datos, así que escribe otra.

Para eso he publicado senior-mindset, una skill nueva en mi repo de skills para Claude Code. Su trabajo es que Claude programe como un senior pragmático por defecto, sin tener que repetírselo en cada prompt.

No es algo que haya hecho en una tarde. Llevo bastante tiempo trabajando en ella, y ahora es cuando he decidido publicarla. Tampoco está terminada: la voy actualizando según me encuentro cosas que faltan o que se pueden hacer mejor, y todavía hay cosas por añadir en las que estoy trabajando para hacerlas bien. Así que lo que cuento aquí es la foto de hoy, no la versión final: parte de lo que describo puede quedarse obsoleto con las próximas actualizaciones. Para la versión al día, tira siempre del README de la skill en GitHub.

Y una advertencia antes de seguir: la skill está pensada para mi forma de trabajar. Yo sigo leyendo código y sigo escribiendo código, y por eso hay tantas normas dirigidas al humano que va a tener que entenderlo después: nombres que se explican solos, specs, ADRs, un inventario. Mi visión de cómo programar con Inteligencia Artificial es bastante distinta de la que se lleva ahora, y de eso hablaré en cómo programo yo con Inteligencia Artificial.

Si no sabes qué es una skill, lo expliqué en el post en el que publiqué mis skills para Claude Code: un SKILL.md con instrucciones que Claude carga cuando lo que le pides encaja con su descripción. Y si lo que te interesa es cómo se instala con un comando, eso lo cuento aparte en cómo convertí mi repo de skills en un marketplace de plugins de Claude Code.

Qué hace senior-mindset en Claude Code

No hablo de un senior de manual que mete microservicios en una lista de la compra. Hablo del que sabe cuándo merece la pena la ceremonia y cuándo no. Esa es la diferencia entre una skill que usas y una que desinstalas a la semana.

Primero, distinguir un script de un proyecto

Lo primero que hace es medir la tarea. Un script suelto (un archivo, de usar y tirar, sin usuarios) se salta la ceremonia: nada de entrevista, ni specs, ni ADRs, ni linter. Un proyecto sigue el flujo completo. Y si no está claro cuál de las dos cosas es, pregunta.

Parece una tontería y es lo que hace que la skill sea usable. Si cada script de diez líneas acabara con una carpeta docs/ y tres ADRs, la desinstalaría yo mismo.

Git desde el principio

En un proyecto sin repositorio, hace git init con la rama por defecto y un .gitignore que siempre cubre los .env, los secretos, las dependencias y lo que genera el build. La rama por defecto es master, y si no está apuntada en el CLAUDE.md, pregunta una vez si prefieres main.

Para los commits usa su propia convención (Conventional Commits con emoji, en inglés y en imperativo), salvo que tengas otra skill de git instalada o una convención en el CLAUDE.md: en ese caso, manda esa.

Y va haciendo commits solo, sobre la marcha: uno por cada cambio importante (una tarea de la spec terminada, una decisión tomada, un fallo arreglado), dejando siempre el repo funcionando. Nada de un commitazo gigante al final de la sesión, y nada de commits “wip” en la rama principal. Cada spec va en su propia rama (feat/0001-user-auth, por ejemplo).

Lo que nunca hace sin que se lo pidas es lo que afecta a los demás: push, force-push, merge, rebase de ramas compartidas o borrar ramas y etiquetas.

Una entrevista, una sola vez por proyecto

En un proyecto, me entrevista una sola vez: stack, base de datos, plataforma de despliegue, arquitectura, convención de nombres, logging, linter y rama por defecto. Cada decisión queda guardada como un ADR (Architecture Decision Record) y un resumen va a una sección ## Engineering conventions del CLAUDE.md del proyecto. La próxima sesión lo lee y no vuelve a preguntar.

Así se ve, según el ejemplo del README de la skill:

you    › build me a booking app
claude › Before writing code, 4 quick questions (I'll remember the answers):
         stack · database · where you deploy · default branch…
         ✔ ADR-0001..0004 written · CLAUDE.md updated · docs/INVENTORY.md created
         Here's docs/specs/0001-bookings/spec.md: 6 acceptance criteria.
         Approve it and I'll start with the tests.

La conversación sigue en tu idioma: lo que va en inglés es el código, los identificadores, los commits y los nombres de los documentos.

Además, en esa primera vuelta deja configurados el linter, el formateador, el logger y el .gitignore antes de la primera feature. Que es justo cuando nadie lo hace, porque “ya lo pondremos”.

Spec-Driven Development: no programa hasta que apruebo la spec

Aquí está el corazón de la skill. Antes de escribir una línea, crea docs/specs/NNNN-slug/ con tres archivos:

spec.md: el qué y el por qué, con criterios de aceptación numerados (AC-1, AC-2…), incluidos los no funcionales que se puedan medir, y lo que queda fuera.
design.md: el cómo: módulos, datos, endpoints, riesgos y enlaces a los ADRs.
tasks.md: la lista de tareas, donde cada tarea apunta a un criterio y lleva sus tests.

La spec nace en estado borrador. Solo cuando la apruebo pasa a aprobada y empieza la implementación, y al terminar se marca como implementada. Si hay huecos en la spec, pregunta en vez de suponer. Que es exactamente lo contrario de lo que hace un modelo de lenguaje cuando lo dejas a su aire.

ADRs inmutables

Un ADR no se edita nunca. Si una decisión cambia (pasas de una base de datos a otra, por ejemplo), se escribe un ADR nuevo y el viejo queda marcado como Superseded by ADR-00XX. Así el historial de por qué se hizo cada cosa no se pierde, que es justo lo que nunca está documentado en ningún proyecto.

Y no solo van a ADR las decisiones de la entrevista. Cualquier decisión de diseño que vaya más allá de una feature (una librería, un patrón, una plataforma, un lenguaje) se convierte en su propio ADR.

El inventario: no reinventar lo que ya existe

docs/INVENTORY.md es el mapa de lo que ya existe: cada módulo, herramienta, script, endpoint o tabla, con su ruta, para qué sirve y cómo se usa. Antes de crear una función, Claude la busca ahí y en el código. Si ya hay algo que hace el trabajo, lo usa o lo amplía.

Y cuando termina, actualiza el inventario: lo nuevo entra, lo que se ha borrado sale. Es lo que impide que la siguiente sesión reinvente algo que ya existe. Se acabó la quinta función para consultar la base de datos.

Cómo evalúa el diseño

Mientras escribe el design.md, la skill decide y justifica cada eje, y si la decisión afecta a todo el proyecto, la convierte en ADR.

Monolito, microservicios o eventos

Monolito modular por defecto: un único desplegable con módulos de límites claros. Microservicios solo con motivos claros, y event-driven para el trabajo asíncrono. Si elige el monolito, deja una línea explicando por qué no hacían falta microservicios.

El lenguaje de cada componente lo decido yo

Para cada pieza (Python, Go, Rust…) me enseña una tabla corta de pros y contras de dos o tres candidatos, da una recomendación razonada y decido yo. La skill propone; no impone.

Tests

Unitarios siempre, para el dominio y los casos de uso, y de integración para los adaptadores.
TDD en proyectos grandes o con lógica crítica.
Tests de carga con k6 en webs y APIs que vayan a tener tráfico, con los objetivos escritos como umbrales para que la ejecución falle si no se cumplen. Como alternativas, JMeter y ab.

APIs contract-first

El contrato va antes que el código: OpenAPI 3.1 en docs/api/openapi.yaml. Los errores siguen el RFC 9457 (Problem Details) y la paginación es por cursor, siempre con un límite máximo.

Logging desde el minuto cero

Con una librería que ya existe (pino, structlog, slog…), nunca uno hecho a mano. Y nunca registrando contraseñas, tokens, secretos ni datos personales, que es lo que OWASP recoge en su punto A09.

Dónde se despliega: plataformas y servidores

A la skill también le he volcado lo que sé de plataformas y servidores, porque dónde despliegas condiciona todo el stack. Por defecto propone Cloudflare, que en la práctica es lo más barato para la mayoría de proyectos web: capa gratuita generosa, sin coste por tráfico de salida y red global. Pero si prefieres otra, la decisión queda como ADR. Cada una tiene su sitio y su letra pequeña:

Cloudflare: webs, APIs, sitios estáticos y lógica en el edge. Ojo: el runtime de Workers no es Node, así que algunos paquetes de npm fallan, y hay límites de CPU.
Vercel: Next.js sin configurar nada y despliegues de previsualización. El coste crece rápido con el tráfico.
AWS: cargas complejas o reguladas y entornos de empresa. A cambio, complejidad y facturas sorpresa, así que pide infraestructura como código y alertas de coste.
Hetzner: VPS y servidores dedicados baratos, datos en la Unión Europea y procesos que corren sin parar. Pero lo gestionas todo tú: actualizaciones, copias de seguridad, escalado y seguridad.
DigitalOcean: el término medio, con VPS sencillos, PostgreSQL gestionado y App Platform.

Y en la entrevista pregunta lo que de verdad decide la plataforma: el tráfico y el crecimiento esperados, el presupuesto, si los datos tienen que quedarse en Europa, si hay procesos largos o de mucha CPU y, sobre todo, quién va a mantenerlo. Si nadie tiene tiempo para administrar servidores, mejor algo gestionado.

Las reglas que se aplican siempre, también en los scripts

Hay un bloque de reglas que no depende del tamaño de la tarea:

Código pensado para que lo lean humanos: nombres que explican lo que hacen, funciones que hacen una sola cosa y comentarios que cuentan el por qué, no el qué.
En inglés el código, los identificadores, los comentarios, los commits y los nombres de los documentos.
Seguro por defecto: validar la entrada en los bordes, consultas parametrizadas, secretos fuera del código y el mínimo privilegio.
Coste computacional: saber la complejidad de lo que escribe y no optimizar antes de medir.
Documentación oficial antes que la memoria del modelo, citando la URL cuando la solución no es obvia.
Linter obligatorio en los proyectos.

Pragmatismo por encima del dogma

Esta es la regla que más me importa. Arquitectura hexagonal y SOLID donde hay dominio, no en una landing de Astro. DRY con la regla de tres: duplicas una vez y abstraes a la tercera. YAGNI. Y cuando hay empate, gana KISS.

He visto demasiados proyectos pequeños con cuatro capas, seis interfaces y una factoría para crear un objeto que solo se crea en un sitio. Todo muy SOLID, todo muy limpio en el diagrama, y para cambiar un texto había que tocar cinco archivos. Los patrones son herramientas, no una religión: se usan cuando resuelven un problema que tienes, no uno que algún día podrías tener. Y la Inteligencia Artificial, si no le dices nada, tiende a lo contrario: te monta la catedral entera aunque le hayas pedido una caseta.

La autorrevisión antes de entregar

Antes de darte nada por terminado, Claude pasa una lista de comprobación:

El linter y el formateador pasan, y los tests también.
Cada criterio de aceptación está cubierto por un test.
El código se lee bien: nombres claros, funciones pequeñas, nada de código muerto.
El checklist del OWASP Top 10.
El coste: sin consultas N+1, sin O(n²) innecesarios y con la entrada y salida agrupada.
Logs en los puntos clave y sin secretos ni datos personales.
El inventario, el contrato de la API y el estado de la spec, al día.

Qué deja creado en tu proyecto

Al terminar la primera vuelta, el proyecto tiene esto:

CLAUDE.md                     ## Engineering conventions
docs/INVENTORY.md
docs/adr/README.md + NNNN-*.md
docs/specs/NNNN-*/{spec,design,tasks}.md
docs/api/openapi.yaml         (if there is an API)
tests/load/                   (if load targets exist)

Una carpeta docs/ que cualquiera (persona o Inteligencia Artificial) puede leer para entender qué se hizo y por qué, sin tener que adivinarlo.

Cómo está hecha por dentro (y por qué así)

El SKILL.md es corto, ±140 líneas, y el detalle vive en 16 archivos dentro de references/ que solo se cargan cuando hacen falta: la plantilla de ADR, el checklist de OWASP, la guía de tests, el diseño de APIs, las plataformas de despliegue, las convenciones de nombres por lenguaje… Claude lee siempre la descripción corta de cada skill instalada, así que meterlo todo en un único archivo sería gastar contexto en cada conversación para nada.

Los valores por defecto (framework, base de datos, plataforma y herramientas por tipo de proyecto) están en references/stack.md, y se pueden cambiar. Las filas marcadas como TODO hacen que Claude te pregunte y te proponga dos o tres opciones.

La skill la fuimos definiendo en una conversación con Claude, en modo plan, añadiendo requisitos poco a poco hasta tener el plan completo antes de escribir nada. Que, ahora que lo pienso, es exactamente lo que la skill obliga a hacer.

Si en tu empresa queréis que los asistentes de código trabajen con este tipo de reglas, hablamos.

Cómo instalar senior-mindset

La forma recomendada es el marketplace de plugins, porque luego actualizar es un comando:

/plugin marketplace add MarcosRamirez/SKILLS
/plugin install senior-mindset@marcosramirez-skills

También puedes pedírselo al propio Claude Code, pegando la URL de la skill:

Install the senior-mindset skill from https://github.com/MarcosRamirez/SKILLS/tree/master/skills/senior-mindset
into ~/.claude/skills/senior-mindset. Copy the whole folder, including references/.

O hacerlo a mano:

git clone --depth 1 https://github.com/MarcosRamirez/SKILLS.git /tmp/skills
cp -r /tmp/skills/skills/senior-mindset ~/.claude/skills/senior-mindset

Si la instalas a mano, la carpeta references/ tiene que ir con ella: el SKILL.md carga esos archivos cuando los necesita.

Se activa sola cuando le pides construir algo: “crea una aplicación para gestionar reservas”, “programa un worker que procese imágenes”, “nueva feature”. Es la segunda skill del repo, después de save-image, la que guarda sola en disco las capturas que pegas en Claude Code, y se instala igual. Todo el código está en github.com/MarcosRamirez/SKILLS, con licencia MIT.

Preguntas frecuentes

¿Qué es senior-mindset para Claude Code?

Es una skill que hace que Claude Code programe como un senior pragmático por defecto: distingue scripts de proyectos, te entrevista una vez por proyecto, escribe la spec antes que el código, guarda las decisiones como ADRs, reutiliza lo que ya existe y revisa seguridad, tests y logs antes de entregar.

¿senior-mindset se aplica también a scripts pequeños?

Solo en parte. Para un script suelto se salta la entrevista, las specs, los ADRs y el linter, pero mantiene las reglas básicas: código legible, en inglés, seguro y con atención al coste computacional.

¿Qué es un ADR y por qué no se edita?

Un ADR (Architecture Decision Record) es un documento corto que recoge una decisión de arquitectura y su motivo. senior-mindset no los edita nunca: si una decisión cambia, escribe un ADR nuevo y marca el anterior como sustituido, para que no se pierda el historial de por qué se hizo cada cosa.

¿Puedo cambiar el stack que propone por defecto?

Sí. Los valores por defecto están en el archivo references/stack.md de la skill. Las filas marcadas como TODO hacen que Claude te pregunte y te proponga dos o tres opciones en lugar de decidir por ti.

Fuentes

Compártelo si te ha resultado útil.

¿Qué es lo que más te desespera del código que te genera la Inteligencia Artificial? Cuéntame.

Y… si la pruebas, cuéntame qué tal se porta.