Capítulos · 12. Adoptar un proyecto existente

Describe Team AI Console 0.4.19 · actualizada el 2026-11-20

12. Adoptar un proyecto existente

Para trabajar con un equipo sobre un proyecto que ya tiene código hecho fuera de la app. Se abre con Adoptar un proyecto existente… en la pantalla inicial, o desde la pantalla de preparación al abrir una carpeta con código y sin equipo. Es un asistente de cuatro pasos, con los pasos arriba y Cancelar la adopción / ‹ Atrás / Siguiente › siempre abajo:

  1. Carpeta — Elegir la carpeta…. La app la revisa y muestra Qué va a pasar: todo lo que hay en la carpeta pasa a app/; si tiene git, qué pasa con el repositorio según la opción que elijas (ver Si la carpeta ya es un repositorio git, abajo); los archivos de CI o despliegue que habrá que actualizar; y que el agente que elijas (Claude Code o Codex) escribirá la documentación inicial. Si la carpeta no se puede adoptar (está vacía, ya es un proyecto de la app, ya tiene una carpeta app/ con contenido), lo explica.
  2. Equipo — las tarjetas de equipos con el botón Elegir este equipo. El elegido se marca.
  3. Opciones — resumen (carpeta, equipo y, si hay git, la opción de Git elegida y su remoto; cada uno con Cambiar), idioma del equipo, Agente que analiza el proyecto (solo los instalados: con los dos, Claude Code viene elegido y puedes cambiar a Codex; con uno solo, ya está elegido), modelo para generar la documentación (la lista es la del agente elegido; con Claude Code, los modelos que tu plan no incluye salen desactivados: ver Modelos por rol), modelo de cada rol y el aviso de que mover el proyecto es un cambio real en el disco. Botón Adoptar el proyecto. Si no hay ningún agente instalado, un aviso explica cómo resolverlo (instalar Claude Code o Codex, o indicar su ruta en Inicio → Agentes) con Comprobar de nuevo, y no se puede adoptar hasta que haya uno.
  4. Adopción — progreso: se mueve el proyecto, se copia el equipo y el agente lee el código y escribe la documentación (Agente: …, archivos leídos, documentos escritos, tiempo). Con cualquiera de los dos agentes solo puede escribir en la carpeta de documentos y en AGENTS.md. El agente usado queda como el agente del proyecto. Se puede Cancelar la documentación: el proyecto queda adoptado y se puede generar después. Al terminar se ve el resumen, la lista de documentos generados, cuántas afirmaciones quedaron marcadas como [SUPUESTO] y Abrir el proyecto.

La documentación inicial incluye los documentos vivos del equipo (brief, arquitectura, estándares con los comandos reales, backlog, deuda técnica, estrategia de pruebas, contexto, glosario…) y un registro de la adopción (en docs/sprints/sprint-0-adopcion/, o sprint-0-adoption/ si el equipo es en inglés). El flujo empieza en el cierre del Sprint 0: el rol inicial revisa contigo los documentos generados y empieza el Sprint 1. Si algo falla antes de la documentación, la app deshace el movimiento.

Si la carpeta ya es un repositorio git

En el paso Carpeta aparece la tarjeta Esta carpeta ya es un repositorio git (también si .git es un archivo, como en un worktree o un submódulo) con dos opciones. Ninguna viene elegida y no se puede seguir hasta elegir una; las dos se explican con las mismas tres filas: qué queda en la raíz, qué queda en app/ y qué se sube.

  • Todo en el repositorio del producto — lo de siempre: .git/ se queda en la raíz, el código pasa a app/ y el repositorio cambia de estructura. Al hacer git add, git ve el código como movido a app/ (el historial se conserva) y lo que subas incluirá también docs/, el equipo y la configuración de la app.
  • Cada uno en su repositorio — para cuando el repositorio es de otra persona o de otra empresa y a él solo debe llegar el producto. .git se mueve con el código a app/: en app/, git status queda igual que antes y el historial no cambia. En la raíz se crea un repositorio nuevo, sin commits, cuyo .gitignore ignora app/ (y .DS_Store y .scratch/); ahí van docs/ y el equipo. Puedes indicar un remoto opcional para ese repositorio: se añade como origin, sin subir nada ni comprobar la red (la dirección no puede llevar espacios ni empezar por -). Nada de la app se escribe dentro de app/.

Si git no está instalado, o el repositorio no se puede mover con seguridad, la segunda opción sale desactivada con el motivo y la primera sigue disponible. Ninguna de las dos hace commit ni push. Si la adopción falla, la app deshace también la mudanza de .git y borra el repositorio nuevo de la raíz. Al terminar, el resumen dice qué repositorio quedó en cada carpeta.

La elección no se puede cambiar después (los proyectos adoptados antes funcionan como la primera opción). Con Cada uno en su repositorio la app usa el repositorio de app/ para el código: el panel de cambios lee el código de app/ y los documentos de la raíz; los issues, el estado del CI, el enlace para comparar ramas y la comprobación del repositorio en la preparación del proyecto usan el de app/. Las instrucciones que reciben los agentes les dicen que el código se confirma y se sube desde app/, que docs/ y el equipo van al repositorio de la raíz y nunca al del producto, y que las ramas del sprint se hacen en cada repositorio con lo que le corresponde.