Cómo construimos RepoSherpa para on-boardear a ingenieros en minutos
En Q2BSTUDIO, empresa dedicada al desarrollo de software a medida, aplicaciones a medida y soluciones de inteligencia artificial para empresas, detectamos un problema recurrente: cada nuevo ingeniero preguntaba en Slack Dónde está el README y había que pegar manualmente el mismo enlace una y otra vez. La consecuencia eran horas desperdiciadas explicando cómo ejecutar tests o desplegar. RepoSherpa nace para eliminar ese cuello de botella respondiendo preguntas de onboarding directamente dentro de Slack, apoyado en la documentación del propio repositorio.
Arquitectura a alto nivel: pipeline de ingestión que clona el repo, trocea archivos markdown en fragmentos de aproximadamente 1KB con contexto de sección, genera embeddings con OpenAI text-embedding-3-large y guarda los vectores en PostgreSQL preparado para pgvector. En cada consulta se recuperan fragmentos relevantes y se construye un prompt para gpt-4o-mini con streaming de respuestas hacia Slack. La interfaz en Slack incluye comandos slash como /onboard, /readme y /repo-status y un manejador de menciones de app usando Slack Bolt sobre FastAPI. Tareas en segundo plano con Celery y Redis coordinan la ingestión, reindexados y refrescos programados.
Tecnología y piezas fundamentales: FastAPI expone la ruta /slack/events y rutas helper en modo desarrollo para probar sin Slack. Slack Bolt AsyncApp registra comandos y menciones delegando en un OnboardingService. Los archivos markdown se fragmentan y se enriquecen con embeddings almacenados en Postgres como JSON para mantener compatibilidad con SQLModel y facilitar búsquedas por similitud.
Retrieval augmented generation: cuando alguien escribe /readme Cómo ejecuto las migraciones, RepoSherpa localiza el mapeo repo-canal, ejecuta búsqueda por similitud sobre los fragmentos almacenados, genera un prompt que resume el contexto y la pregunta, llama a gpt-4o-mini en modo streaming y devuelve bloques de Slack con la respuesta final y citas de contexto.
Operaciones: workers de Celery gestionan embeddings, ingestión y reindexados programados; Redis actúa como broker y para locks distribuidos; Alembic maneja las migraciones de Postgres. Nombres de base de datos dependientes del entorno como sherpa_dev y sherpa_test aíslan a desarrolladores. Para desarrollo local levantamos uvicorn app.main:app con reload y celery -A worker.celery_app worker, exponemos FastAPI con ngrok y pegamos la URL de /slack/events en las suscripciones de eventos y comandos slash. Rutas dev como /dev/onboard y /dev/question permiten probar ingestión y recuperación sin Slack mientras ENVIRONMENT sea development.
Lecciones aprendidas: fragmentos pequeños sub-1KB reducen las alucinaciones manteniendo el contexto ajustado. El streaming de respuestas mejora la experiencia al verla construirse en real time. La higiene en comandos slash importa; todos comparten la misma Request URL por lo que documentamos scopes como chat:write y app_mentions:read y recordamos reinstalar la app tras cambios. Las APIs en modo dev quitan fricción para que el equipo pueda curlear endpoints de ingestión antes de integrar Slack.
Próximos pasos: almacenamiento nativo con pgvector para búsquedas ANN más rápidas, controles de acceso por canal para repositorios, triggers de webhook de Git para reindex automático cuando cambian docs y conectores adicionales como Confluence o Notion alimentando el mismo stack de recuperación.
Cómo probar RepoSherpa: es open source y compatible con Python 3.11. Clona el proyecto, configura las variables de entorno SLACK_BOT_TOKEN SLACK_SIGNING_SECRET OPENAI_API_KEY y DATABASE_URL y levanta el stack de desarrollo. En Q2BSTUDIO fomentamos contribuciones especialmente en estrategias de chunking, heurísticas de recuperación y nuevos flujos de Slack.
Por qué Q2BSTUDIO: además de construir herramientas que aceleran el onboarding y mejoran la productividad de equipos de ingeniería, ofrecemos servicios integrales como desarrollo de aplicaciones a medida, soluciones en inteligencia artificial para empresas, ciberseguridad y pentesting, y servicios cloud aws y azure. Integramos capacidades de inteligencia de negocio y Power BI para extraer valor de los datos y diseñamos agentes IA y automatizaciones que optimizan procesos.
Palabras clave relevantes para nuestro posicionamiento: aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA, power bi. Si quieres acelerar el onboarding de tus equipos con soluciones basadas en IA o desarrollar software personalizado que integre seguridad y nube, en Q2BSTUDIO podemos ayudarte.
Contacto y contribuciones: prueba RepoSherpa, adapta sus ideas a tus repositorios y si necesitas apoyo profesional en desarrollo a medida, inteligencia artificial, ciberseguridad o servicios cloud, visita nuestras páginas y habla con nuestro equipo para diseñar la solución que tu empresa necesita.
