Guía Técnica: Comandos y Flujos (Git, SVN & IA)

🛠️ Guía Técnica de Operaciones

Comandos esenciales y flujos de trabajo de Hypenosys para garantizar la integridad del proyecto.

Índice de Contenidos

1. Control de Versiones: Git vs SVN

Utilizamos un sistema híbrido para optimizar el rendimiento y la colaboración.

Característica Git (GitHub) SVN (Subversion)
Uso Principal Código fuente y configuración Assets binarios pesados
Tipos de Archivo .cpp, .h, .json, .yml, .md .uasset, .umap, .fbx, .png
Bloqueo (Lock) No (basado en ramas/merge) Sí (Vital para mapas y assets)
Velocidad Rápido para texto Eficiente para archivos grandes

2. Referencia de Comandos CLI

Subversion (SVN)
svn checkout [URL]
svn update
svn commit -m "Msg"
svn lock [file]
svn unlock [file]
svn status
Git
git pull
git add .
git commit -m "Msg"
git push
git status
git checkout -b [branch]

3. Flujo TortoiseSVN (Windows)

  1. Update (Mañana): Click derecho > SVN Update.
  2. Lock (Antes de editar): Click derecho > TortoiseSVN > Get Lock.
  3. Edit: Realiza tus cambios en Unreal Engine.
  4. Commit (Al terminar): Click derecho > SVN Commit....
  5. Revert (Si algo sale mal): Click derecho > TortoiseSVN > Revert.

4. 🤖 Flujo de Trabajo con IA (Claude → Jules)

  • Conceptualización (Claude): Describe lo que necesitas a Claude.
  • Generación de Prompt Técnico: Pídele a Claude un prompt para Jules.
  • Ejecución (Jules): Pega el prompt en el Jules Panel.
  • Verificación: Revisa el log de actividad y el PR.

5. 🚀 Onboarding: Checklist de Incorporación

Sigue este checklist en orden. No avances al siguiente paso hasta completar el anterior. Al finalizar, habrás integrado todas las capas del ecosistema Hypenosys.

A — Cuentas y Accesos
  • GitHub: Crea tu cuenta en github.com y proporciona tu username a Axel para ser añadido a la organización hypenosys.
  • Claude: Crea tu cuenta en claude.ai. Es la herramienta de conceptualización y generación de prompts técnicos del equipo.
    💡 Memoria de Claude: Una vez tengas acceso, añade manualmente en las memorias de Claude la siguiente instrucción:
    "Jules es un agente de IA experto en ingeniería de software con acceso a los repositorios de código y proyectos en GitHub de Hypenosys."
    Además, tras completar tu entrevista de onboarding (plan_de_arranque), añade también los resultados relevantes de esa sesión para personalizar tu contexto de trabajo.
  • Jules (token API): Accede a jules.google.com, genera tu API Key personal y configúrala en tu perfil en la plataforma Hypenosys OPS (Settings → Jules API Key).
  • Tailscale (VPN): Descarga Tailscale e instálalo. Contacta a Axel para que te añada a la red VPN de Hypenosys. Este paso es obligatorio para acceder al servidor SVN.
B — Territorios por Rol
🎨 Diseño / Narrativa
  • Repositorio principal: hypenosys/docs
  • Vincula tu instancia de Obsidian a este repositorio para backups automáticos siguiendo las instrucciones del README.
  • Estructura de carpetas de assets en SVN: coordina con Arte para mantener coherencia con el proyecto de Unreal Engine.
💻 Desarrollo / Código
🖼️ Arte
  • Territorio principal: SVN (binarios, texturas, modelos, mapas de Unreal Engine).
  • Estructura de carpetas alineada con el proyecto UE y con Diseño.
  • Archivos propios de arte dentro del proyecto Unreal (.uasset, .umap, etc.) gestionados exclusivamente por SVN con bloqueo obligatorio antes de editar.
  • Acceso al SVN requiere estar en la VPN de Tailscale (ver paso A).
C — Sincronización SVN + Unreal Engine 5
  1. Asegúrate de estar conectado a la VPN de Tailscale (Paso A).
  2. Instala TortoiseSVN en Windows.
  3. Solicita a Axel la URL del servidor SVN y las credenciales de acceso.
  4. Haz SVN Checkout en la carpeta local donde quieras sincronizar el proyecto.
  5. Abre el proyecto en Unreal Engine 5 apuntando a esa carpeta.
  6. Configura en UE5 el proveedor de control de versiones: Edit → Project Settings → Source Control → Provider: Subversion.
  7. Verifica que los archivos muestran los iconos de estado de TortoiseSVN en el explorador de Windows.
D — Entrevista de Onboarding (Plan de Arranque)

Una vez completados los pasos A–C, realiza tu entrevista de onboarding con Claude usando el documento plan_de_arranque como contexto. Esta sesión establece tu perfil técnico, tus áreas de responsabilidad y calibra el contexto de trabajo para Claude y Jules.

  • Abre Claude y adjunta o pega el contenido de plan_de_arranque.md del repositorio hypenosys/docs.
  • Responde las preguntas de onboarding. Claude generará un resumen de tu perfil.
  • Guarda ese resumen y añádelo manualmente a las memorias de Claude para que persista en futuras sesiones.
  • Comunica a Axel que has completado el onboarding para que active tu acceso completo a todos los repositorios de la organización.
⚠️ Gaps detectados — Acciones pendientes del equipo
  • Handles de GitHub de Alex y Dídac — Pendiente de registrar en la whitelist de acceso al dashboard y en assets/data/team_profiles.json. Comunicarlos a Axel al crear la cuenta.
  • URL del servidor SVN — No está documentada en ningún repositorio público. Axel debe añadirla de forma segura (por ejemplo, en un documento privado en hypenosys/docs con acceso restringido al equipo).
  • Credenciales SVN — Mismo caso. Documentar el proceso de distribución segura de credenciales (recomendado: Bitwarden o similar compartido por el equipo).
  • Versión exacta de Unreal Engine — Se menciona UE 5.7.4 pero conviene documentar el instalador y la build exacta en hypenosys/docs para evitar incompatibilidades entre miembros.
  • Estructura de carpetas SVN — No está documentada. Arte y Diseño deben acordar y documentar la estructura canónica antes de que se incorporen nuevos miembros.

6. 🛸 Antigravity IDE: Extensiones y Setup

Para que Antigravity deje de ser un bloc de notas glorificado y se convierta en una estación de combate real, necesitas configurar las extensiones oficiales de VS Code.

Imprescindibles (No seas animal, instálalas)
  • Graph-It-Live: Porque navegar proyectos grandes a ciegas es deporte de riesgo.
  • Antigravity Cockpit: Monitoriza cuotas y uso de LLMs. No querrás quedarte sin "gasolina" a mitad de un sprint.
  • Jules Bridge Preview: El puente directo para que Jules haga el trabajo sucio mientras tú tomas café.
Confort Visual (Para nostálgicos de VS Code)
  • GitHub Theme: Porque tus ojos merecen un descanso de los temas por defecto.
  • vscode-icons: Diferenciar un .json de un .js por el icono ahorra milisegundos preciosos.
Flujo Recomendado de Configuración
  1. Hackea el Marketplace: Cambia la URL del marketplace por defecto al oficial de VS Code (ver abajo).
  2. Orden de Batalla: Instala primero las de navegación. Si no ves dónde estás, no sirve de nada lo que escribas.
  3. Estética: Aplica temas e iconos para no sentir que estás programando en 1995.
  4. Higiene: Prioriza herramientas con mantenimiento activo. Instalar extensiones abandonadas es comprar boletos para un bug que nadie va a arreglar.
Configuración del Marketplace Oficial

Añade estas URLs en la configuración de Antigravity para acceder al catálogo real:

Item URL: https://marketplace.visualstudio.com/items
Gallery URL: https://marketplace.visualstudio.com/_apis/public/gallery

7. 💎 Obsidian: Sincronización de la Bóveda

Bienvenido al repositorio-vertedero de documentación. Si estás leyendo esto, enhorabuena: ya superaste el primer obstáculo. Los que no llegaron hasta aquí probablemente siguen buscando el archivo en el escritorio.

Requisitos (Lo mínimo para no fallar)
  • Obsidian Desktop instalado.
  • Acceso al repo hypenosys/docs en GitHub.
  • Un Personal Access Token (PAT) de GitHub.
  • 10 minutos de tu vida que no recuperarás, pero que te salvarán de la humillación técnica.
Instalación paso a paso

1. Clona el Repo

git clone https://github.com/hypenosys/docs tu-carpeta-local

Si no sabes qué es una terminal, este proyecto te va a doler.

2. Abre la Bóveda

En Obsidian, selecciona "Abrir carpeta como bóveda" y apunta a lo que acabas de clonar. Sí, las carpetas son las notas. No busques magia donde hay estructura.

3. Activa el Plugin de Git

Ve a Configuración → Plugins de comunidad, desactiva el Modo restringido e instala el plugin Git (de Vinzent03).

💡 Configuración Crítica del Plugin:
  • Auto commit-and-sync: 10 minutos.
  • Pull on startup: ✅ ON.
  • Push on commit-and-sync: ✅ ON.

4. El Token de GitHub (El "PAT")

GitHub ya no acepta contraseñas normales. Necesitas un token. Es como una contraseña, pero más larga y con menos dignidad.

  1. Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens.
  2. Genera uno nuevo para hypenosys/docs con permisos de Contents: Read and Write.
  3. Cópialo. GitHub no te lo volverá a mostrar. No hay segunda oportunidad.
Gestión de Conflictos

Si al hacer pull Obsidian te grita sobre un conflicto, significa que alguien editó lo mismo que tú. Hablar con el equipo antes de editar es una funcionalidad que Git no puede implementar por ti. Si no sabes qué hacer con un conflicto, pregunta antes de romper el historial del lore.

💡 TIP: Haz commits pequeños y frecuentes. Si tienes dudas con un conflicto, no fuerces el commit.