explore-codebase
npx machina-cli add skill 686f6c61/alfred-dev/explore-codebase --openclawExplorar base de código
Resumen
Este skill se ejecuta antes de tocar cualquier línea de código existente. Su propósito es entender el contexto: cómo está organizado el proyecto, qué patrones sigue, qué convenciones usa y dónde están los puntos críticos. Modificar código sin entender su contexto es la receta para introducir bugs y romper convenciones.
La exploración no modifica nada. Solo lee, analiza y documenta hallazgos que servirán de guía para los cambios posteriores.
Proceso
-
Mapear la estructura del proyecto. Revisar el árbol de directorios para entender la organización general. Identificar:
- Punto de entrada de la aplicación (main, index, app).
- Estructura de capas o módulos (src/, lib/, services/, etc.).
- Ubicación de tests (tests/, tests/, .test., .spec.).
- Configuración (package.json, tsconfig, Cargo.toml, pyproject.toml, etc.).
- Documentación existente (docs/, README, CONTRIBUTING).
-
Leer la configuración del proyecto. Los ficheros de configuración revelan decisiones importantes:
- Dependencias y sus versiones.
- Scripts disponibles (build, test, lint, format).
- Configuración de linter y formatter (estilo de código).
- Configuración de TypeScript, Babel u otros transpiladores.
-
Identificar patrones y convenciones. Leer 3-5 ficheros representativos del código para detectar:
- Estilo de nomenclatura (camelCase, snake_case, PascalCase).
- Patrón de arquitectura (MVC, hexagonal, clean architecture, etc.).
- Patrón de manejo de errores (excepciones, Result types, códigos de error).
- Patrón de inyección de dependencias.
- Formato de imports y exports.
-
Revisar los tests existentes. Los tests son la mejor documentación del comportamiento esperado:
- Framework de testing utilizado.
- Estilo de los tests (AAA, Given/When/Then, BDD).
- Cobertura: qué áreas tienen tests y cuáles no.
- Fixtures, mocks y utilidades de test.
-
Mapear dependencias del área a modificar. Para el módulo o fichero concreto que se va a cambiar:
- Qué otros módulos lo importan (dependientes).
- Qué módulos importa él (dependencias).
- Interfaces públicas que no se pueden romper sin afectar a dependientes.
-
Documentar hallazgos. Resumir en un comentario o mensaje al usuario:
- Patrones detectados que hay que seguir.
- Riesgos identificados (áreas sin tests, acoplamiento fuerte).
- Convenciones de naming y formato a respetar.
- Cualquier "trampa" o peculiaridad del código.
Criterios de éxito
- Se ha revisado la estructura general del proyecto.
- Se han identificado patrones y convenciones existentes.
- Se han leído los tests relacionados con el área a modificar.
- Se han mapeado las dependencias del módulo objetivo.
- No se ha modificado ningún fichero durante la exploración.
- Los hallazgos están documentados antes de empezar a hacer cambios.
Source
git clone https://github.com/686f6c61/alfred-dev/blob/main/skills/desarrollo/explore-codebase/SKILL.mdView on GitHub Overview
Este skill se ejecuta antes de modificar código existente para entender el contexto: estructura del proyecto, convenciones y puntos críticos. Permite mapear dependencias, identificar patrones y documentar hallazgos sin cambiar nada, evitando bugs y violaciones de normas.
How This Skill Works
Analiza el árbol del proyecto y revisa ficheros de configuración (package.json, tsconfig, etc.) para extraer patrones de nomenclatura y arquitectura leyendo 3-5 archivos representativos. Revisa las pruebas para entender el comportamiento esperado y mapea dependencias y exportaciones para no romperlas.
When to Use It
- Antes de empezar una nueva implementación o refactor
- Cuando te unes a un código base por primera vez
- Antes de realizar cambios en un módulo crítico
- Para evaluar impactos y dependencias antes de un PR
- Al documentar o preparar guías de estilo y convenciones
Quick Start
- Step 1: Abre el repositorio y navega al directorio del skill
- Step 2: Ejecuta una exploración leyendo estructura, configuración y tests
- Step 3: Genera un resumen de hallazgos y recomendaciones de cambios
Best Practices
- Leer 3-5 archivos representativos para detectar convenciones
- Revisar la configuración de dependencias y scripts
- Mapear entradas y salidas de cada módulo
- Verificar dónde están las pruebas y su cobertura
- Documentar hallazgos claros y accionables
Example Use Cases
- En un proyecto Node/TS, mapear la estructura de src, tests y configs antes de refactorizar
- Antes de migrar una función a un servicio, entender dependencias
- Al entender un monolito para dividirlo en microservicios
- Antes de modificar un código con manejo de errores complejo
- Al añadir nuevas librerías, verificar impacto en patrones y convenciones
