Qué hace
Le pedís a tu agente $atlify (Codex) o /atlify (Claude Code) y, en vez de leer archivo por archivo, recibís un único HTML que funciona sin internet con:
- El mapa del sistema: frontend, backend y base de datos, con quién llama a quién.
- El recorrido de cada endpoint, paso a paso, desde el componente de pantalla hasta la tabla, con el código real de cada paso y una pregunta para pensar.
- Los problemas que encontró: seguridad, datos, errores, rendimiento y diseño. Cada uno trae el archivo, el símbolo, el escenario en que falla y el arreglo mínimo.
- El modo "Antes de tocarlo", para arreglar un endpoint en un repo gigante: qué otras rutas comparten sus funciones y tablas, y qué referencias a tests se descubren (sin ejecutarlos).
Sirve si heredaste un repo, si lo armaste rápido con IA y ahora lo querés seguir en serio, o si tenés que tocar algo sin romper otra cosa.
| Resumen | Hallazgos |
|---|
| |
| Mapa | Antes de tocarlo (--endpoint) |
| |
Instalación
Requiere Git, Python 3.10 o superior y un agente con soporte de skills y ejecución de comandos. Los scripts no necesitan paquetes de Python extra. El instalador usa una shell POSIX (macOS/Linux; WSL en Windows). El agente puede tener su propio costo.
git clone https://github.com/miguelecf/atlify.git
cd atlify && ./install.sh
install.sh enlaza el skill en ~/.agents/skills/atlify y en las carpetas de skills que ya existan para estos agentes:
| Agente | Carpeta | Cómo se usa |
|---|
| Claude Code | ~/.claude/skills | /atlify |
| Codex | ~/.codex/skills | $atlify |
| Pi | ~/.pi/agent/skills | "usá atlify para generar el atlas de este repo" |
| OpenCode | ~/.config/opencode/skills | ídem |
| Gemini CLI | ~/.gemini/skills | ídem |
| Cualquier otro | ~/.agents/skills | apuntá tu agente a esa carpeta |
./install.sh --only claude,codex # solo algunos agentes
./install.sh --copy # copia en vez de enlazar
./install.sh --uninstall # quita solo lo que instaló
python3 scripts/atlify.py doctor # comprueba Python y los archivos del skill
Uso
/atlify # todo el repo
/atlify --endpoint "POST /api/orders" # un endpoint y su impacto, para un fix chico
/atlify --actualizar # re-corre extract, lista los cambios y el agente actualiza el atlas
Todo se escribe en .atlify/ dentro del repo analizado: atlas.json (la fuente, que se puede versionar), atlas.html (el visor) y, si lo pedís, plan.md con el plan de arreglo para que lo ejecute el agente que prefieras.
En un repo grande (más de 40 endpoints), Atlify no intenta todo de una: agrupa los endpoints por funcionalidad y te propone hacerlas de a una.
Cómo funciona
extract el agente validate build
repo ─────────────────▶ esqueleto ───────────▶ atlas.json ─────────────▶ OK ──────────────▶ atlas.html
rutas, llamadas, + TO REVIEW lee el código, ¿existe cada copia las líneas
tablas, imports escribe textos archivo, símbolo reales y arma
y hallazgos y endpoint? el visor offline
- Extraer. Scripts deterministas detectan rutas, llamadas HTTP del frontend, tablas y quién llama a quién. Marcan lo sospechoso: una llamada a una ruta que no existe o un endpoint que nadie usa.
- Leer con criterio. El agente sigue cada recorrido y escribe lo que solo se ve leyendo: por qué está hecho así, dónde falla y cómo se arregla.
- Validar y construir. Cada cita se comprueba contra el código real. Si un archivo, un símbolo o un endpoint no existe, el HTML no se genera.
Fiable por diseño
- Solo lectura. Escribe únicamente en
.atlify/. No arregla nada por su cuenta.
- No ejecuta tu código, no corre tus tests ni instala dependencias.
- El repo es dato, no instrucción. Si un README o un comentario le pide al agente que no reporte algo, lo ignora y lo avisa. El repo de ejemplo de los evals trae una instrucción así plantada a propósito.
- Referencias verificadas.
validate comprueba archivos, símbolos, rangos y endpoints; rechaza rutas fuera del repo y nombres de archivos sensibles reconocidos. Esto no demuestra que toda explicación del agente sea correcta ni detecta secretos dentro de cualquier archivo permitido.
- Probado. 11 errores plantados en un repo de ejemplo, tests de los scripts y tests E2E del visor en escritorio y celular.
Stacks
| Detecta solo | Con ayuda del agente |
|---|
| Python / FastAPI, Java / Spring, JS / TS / React | Express, Fastify, Django, Jinja + HTMX y otros: el agente completa lo que el extractor no ve, siguiendo references/edge-cases.md |
Estructura
SKILL.md el contrato que lee el agente
references/ detalle que se carga cuando hace falta
scripts/atlify.py CLI: extract, validate, build, doctor
assets/visor.html el visor (Preact + htm embebidos, sin build)
evals/ tests de scripts, E2E y casos de comportamiento
docs/ el sitio y la demo
install.sh instalador para todos los agentes
¿Querés entender cómo está hecho, o armar un skill parecido? Leé ESTUDIAR.md: un recorrido guiado por el código, con las ideas que podés llevarte a otros skills.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
