Descubrimiento con IA

Connect a repository from the project settings to enable AI discovery

La función de Descubrimiento con IA de Archyl analiza tu código fuente para descubrir y documentar automáticamente tu arquitectura de software. Esto ahorra horas de trabajo de documentación manual y asegura que tu documentación de arquitectura se mantenga sincronizada con tu código real.

Cómo funciona

1. Conecta tu repositorio

Primero, conecta tu repositorio Git a Archyl:

  1. Ve a la configuración de tu proyecto
  2. Haz clic en "Conectar repositorio"
  3. Elige tu proveedor Git (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea o instancias autoalojadas)
  4. Autoriza a Archyl a acceder a tu repositorio

2. Inicia el descubrimiento

Una vez conectado, inicia el descubrimiento con IA:

  1. Haz clic en "Iniciar descubrimiento" en tu proyecto
  2. Selecciona qué rama analizar
  3. Haz clic en "Ejecutar descubrimiento"

3. Análisis con IA

La IA analiza tu código fuente en varias fases:

  1. Análisis de estructura — Identifica el nombre del sistema, los contenedores y las dependencias externas
  2. Descubrimiento detallado — Analiza los archivos fuente en bloques paralelos para encontrar componentes, elementos de código y relaciones
  3. Refinamiento de relaciones — Cruza los contenedores entre sí para encontrar dependencias entre servicios
  4. Post-análisis en paralelo — Descubre ADRs, documentación, contratos de API y dependencias de paquetes

Los elementos descubiertos incluyen:

  • Sistemas: Sistemas de software de nivel superior y dependencias externas
  • Contenedores: Servicios, APIs, bases de datos, aplicaciones web, workers
  • Componentes: Módulos, paquetes, handlers, repositorios, servicios
  • Elementos de código: Clases, interfaces y funciones con sus rutas de archivo
  • Relaciones: Cómo se comunican los elementos (usa, llama a, envía a, lee de)

4. Revisar y aprobar

Los descubrimientos se colocan en estado Pendiente para su revisión:

  1. Revisa cada elemento descubierto
  2. Edita nombres, descripciones o relaciones
  3. Aprueba los descubrimientos precisos
  4. Rechaza o modifica los incorrectos

En los proyectos nuevos (sin elementos C4 existentes), los descubrimientos se aprueban automáticamente para que puedas empezar rápido.

Descubrimiento incremental

El descubrimiento incremental mantiene tu modelo C4 actualizado analizando solo los archivos que cambiaron, no el repositorio completo. Es más rápido, más económico y puede ejecutarse automáticamente en cada push.

Cómo funciona el descubrimiento incremental

  1. Se hace push de código a la rama por defecto
  2. Archyl recibe el evento push (vía webhook o GitHub Action)
  3. Los archivos modificados se extraen de los commits del push
  4. Solo se analizan los archivos fuente (los archivos eliminados se omiten)
  5. La IA se ejecuta sobre el conjunto reducido de archivos
  6. Los nuevos elementos se crean como descubrimientos pendientes para su revisión
  7. Los elementos existentes se deduplican automáticamente, sin duplicados

Activar el descubrimiento incremental

Hay dos formas de activar el descubrimiento incremental:

Opción A: Webhook de GitHub (sin configuración)

  1. Ve a los ajustes de Configuración de webhooks de tu proyecto
  2. Activa Discovery on Push
  3. Copia la URL del webhook y añádela a la configuración de tu repositorio de GitHub
  4. Selecciona el evento push

Cada push a la rama por defecto disparará automáticamente el descubrimiento incremental.

Opción B: GitHub Action (CI/CD)

Añade la action Archyl Incremental Discovery a tu workflow. Consulta Integración con GitHub Actions para ver las instrucciones completas de configuración.

name: Architecture Sync
on:
  push:
    branches: [main]

jobs:
  discovery:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - uses: archyl/archyl/.github/actions/incremental-discovery@main
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: ${{ vars.ARCHYL_PROJECT_ID }}

Descubrimiento completo vs. incremental

Descubrimiento completo Descubrimiento incremental
Alcance Repositorio completo Solo archivos modificados
Disparador Manual (UI/API) Automático (webhook de push o GitHub Action)
Velocidad Minutos (depende del tamaño del repo) De segundos a minutos
Coste de IA Mayor (analiza todos los archivos) Menor (analiza solo el diff)
Caso de uso Configuración inicial, refactorizaciones importantes Cambios de código del día a día
Deduplicación Deduplicación completa frente al modelo existente La misma deduplicación, sin duplicados

Combinar completo e incremental

El flujo de trabajo recomendado:

  1. Ejecuta el descubrimiento completo cuando conectes un repositorio por primera vez
  2. Activa el descubrimiento incremental para mantener el modelo al día
  3. Vuelve a ejecutar el descubrimiento completo tras refactorizaciones o migraciones importantes

El descubrimiento incremental crea elementos pendientes igual que el descubrimiento completo: siempre revisas antes de que los cambios se apliquen a tu modelo C4.

Tecnologías soportadas

El Descubrimiento con IA funciona con más de 15 lenguajes y frameworks:

Lenguajes

Go, TypeScript, JavaScript, Python, Java, Kotlin, Rust, C#, C/C++, Ruby, PHP, Swift, Scala

Sistemas de build y gestores de paquetes

npm, Go modules, pip/Poetry, Maven, Gradle, Cargo, Composer, RubyGems, NuGet, CMake (find_package, FetchContent, CPM), Conan, vcpkg

Frameworks

React, Next.js, Vue, Angular, Express, Fastify, NestJS, Django, Flask, FastAPI, Spring Boot, ASP.NET Core, Ruby on Rails, Gin, Fiber

Infraestructura

Docker, Kubernetes, Terraform, Helm, Ansible, GitHub Actions, AWS CDK, Pulumi

Soporte de monorepos

Archyl detecta automáticamente las estructuras de monorepo:

  • Directorios apps/, packages/, services/, libs/
  • Muestreo proporcional de archivos entre servicios
  • Cada servicio se asigna a un contenedor distinto en el modelo C4
  • Se detectan las relaciones entre servicios

Buenas prácticas

Empieza por algo pequeño

Para bases de código grandes:

  1. Empieza con un solo servicio o módulo
  2. Revisa y refina los resultados
  3. Amplía gradualmente a otras áreas

Actualizaciones regulares

Mantén tu documentación al día:

  1. Activa el descubrimiento incremental para las actualizaciones automáticas
  2. Revisa con regularidad los descubrimientos pendientes
  3. Ejecuta el descubrimiento completo tras refactorizaciones importantes

Combínalo con el trabajo manual

El Descubrimiento con IA es un punto de partida:

  1. Usa la IA para el trabajo pesado
  2. Añade el contexto de negocio manualmente (descripciones, ADRs)
  3. Refina las relaciones y las descripciones

API REST

POST   /api/v1/discovery/start                            # Start full discovery
GET    /api/v1/discovery/jobs/:jobId                       # Get job status
POST   /api/v1/projects/:id/discovery/incremental          # Trigger incremental discovery

Solución de problemas

El descubrimiento tarda demasiado

  • Reduce el número de archivos analizados (ajusta el máximo de archivos en la configuración)
  • Usa el descubrimiento incremental para las actualizaciones regulares
  • Céntrate en ramas específicas

Resultados inexactos

  • Revisa y corrige sobre la marcha: el sistema de pendientes te permite aprobar o rechazar cada elemento
  • Un código más estructurado produce mejores resultados
  • Añade descripciones a los elementos aprobados para mejorar el contexto de futuros descubrimientos

No se analiza ningún archivo

  • Comprueba que tu repositorio está conectado y que la rama existe
  • Asegúrate de que los archivos fuente tienen extensiones reconocidas (.go, .ts, .py, .java, etc.)
  • Verifica que el token de acceso tiene permisos de lectura sobre el repositorio