Empieza aquí 🌱 · Revisor de primeros principios

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. Vas a ver algunas palabras en inglés en la pantalla; ni caso, él te va guiando.

¿Otras formas de pedírselo? "instala esta semilla", "activa este agente", "pon a funcionar el revisor de primeros principios". Te entiende igual.

¿Qué es y qué resuelve?

Por qué existe. Una idea puede sonar buenísima y aun así estar parada sobre un supuesto falso. El problema es que ese supuesto no se ve: la propuesta convence, le das luz verde, y el error aparece cuando ya gastaste tiempo, dinero o credibilidad. Casi siempre el hueco no estaba en cómo se iba a hacer, sino en por qué creíamos que iba a funcionar.

Qué hace esta semilla. Instala un agente revisor con una sola obsesión: ¿la lógica se sostiene desde el fondo?. Agarra tu propuesta y la desarma hasta sus piezas más pequeñas —los supuestos que ya no se pueden partir más— y a cada uno le exige la prueba: ¿de dónde sacamos que esto es cierto? Enséñame la fuente. Lo que tiene respaldo, lo marca en verde; lo que es una corazonada disfrazada de hecho, lo marca en rojo y te dice por qué. Y antes de dejarte avanzar, te avisa si la decisión es de las que se pueden deshacer (adelante, rápido) o de las que no (ahí sí, con calma y con evidencia).

En qué se distingue. No es el que pregunta "¿qué puede salir mal?" (ese busca los riesgos de ejecución). Este pregunta algo más de fondo: "¿estamos viendo bien lo que creemos ver?". Ataca el razonamiento, no la operación. Y trabaja en modo consejero: no aprueba ni ejecuta nada; solo te sube el nivel de evidencia para que tú decidas con más piso.

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 automáticamente 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/principles-counselor.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/principles-counselor.md ~/.claude/agents/principles-counselor.md
  

• Windows (Claude Code o Cowork):

  mkdir -p "$USERPROFILE/.claude/agents"
  cp kernel/principles-counselor.md "$USERPROFILE/.claude/agents/principles-counselor.md"
  

• Codex: Codex no maneja "subagentes con nombre" como Claude Code. Ahí no se copia como agente: pega el contenido de kernel/principles-counselor.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 revisar desde primeros principios se cargue con el resto de tus instrucciones y lo apliques tú mismo cuando toque juzgar una propuesta.

Paso 2 · Aterrizar las fuentes autoritativas (opcional pero recomendado)

El kernel ya trae el método completo dentro de sí mismo, así que funciona sin configurar nada. Si el usuario quiere que el revisor apunte a SUS fuentes, abre kernel/fuentes-autoritativas.ejemplo.md: ahí le dices qué cuenta como evidencia en su mundo (docs oficiales de sus herramientas, benchmarks, decisiones ya firmadas) y qué acciones son irreversibles en su contexto (sus "puertas de una vía"). Reemplaza los placeholders <URL o TU-RUTA>, <TU-RUTA> y <TU-ACCIÓN-IRREVERSIBLE> por lo real, y pega esas dos secciones dentro del kernel. Si el usuario no sabe qué poner, no pasa nada: deja las categorías genéricas y el agente 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/principles-counselor.md

Salida esperada:

name: principles-counselor

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 principles-counselor.md. En Claude Code, el comando /agents debe listar principles-counselor entre los agentes disponibles; si aparece ahí, ya se puede invocar.

Prueba de comportamiento (recomendada): en una sesión nueva, dale al usuario una afirmación que suene convincente pero sin fuente (por ejemplo "deberíamos hacer X porque es lo más rápido") y pídele: "revísalo desde primeros principios". La conducta correcta es que el agente descomponga la afirmación a supuestos, exija de dónde sale cada uno, marque el que no tiene fuente como débil, y clasifique la decisión como reversible o irreversible — no que diga "suena bien". Si hace eso, quedó sembrado.

Ajustes opcionales que el usuario puede pedirte después

• Modelo — la línea model: opus. Revisar lógica desde fundamentos es una tarea de razonamiento, por eso el default es un modelo fuerte; cámbiala si el usuario prefiere otro.
• Herramientas web — el kernel lista WebSearch y WebFetch para verificar afirmaciones contra docs oficiales en línea. Si la plataforma del usuario no las tiene, el agente degrada con gracia: pide la fuente/enlace al usuario en vez de darla por buena. Puedes quitar esas dos líneas si no aplican.
• Aprendizajes — el placeholder <TU-ARCHIVO-DE-APRENDIZAJES> es opcional; sirve si el usuario quiere que el agente recuerde premisas que ya resultaron falsas. 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: principles-counselor, ya quedó sembrado.

De ahí en adelante, cuando tengas una propuesta o decisión de peso y quieras saber si la lógica de verdad aguanta, dile a tu asistente algo como: "revisa esto desde primeros principios". Vas a recibir un reporte cortito: los supuestos sobre los que se para tu idea, cuáles tienen prueba y cuáles no (con la fuente en la mano), y si lo que estás por decidir se puede deshacer o no. Lo que no va a pasar —y ese es justo el punto— es que apruebes algo que sonaba impecable y descubras a medio camino que estaba parado sobre un supuesto que nadie verificó. 🌱