✈️ El Piloto

Tú ya sabes cómo funciona tu proyecto. Ese es el problema.

El Piloto corre tu onboarding como si fuera la primera vez: una sesión de agente sin memoria, sin CLAUDE.md y sin acceso a tu código sigue tu README al pie de la letra dentro de un sandbox desechable, y reporta cada punto donde tuvo que adivinar algo.

El resultado es un veredicto con evidencia: ¿está listo para publicar, o falta pulir el README primero?

No necesitas una API key nueva. Usa el Claude Code que ya tienes instalado y configurado — tu propia suscripción, sin nada extra que pagar ni configurar.

Nunca toca tu repo. Todo pasa sobre una copia efímera que se destruye al terminar.

Uso

# Antes de publicar: prueba tu propio proyecto
el-piloto --local ./mi-proyecto

# Valida la experiencia real de alguien que clona tu repo público
el-piloto --repo https://github.com/usuario/repo

# Recorre los hallazgos uno por uno, sin muro de texto
el-piloto --local ./mi-proyecto --tour

| Opción | Qué hace | Default | |---|---|---| | --local <ruta> | Copia una carpeta local al sandbox, como si acabara de clonarse | — | | --repo <url> | Clona un repo de GitHub dentro del sandbox | — | | --readme <archivo> | Cuál archivo tratar como el README objetivo | README.md | | --alcance <modo> | estricto (solo el README) · ampliado (+ lo que el README nombre) | estricto | | --salida <ruta> | Dónde guardar el reporte | ./.el-piloto | | --tour | Recorrido interactivo, hallazgo por hallazgo | — | | --json | Imprime el JSON por stdout | — | | --desatendido | Sin preguntas ni pausas | — |

Código de salida: 0 listo · 1 mejorable o revisión parcial · 2 no publiques · 3 no se pudo evaluar.

El problema que resuelve

Después de construir algo, eres la peor persona para juzgar tu propio onboarding: ya sabes cómo funciona todo, así que no puedes ver dónde se atasca alguien que lo ve por primera vez. Hoy esa fricción se descubre tarde — dos días después de publicar, en un comentario confundido de alguien que no pudo arrancar.

El Piloto adelanta ese descubrimiento al momento antes de publicar.

Por qué no basta con "pídele a un LLM que siga tu README"

Aquí está la parte difícil, y es el corazón de la herramienta.

Un modelo sin ningún contexto de tu proyecto sigue siendo alguien con muchísimo conocimiento de desarrollo. Si tu README dice "instala las dependencias" sin decir con qué gestor, va a escribir npm install sin pestañear — igual que cualquier desarrollador con experiencia. Termina el onboarding, no encuentra ninguna fricción, y te devuelve un sello de aprobación vacío.

Pero buena parte de quien lee tu README apenas está empezando. Para esa persona, ese "obviamente es npm install" no es obvio en absoluto.

La solución no es pedirle al agente que finja no saber nada — eso no es creíble ni consistente de una corrida a otra. Es exigirle honestidad radical sobre el origen de cada acción: antes de ejecutar cada paso, tiene que declarar si el README lo especifica al 100% o si tuvo que rellenar algo con conocimiento propio, por trivial que le parezca.

Esa auto-declaración es el dato que nos interesa. No si logró completar el onboarding, sino cuánto tuvo que poner de su parte para lograrlo.

Y para que no dependa de que el agente "se acuerde"

Pedírselo en el prompt no basta: en medio de una tarea larga, un modelo se olvida. Así que el reporte no se pide en texto libre — se fuerza con un candado.

El piloto no tiene Bash, ni Read, ni ninguna herramienta de Claude Code. Su universo entero son seis herramientas nuestras. Cuando ejecuta una acción, el sistema queda en deuda; hasta que no llame a reportar_paso con el esquema completo, cualquier otra cosa que intente —incluido terminar— le devuelve un error. No puede avanzar.

Por eso clasificar cada paso como 🔴/🟡/🟢 es un proceso 100% determinístico sobre esa estructura, y no depende de interpretar la prosa del agente.

Qué encuentra

| Tipo | Definición | Ejemplo real | |---|---|---| | asuncion_no_declarada | Funcionó, pero por conocimiento propio que el README no daba | "Instala las dependencias" sin decir con qué gestor | | prerequisito_faltante | Hace falta algo que el README nunca menciona | El proyecto necesita Node 20+ y no lo dice | | comando_roto | El comando tal cual está escrito falla | npm run dev cuando el script se llama start:dev | | paso_ambiguo | Hay más de una forma razonable de interpretarlo | "Configura tu base de datos" sin decir dónde | | salto_de_contexto | Asume un concepto externo sin explicarlo | "Corre las migraciones" sin decir qué son | | verificacion_no_declarada | Funcionó, pero no dice cómo confirmar que salió bien | npm run dev sin decir qué deberías ver |

Severidad, determinada por la estructura del reporte, no por su tono:

• 🔴 Crítico — falló, o es comando_roto / prerequisito_faltante (bloquean por definición)
• 🟡 Advertencia — hubo que rellenar un hueco del README con conocimiento propio
• 🟢 Informativo — hay algo que señalar, pero no se infirió nada y funcionó

requirioInferencia es la bisagra entre 🟡 y 🟢 — y es exactamente el dato que hace útil toda la revisión.

Veredicto:

| Condición | Recomendación | |---|---| | 0 🔴 y 0–2 🟡 | ✅ Listo para publicar | | 0 🔴 y 3+ 🟡 | 🔧 Funciona, pero mejora el README | | 1+ 🔴 | 🛑 No publiques todavía | | 1+ paso pendiente de un humano | ⚪ Revisión parcial | | 0 pasos ejecutados | ⚠️ No se pudo evaluar |

Cómo se garantiza que no hace trampa

Un piloto que puede leer tu CLAUDE.md no está midiendo tu README: está midiendo tu CLAUDE.md. Tres capas independientes lo impiden, y ninguna depende de que el modelo se porte bien:

1. Los spoilers no llegan al sandbox. CLAUDE.md, AGENTS.md, .cursorrules, .claude/, .cursor/… se filtran durante la copia. No es que el agente no pueda leerlos: no existen donde él puede mirar. Todo lo excluido queda listado en el reporte como evidencia.
2. La lectura pasa por una lista blanca. En estricto, solo el README. En ampliado, el README y lo que el README nombre. Un README que diga "revisa CLAUDE.md" no abre esa puerta.
3. Un hook PreToolUse deniega todo lo que no sea del piloto. Es la única capa que corre antes que cualquier otra evaluación de permisos, así que si una versión futura del SDK reintrodujera un Bash o un Read por su cuenta, ahí se detiene.

Además, el sandbox se copia sin node_modules ni dist — porque un clon recién hecho no los tiene. Si los copiáramos, npm run dev funcionaría de una y jamás descubriríamos que el README olvidó decir "instala las dependencias".

Lo que nunca hace

• Nunca inventa ni usa credenciales. Un paso que pide login, un CAPTCHA, un pago o un 2FA se detiene y te lo muestra para que lo resuelvas tú. Esos pasos van en su propia categoría — no cuentan como fricción del README, porque no son un problema de documentación sino un límite real de lo que un agente puede probar solo.
• Nunca publica nada. git push, npm publish y compañía están en la lista negra.
• Nunca modifica tu proyecto. Ni el onboarding ni el reporte: la salida va a la carpeta desde donde corriste el comando.
• Nunca navega a internet de verdad. El navegador headless solo abre localhost.
• Nunca arregla el proyecto. Su trabajo es encontrar dónde se atasca alguien nuevo, no desatascarlo.

El navegador se descarga solo si lo necesitas

Playwright no es una dependencia de El Piloto. Si tu proyecto es una CLI, nunca pagas ese peso.

La primera vez que un README manda abrir una URL, El Piloto te pregunta antes de descargar solo Chromium (no los tres navegadores). Se guarda en su caché y sirve para todas las corridas futuras. Si dices que no, ese paso queda marcado como pendiente y el onboarding sigue. En una corrida desatendida no descarga nada.

Aislamiento

Por defecto, una carpeta temporal más una lista negra de comandos: nadie tiene que instalar nada. El aislamiento es menor que con un contenedor y está dicho a propósito — pero siempre sobre una copia, nunca sobre tu repo. Para quien quiera más y ya lo tenga, --docker queda disponible como opción, nunca como requisito.

Límites por corrida: 25 pasos · 15 minutos en total · 5 minutos por paso. Alcanzarlos no es un error de la herramienta: es un hallazgo. Un onboarding que no cabe en 25 pasos ya te está diciendo algo.

Ejemplo real

Corriéndolo contra el README de El Filtro, otro proyecto de la suite:

🛑 No publiques todavía
8 pasos en 204s · 🔴 5 críticos · 🟡 2 advertencias

🔴 Paso 6 — prerequisito_faltante
  > "## Desarrollo ⏎ npm install"
  El README pone `npm install` al final, bajo "Desarrollo", sin decir que sea
  prerrequisito de los comandos `npx el-filtro` de arriba. El orden real de los
  pasos es el inverso al del documento.

Ese hallazgo estaba invisible para quien escribió el README, porque ya tenía el proyecto instalado.

Limitaciones conocidas

• Necesita Claude Code instalado y con sesión iniciada. Es el motor del piloto.
• La copia temporal aísla menos que un contenedor. Cubierto por lista negra de comandos y cwd fijo; --docker para quien quiera más.
• El agente podría reportar un paso con datos inexactos. Que declare bien es un juicio del modelo. Lo que sí está garantizado es que declare siempre y con estructura — el candado no admite pasos sin reportar.
• Proyectos que solo se prueban con interfaz gráfica real (una app de escritorio, una extensión que hay que cargar a mano) se marcan como pendientes de un humano.
• V1 evalúa un solo README a la vez y no lo corrige: el reporte es el insumo, arreglarlo sigue siendo un paso aparte.

Desarrollo

npm test          # build + suite completa
npm run test:watch
npm run dev -- --local ../mi-proyecto

350 tests, ninguno de los cuales gasta un token: el agente entra inyectado, así que el candado, el sandbox, el alcance y la clasificación se prueban con guiones de llamadas a herramientas. Lo que sí depende del modelo se verifica con una corrida real contra un README conocido.

Licencia

MIT