Empieza aquí 🌱 · Revisor de arquitectura senior

Abre esta carpeta con Claude Code o Cowork y dile a tu asistente: "siembra esta semilla 🌱"

Con eso basta de tu parte. Tu asistente hace todo lo técnico por ti; tú solo confirmas cuando te pregunte. Si ves algunas palabras en inglés en la pantalla, ni caso: él te guía.

¿Otras formas de pedirlo? "instala esta semilla", "activa este revisor", "pon al revisor de arquitectura a funcionar". Te entiende igual.

¿Qué es y qué resuelve?

Por qué existe. Cuando tomas una decisión técnica —agregar una librería, meter una caché, crear una abstracción "por si algún día", aceptar un atajo para salir del paso— casi siempre estás solo. No tienes al lado a un ingeniero con veinte años de callo que te diga, sin rodeos y con evidencia, si eso es una buena idea o una bomba de tiempo. Y tu asistente, por complaciente, suele decirte que sí a casi todo.

Qué hace esta semilla. Instala un revisor de arquitectura senior: un evaluador que juzga tus decisiones técnicas con dos exigencias que no negocia. La primera es elegancia: la solución más simple que resuelve el problema real y que hasta un principiante entiende en cinco minutos. La segunda es evidencia: no opina de memoria, verifica contra la documentación oficial de tus herramientas antes de recomendarte nada.

Su regla más útil: la del atajo. Cuando propones algo que se siente "hacky", primero te pone enfrente la alternativa elegante y te explica cuánto te costaría el atajo (en bugs, en mantenimiento, en deuda). Pero —y esto es lo valioso— si la alternativa elegante resulta ser sobre-ingeniería para tu caso real, defiende la simplicidad y te aprueba el atajo, diciéndote por qué. No es un purista dogmático: es un pragmático con criterio. No escribe código de producción; su trabajo es marcarte el estándar y darte el veredicto con el que tú decides.

Para el asistente que siembra 🤖

Eres el asistente. Sigue estos pasos con precisión. Esto es un agente (un subagente con nombre propio), no un hook ni un script: se instala copiando un solo archivo Markdown a la carpeta de agentes del usuario. La plataforma lo descubre sola al leer esa carpeta. Sin chmod y sin settings.json.

Paso 1 · Copiar el archivo del kernel

El kernel principal es un solo archivo: kernel/tech-lord.md. Cópialo a la carpeta de agentes del usuario según su plataforma.

• macOS / Linux (Claude Code o Cowork):

  mkdir -p ~/.claude/agents
  cp kernel/tech-lord.md ~/.claude/agents/tech-lord.md
  

• Windows (Claude Code o Cowork):

  mkdir -p "$USERPROFILE/.claude/agents"
  cp kernel/tech-lord.md "$USERPROFILE/.claude/agents/tech-lord.md"
  

• Codex: Codex no maneja "subagentes con nombre" como Claude Code. Ahí no se copia como agente: pega el contenido de kernel/tech-lord.md dentro de tu archivo de instrucciones AGENTS.md (o guárdalo aparte en el proyecto y agrégale un puntero), para que el método de revisión se cargue con el resto de tus instrucciones y lo apliques tú mismo cuando toque evaluar una decisión técnica.

Paso 2 · Aterrizar el stack y las fuentes (opcional pero recomendado)

El kernel ya trae todo el método adentro, así que funciona sin configurar nada. Si el usuario quiere que el revisor apunte a SU stack real y verifique contra SUS fuentes oficiales, abre kernel/stack-canonico.ejemplo.md: ahí se anota el stack por capa, las fuentes oficiales a verificar y las convenciones de arquitectura que su proyecto siempre respeta. Cópialo a una carpeta del usuario (por ejemplo ~/.claude/tech-lord/stack.md) y reemplaza los <placeholders> por lo real. Si el usuario no sabe qué poner, no pasa nada: deja el método base y el revisor sigue sirviendo.

Paso 3 · Verificación post-siembra (obligatoria)

No declares "listo" sin correr esto. Confirma que el archivo llegó a su sitio y que su encabezado (frontmatter) quedó bien formado.

grep -m1 '^name:' ~/.claude/agents/tech-lord.md

Salida esperada:

name: tech-lord

En Windows, cambia ~ por "$USERPROFILE". Si no imprime nada, revisa que el archivo se haya copiado a la carpeta agents (no a hooks) y que el nombre sea exactamente tech-lord.md. En Claude Code, el comando /agents debe listar tech-lord entre los agentes disponibles; si aparece ahí, ya se puede invocar.

Prueba de comportamiento (recomendada): en una sesión nueva, pídele al usuario que te plantee una decisión técnica con un atajo evidente, por ejemplo: "quiero crear una interfaz súper genérica para soportar cualquier proveedor de pagos en el futuro, aunque hoy solo uso uno", y dile "que el revisor de arquitectura evalúe esto". La conducta correcta es que el agente te ofrezca la ruta más simple, nombre YAGNI y te advierta de la sobre-ingeniería con su razonamiento, en vez de aplaudir la idea. Si hace eso, quedó sembrado.

Ajustes opcionales que el usuario puede pedirte después

• Modelo — la línea model: opus. Revisar arquitectura es una tarea de razonamiento, por eso el default es un modelo fuerte; cámbiala si el usuario prefiere otro.
• Aprendizajes — el placeholder <TU-ARCHIVO-DE-APRENDIZAJES> es opcional; sirve si el usuario quiere que el revisor acumule los criterios de arquitectura que ya validó. Si no le interesa, déjalo tal cual o borra esa línea: el agente ya trae memory: project para memoria automática por proyecto.

¿Cómo sé que funcionó?

Cuando tu asistente termine, pídele que corra la verificación de arriba y te muestre el resultado. Si aparece name: tech-lord, ya quedó sembrado.

De ahí en adelante, cada vez que estés por tomar una decisión técnica de peso —agregar una librería, meter una caché, crear una abstracción, aceptar un atajo— dile a tu asistente algo como: "antes de seguir, que el revisor de arquitectura evalúe esto". Vas a recibir un veredicto corto y honesto: cuál es el problema real, la recomendación más simple que sirve, los compromisos con nombre y apellido, y las fuentes oficiales que lo respaldan. Lo que no va a pasar —y ese es justo el punto— es que alguien te diga que sí a todo y te enteres del problema cuando ya lo estás pagando. 🌱