Skip to content

faq.md

Latest commit

 

History

History
616 lines (430 loc) · 15.3 KB

faq.md

File metadata and controls

616 lines (430 loc) · 15.3 KB
Raw

Preguntas Frecuentes de Synkra AIOX

🌐 EN | PT | ES

Versión: 2.1.0 Última Actualización: 2025-01-24

Tabla de Contenidos

Preguntas de Instalación

P1: ¿Por qué npx en lugar de npm install -g?

Respuesta: Recomendamos npx aiox-core install en lugar de instalación global por varias razones:

  1. Siempre la Última Versión: npx obtiene la última versión automáticamente
  2. Sin Contaminación Global: No agrega a sus paquetes npm globales
  3. Aislamiento de Proyecto: Cada proyecto puede tener su propia versión
  4. Sin Problemas de Permisos: Evita problemas comunes de permisos npm globales
  5. Compatible con CI/CD: Funciona perfectamente en pipelines automatizados

Si prefiere instalación global:

npm install -g aiox-core
aiox-core install

P2: ¿Cuáles son los requisitos del sistema?

Respuesta:

Componente Mínimo Recomendado
Node.js 18.0.0 20.x LTS
npm 9.0.0 10.x
Espacio en Disco 100 MB 500 MB
RAM 2 GB 8 GB
SO Windows 10, macOS 12, Ubuntu 20.04 Últimas versiones

Verifique su sistema:

node --version  # Debe ser 18+
npm --version   # Debe ser 9+

P3: ¿Puedo instalar AIOX en un proyecto existente?

Respuesta: ¡Sí! AIOX está diseñado tanto para proyectos nuevos como existentes.

Para proyectos existentes:

cd /path/to/existing-project
npx aiox-core install

El instalador:

  • Creará el directorio .aiox-core/ (archivos del framework)
  • Creará la configuración del IDE (.claude/, .cursor/, etc.)
  • NO modificará su código fuente existente
  • NO sobrescribirá documentación existente a menos que lo elija

Importante: Si tiene un directorio .claude/ o .cursor/ existente, el instalador preguntará antes de modificar.

P4: ¿Cuánto tiempo toma la instalación?

Respuesta:

Escenario Tiempo
Primera instalación 2-5 minutos
Actualizar existente 1-2 minutos
Solo paquete de expansión 30-60 segundos

Factores que afectan el tiempo de instalación:

  • Velocidad de conexión a internet
  • Estado de la caché de npm
  • Número de IDEs seleccionados
  • Paquetes de expansión seleccionados

P5: ¿Qué archivos crea AIOX en mi proyecto?

Respuesta: AIOX crea la siguiente estructura:

your-project/
├── .aiox-core/                 # Núcleo del framework (200+ archivos)
│   ├── agents/                 # 11+ definiciones de agentes
│   ├── tasks/                  # 60+ flujos de trabajo de tareas
│   ├── templates/              # 20+ plantillas de documentos
│   ├── checklists/             # Listas de verificación de validación
│   ├── scripts/                # Scripts de utilidad
│   └── core-config.yaml        # Configuración del framework
│
├── .claude/                    # Claude Code (si se seleccionó)
│   └── commands/AIOX/agents/   # Comandos slash de agentes
│
├── .cursor/                    # Cursor (si se seleccionó)
│   └── rules/                  # Reglas de agentes
│
├── docs/                       # Estructura de documentación
│   ├── stories/                # Historias de desarrollo
│   ├── architecture/           # Documentos de arquitectura
│   └── prd/                    # Requisitos de producto
│
└── Squads/            # (si se instaló)
    └── hybrid-ops/             # Paquete HybridOps

Actualizaciones y Mantenimiento

P6: ¿Cómo actualizo AIOX a la última versión?

Respuesta:

# Actualizar vía npx (recomendado)
npx aiox-core update

# O reinstalar la última
npx aiox-core install --force-upgrade

# Verificar versión actual
npx aiox-core status

Qué se actualiza:

  • Archivos de .aiox-core/ (agentes, tareas, plantillas)
  • Configuraciones del IDE
  • Paquetes de expansión (si están instalados)

Qué se preserva:

  • Sus modificaciones personalizadas en core-config.yaml
  • Su documentación (docs/)
  • Su código fuente

P7: ¿Con qué frecuencia debo actualizar?

Respuesta: Recomendamos:

Tipo de Actualización Frecuencia Comando
Parches de seguridad Inmediatamente npx aiox-core update
Actualizaciones menores Mensualmente npx aiox-core update
Versiones mayores Trimestralmente Revise el changelog primero

Verificar actualizaciones:

npm show aiox-core version
npx aiox-core status

P8: ¿Puedo revertir a una versión anterior?

Respuesta: Sí, varias opciones:

Opción 1: Reinstalar versión específica

npx aiox-core@1.1.0 install --force-upgrade

Opción 2: Usar Git para restaurar

# Si .aiox-core está rastreado en git
git checkout HEAD~1 -- .aiox-core/

Opción 3: Restaurar desde copia de seguridad

# El instalador crea copias de seguridad
mv .aiox-core .aiox-core.failed
mv .aiox-core.backup .aiox-core

Uso Offline y en Entornos Aislados

P9: ¿Puedo usar AIOX sin internet?

Respuesta: Sí, con algo de preparación:

Configuración inicial (requiere internet):

# Instalar una vez con internet
npx aiox-core install

# Empaquetar para uso offline
tar -czvf aiox-offline.tar.gz .aiox-core/ .claude/ .cursor/

En máquina aislada:

# Extraer el paquete
tar -xzvf aiox-offline.tar.gz

# Los agentes de AIOX funcionan sin internet
# (No requieren llamadas a API externas)

Limitaciones sin internet:

  • No se puede actualizar a nuevas versiones
  • Las integraciones MCP (ClickUp, GitHub) no funcionarán
  • No se puede obtener documentación de bibliotecas (Context7)

P10: ¿Cómo transfiero AIOX a un entorno aislado?

Respuesta:

  1. En máquina conectada:

    # Instalar y empaquetar
npx aiox-core install
cd your-project
tar -czvf aiox-transfer.tar.gz .aiox-core/ .claude/ .cursor/ docs/

  2. Transferir el archivo vía USB, transferencia segura, etc.

  3. En máquina aislada:

    cd your-project
tar -xzvf aiox-transfer.tar.gz

  4. Configurar IDE manualmente si es necesario (las rutas pueden diferir)

IDE y Configuración

P11: ¿Qué IDEs soporta AIOX?

Respuesta:

IDE Estado Activación de Agentes
Claude Code Soporte Completo /dev, /qa, etc.
Cursor Soporte Completo @dev, @qa, etc.
Gemini CLI Soporte Completo Mención en prompt
GitHub Copilot Soporte Completo Modos de chat

Agregar soporte para un nuevo IDE: Abra un issue en GitHub con la especificación de agentes/reglas del IDE.

P12: ¿Puedo configurar AIOX para múltiples IDEs?

Respuesta: ¡Sí! Seleccione múltiples IDEs durante la instalación:

Interactivo:

? ¿Qué IDE(s) quiere configurar?
❯ ◉ Cursor
  ◉ Claude Code

Línea de comandos:



Cada IDE obtiene su propio directorio de configuración:


    

  • .cursor/rules/ para Cursor
    • 

  • .claude/commands/ para Claude Code
    • 





P13: ¿Cómo configuro AIOX para un nuevo miembro del equipo?


Respuesta:


Si .aiox-core/ está commiteado en su repositorio:


# El nuevo miembro solo clona
git clone your-repo
cd your-repo

# Opcionalmente configurar su IDE preferido
npx aiox-core install --ide cursor


Si .aiox-core/ no está commiteado:


git clone your-repo
cd your-repo
npx aiox-core install


Mejor práctica: Commitear .aiox-core/ para compartir configuraciones de agentes consistentes.




Agentes y Flujos de Trabajo


P14: ¿Qué agentes están incluidos?


Respuesta: AIOX incluye 11+ agentes especializados:






Agente
Rol
Ideal Para






dev
Desarrollador Full-Stack
Implementación de código, depuración




qa
Ingeniero QA
Pruebas, revisión de código




architect
Arquitecto de Sistemas
Diseño, decisiones de arquitectura




pm
Gerente de Proyecto
Planificación, seguimiento




po
Product Owner
Backlog, requisitos




sm
Scrum Master
Facilitación, gestión de sprints




analyst
Analista de Negocios
Análisis de requisitos




ux-expert
Diseñador UX
Diseño de experiencia de usuario




data-engineer
Ingeniero de Datos
Pipelines de datos, ETL




devops
Ingeniero DevOps
CI/CD, despliegue




db-sage
Arquitecto de Base de Datos
Diseño de esquemas, consultas








P15: ¿Cómo creo un agente personalizado?


Respuesta:


    

  1. 

    Copiar un agente existente:
    

    cp .aiox-core/agents/dev.md .aiox-core/agents/my-agent.md
    

    2. 

  2. 

    Editar el frontmatter YAML:
    

    agent:
  name: MyAgent
  id: my-agent
  title: Mi Agente Personalizado
  icon: 🔧

persona:
  role: Experto en [su dominio]
  style: [estilo de comunicación]
    

    3. 

  3. 

    Agregar a la configuración del IDE:
    

    npx aiox-core install --ide claude-code
    

    4. 

  4. 

    Activar: /my-agent o @my-agent
    

    5. 





P16: ¿Qué es el "modo yolo"?


Respuesta: El modo yolo es un modo de desarrollo autónomo donde el agente:


    

  • Implementa tareas de la historia sin confirmación paso a paso
    • 

  • Toma decisiones autónomamente basándose en los requisitos de la historia
    • 

  • Registra todas las decisiones en .ai/decision-log-{story-id}.md
    • 

  • Se puede detener en cualquier momento
    • 



Habilitar modo yolo:


/dev
*develop-yolo docs/stories/your-story.md


Cuándo usar:


    

  • Para historias bien definidas con criterios de aceptación claros
    • 

  • Cuando confía en la toma de decisiones del agente
    • 

  • Para tareas repetitivas
    • 



Cuándo NO usar:


    

  • Para cambios arquitectónicos complejos
    • 

  • Cuando los requisitos son ambiguos
    • 

  • Para código crítico de producción
    • 





Squads


P17: ¿Qué son los Squads?


Respuesta: Los paquetes de expansión son complementos opcionales que extienden las capacidades de AIOX:






Paquete
Características






hybrid-ops
Integración con ClickUp, automatización de procesos, flujos de trabajo especializados






Instalar un Squad:


npx aiox-core install --Squads hybrid-ops


Listar paquetes disponibles:


npx aiox-core install




P18: ¿Puedo crear mi propio Squad?


Respuesta: ¡Sí! Los paquetes de expansión siguen esta estructura:


my-expansion/
├── pack.yaml           # Manifiesto del paquete
├── README.md           # Documentación
├── agents/             # Agentes personalizados
│   └── my-agent.md
├── tasks/              # Tareas personalizadas
│   └── my-task.md
├── templates/          # Plantillas personalizadas
│   └── my-template.yaml
└── workflows/          # Flujos de trabajo personalizados
    └── my-workflow.yaml



Ejemplo de pack.yaml:


name: my-expansion
version: 1.0.0
description: Mi Squad personalizado
dependencies:
  aiox-core: ">=1.0.0"
agents:
  - my-agent
tasks:
  - my-task




Uso Avanzado


P19: ¿Cómo integro AIOX con CI/CD?


Respuesta:


Ejemplo de GitHub Actions:


name: CI with AIOX
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "18"
      - run: npx aiox-core install --full --ide claude-code
      - run: npm test


Ejemplo de GitLab CI:


test:
  image: node:18
  script:
    - npx aiox-core install --full
    - npm test




P20: ¿Cómo personalizo core-config.yaml?


Respuesta: El archivo core-config.yaml controla el comportamiento del framework:


# Fragmentación de documentos
prd:
  prdSharded: true
  prdShardedLocation: docs/prd

# Ubicación de historias
devStoryLocation: docs/stories

# Archivos cargados por el agente dev
devLoadAlwaysFiles:
  - docs/framework/coding-standards.md
  - docs/framework/tech-stack.md

# Configuración de Git
git:
  showConfigWarning: true
  cacheTimeSeconds: 300

# Estado del proyecto en saludos de agentes
projectStatus:
  enabled: true
  showInGreeting: true


Después de editar, reinicie su IDE para aplicar los cambios.




P21: ¿Cómo contribuyo a AIOX?


Respuesta:


    

  1. 

    Haga fork del repositorio: https://github.com/SynkraAI/aiox-core
    

    2. 

  2. 

    Cree una rama de feature:
    

    git checkout -b feature/my-feature
    

    3. 

  3. 

    Haga cambios siguiendo los estándares de código:
    

      

    • Lea docs/framework/coding-standards.md
      • 

    • Agregue pruebas para nuevas funcionalidades
      • 

    • Actualice la documentación
      • 

    

    4. 

  4. 

    Envíe un pull request:
    

      

    • Describa sus cambios
      • 

    • Enlace a issues relacionados
      • 

    • Espere la revisión
      • 

    

    5. 



Tipos de contribuciones bienvenidas:


    

  • Corrección de errores
    • 

  • Nuevos agentes
    • 

  • Mejoras de documentación
    • 

  • Paquetes de expansión
    • 

  • Integraciones de IDE
    • 





P22: ¿Dónde puedo obtener ayuda?


Respuesta:






Recurso
Enlace






Documentación
docs/ en su proyecto




Solución de Problemas
troubleshooting.md




Issues de GitHub
https://github.com/SynkraAI/aiox-core/issues




Código Fuente
https://github.com/SynkraAI/aiox-core






Antes de pedir ayuda:


    

  1. Revise estas FAQ
    2. 

  2. Revise la Guía de Solución de Problemas
    3. 

  3. Busque issues existentes en GitHub
    4. 

  4. Incluya información del sistema y mensajes de error en su pregunta
    5. 





Documentación Relacionada