Explora repo
Produce un mapa util de un codebase desconocido en una pasada. El objetivo no es listar carpetas: es que alguien pueda hacer su primer cambio despues de leerlo.
Regla base
Prioriza lo que el codigo hace sobre lo que el README dice que hace. Los READMEs mienten por omision; el codigo no.
Paso 1: orientarse (barato, primero)
ls -la
cat README* 2>/dev/null | head -60
git log --oneline -15
git log --format='%an' | sort | uniq -c | sort -rn | head -5 # quien mantiene esto
Identifica el stack por los archivos de manifiesto:
| Archivo |
Stack |
package.json |
Node / JS / TS. Mira scripts y dependencies |
pyproject.toml, requirements.txt |
Python |
go.mod |
Go |
Cargo.toml |
Rust |
composer.json |
PHP |
pom.xml, build.gradle |
Java / Kotlin |
Gemfile |
Ruby |
docker-compose.yml |
Servicios externos (DB, cache, colas) |
docker-compose.yml y .env.example son oro: te dicen de que depende el proyecto para arrancar.
Paso 2: encontrar el punto de entrada
No adivines. Buscalo:
- Node: campo
main/scripts.start en package.json, luego src/index.*, src/main.*, app.*
- Next.js / frameworks de archivos: la estructura de
app/ o pages/ es el enrutador
- Python:
if __name__ == "__main__", main.py, wsgi.py, asgi.py, manage.py
- Go:
func main() en cmd/
- Rust:
src/main.rs
grep -rn "if __name__" --include="*.py" . | head
grep -rln "func main()" --include="*.go" . | head
Paso 3: seguir un flujo completo de punta a punta
Esto es lo que separa un mapa util de un indice inutil. Elige una operacion representativa (un login, un listado, el endpoint mas obvio) y siguela:
peticion HTTP -> ruta -> middleware -> controlador -> servicio -> acceso a datos -> respuesta
Anota los nombres de archivo y linea reales de cada salto. Ese recorrido le ensena al lector el patron que sigue todo lo demas.
Paso 4: ubicar las piezas clave
- Modelo de datos: schemas, entidades, migraciones (
migrations/, prisma/schema.prisma, models/)
- Configuracion: como se leen las variables de entorno y cuales son obligatorias
- Autenticacion: donde se valida la sesion o el token
- Tests: donde viven, como se corren, y que tanto cubren de verdad
- Frontera con el exterior: llamadas a APIs de terceros, colas, webhooks
Paso 5: entregar el mapa
Formato de salida:
# <nombre del repo>
**Que es:** una frase. Que problema resuelve y para quien.
**Stack:** lenguaje, framework, base de datos, infra.
**Estado:** ultimo commit, frecuencia, cuanta gente lo toca.
## Como correrlo
Los comandos exactos, en orden, incluyendo dependencias externas.
## Arquitectura
Las 4-6 piezas reales y como se hablan entre si.
## Recorrido de ejemplo: <operacion>
Ruta completa con archivo:linea en cada salto.
## Donde tocar para...
| Quiero... | Voy a... |
|---|---|
| agregar un endpoint | `src/routes/`, luego `src/services/` |
| cambiar el modelo | migracion en `...`, entidad en `...` |
## Lo que me llamo la atencion
Deuda tecnica visible, patrones raros, cosas que parecen trampa.
Cuando el repo es grande
No leas todo. Muestrea:
- Los 10 archivos mas grandes (
find . -name "*.ts" -exec wc -l {} + | sort -rn | head)
- Los 10 archivos mas modificados (
git log --format= --name-only | sort | uniq -c | sort -rn | head). Ahi esta el corazon del proyecto
Errores comunes
- Pegar el arbol de directorios completo y llamarle mapa.
- Describir carpetas (
utils/ tiene utilidades) en vez de flujos.
- Confiar en los comandos del README sin verificar que los scripts existan en
package.json.
- Omitir las dependencias externas necesarias para arrancar (la DB, el Redis, el
.env).
1---2name: explora-repo3description: Levanta el mapa de un repositorio desconocido: arquitectura real, por donde entra una peticion, donde vive la logica de negocio, como se corre y como se testea. Pensado para el primer dia en un proyecto nuevo o para entender un repo de terceros. Usar cuando el usuario diga: "explicame este repo", "explora el proyecto", "no entiendo este codigo", "de que va este proyecto", "por donde empiezo", "onboarding", "primer dia", "como funciona este repo", "hazme un mapa del codigo", "donde esta la logica de".4---56# Explora repo78Produce un mapa util de un codebase desconocido en una pasada. El objetivo no es listar carpetas: es que alguien pueda **hacer su primer cambio** despues de leerlo.910## Regla base1112Prioriza lo que el codigo hace sobre lo que el README dice que hace. Los READMEs mienten por omision; el codigo no.1314## Paso 1: orientarse (barato, primero)1516```bash17ls -la18cat README* 2>/dev/null | head -6019git log --oneline -1520git log --format='%an' | sort | uniq -c | sort -rn | head -5 # quien mantiene esto21```2223Identifica el stack por los archivos de manifiesto:2425| Archivo | Stack |26|---|---|27| `package.json` | Node / JS / TS. Mira `scripts` y `dependencies` |28| `pyproject.toml`, `requirements.txt` | Python |29| `go.mod` | Go |30| `Cargo.toml` | Rust |31| `composer.json` | PHP |32| `pom.xml`, `build.gradle` | Java / Kotlin |33| `Gemfile` | Ruby |34| `docker-compose.yml` | Servicios externos (DB, cache, colas) |3536`docker-compose.yml` y `.env.example` son oro: te dicen de que depende el proyecto para arrancar.3738## Paso 2: encontrar el punto de entrada3940No adivines. Buscalo:4142- **Node**: campo `main`/`scripts.start` en `package.json`, luego `src/index.*`, `src/main.*`, `app.*`43- **Next.js / frameworks de archivos**: la estructura de `app/` o `pages/` **es** el enrutador44- **Python**: `if __name__ == "__main__"`, `main.py`, `wsgi.py`, `asgi.py`, `manage.py`45- **Go**: `func main()` en `cmd/`46- **Rust**: `src/main.rs`4748```bash49grep -rn "if __name__" --include="*.py" . | head50grep -rln "func main()" --include="*.go" . | head51```5253## Paso 3: seguir un flujo completo de punta a punta5455Esto es lo que separa un mapa util de un indice inutil. Elige **una** operacion representativa (un login, un listado, el endpoint mas obvio) y siguela:5657```58peticion HTTP -> ruta -> middleware -> controlador -> servicio -> acceso a datos -> respuesta59```6061Anota los nombres de archivo y linea reales de cada salto. Ese recorrido le ensena al lector el patron que sigue todo lo demas.6263## Paso 4: ubicar las piezas clave6465- **Modelo de datos**: schemas, entidades, migraciones (`migrations/`, `prisma/schema.prisma`, `models/`)66- **Configuracion**: como se leen las variables de entorno y cuales son obligatorias67- **Autenticacion**: donde se valida la sesion o el token68- **Tests**: donde viven, como se corren, y que tanto cubren de verdad69- **Frontera con el exterior**: llamadas a APIs de terceros, colas, webhooks7071## Paso 5: entregar el mapa7273Formato de salida:7475```markdown76# <nombre del repo>7778**Que es:** una frase. Que problema resuelve y para quien.79**Stack:** lenguaje, framework, base de datos, infra.80**Estado:** ultimo commit, frecuencia, cuanta gente lo toca.8182## Como correrlo83Los comandos exactos, en orden, incluyendo dependencias externas.8485## Arquitectura86Las 4-6 piezas reales y como se hablan entre si.8788## Recorrido de ejemplo: <operacion>89Ruta completa con archivo:linea en cada salto.9091## Donde tocar para...92| Quiero... | Voy a... |93|---|---|94| agregar un endpoint | `src/routes/`, luego `src/services/` |95| cambiar el modelo | migracion en `...`, entidad en `...` |9697## Lo que me llamo la atencion98Deuda tecnica visible, patrones raros, cosas que parecen trampa.99```100101## Cuando el repo es grande102103No leas todo. Muestrea:104- Los 10 archivos mas grandes (`find . -name "*.ts" -exec wc -l {} + | sort -rn | head`)105- Los 10 archivos mas modificados (`git log --format= --name-only | sort | uniq -c | sort -rn | head`). Ahi esta el corazon del proyecto106107## Errores comunes108109- Pegar el arbol de directorios completo y llamarle mapa.110- Describir carpetas (`utils/ tiene utilidades`) en vez de flujos.111- Confiar en los comandos del README sin verificar que los scripts existan en `package.json`.112- Omitir las dependencias externas necesarias para arrancar (la DB, el Redis, el `.env`).
eve-devs