Skip to content

faq.md

Latest commit

 

History

History
616 lines (430 loc) · 14.9 KB

faq.md

File metadata and controls

616 lines (430 loc) · 14.9 KB
Raw

FAQ do Synkra AIOX

🌐 EN | PT | ES

Versão: 2.1.0 Última Atualização: 2025-01-24

Sumário

Perguntas sobre Instalação

Q1: Por que npx ao invés de npm install -g?

Resposta: Recomendamos npx aiox-core install ao invés de instalação global por várias razões:

  1. Sempre a Versão Mais Recente: npx baixa a versão mais recente automaticamente
  2. Sem Poluição Global: Não adiciona aos seus pacotes npm globais
  3. Isolamento de Projeto: Cada projeto pode ter sua própria versão
  4. Sem Problemas de Permissão: Evita problemas comuns de permissão npm global
  5. Amigável para CI/CD: Funciona perfeitamente em pipelines automatizados

Se você preferir instalação global:

npm install -g aiox-core
aiox-core install

Q2: Quais são os requisitos de sistema?

Resposta:

Componente Mínimo Recomendado
Node.js 18.0.0 20.x LTS
npm 9.0.0 10.x
Espaço em Disco 100 MB 500 MB
RAM 2 GB 8 GB
SO Windows 10, macOS 12, Ubuntu 20.04 Versões mais recentes

Verifique seu sistema:

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

Q3: Posso instalar o AIOX em um projeto existente?

Resposta: Sim! O AIOX foi projetado tanto para projetos greenfield quanto brownfield.

Para projetos existentes:

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

O instalador irá:

  • Criar o diretório .aiox-core/ (arquivos do framework)
  • Criar configuração de IDE (.claude/, .cursor/, etc.)
  • NÃO modificar seu código-fonte existente
  • NÃO sobrescrever documentação existente a menos que você escolha

Importante: Se você tiver um diretório .claude/ ou .cursor/ existente, o instalador perguntará antes de modificar.

Q4: Quanto tempo leva a instalação?

Resposta:

Cenário Tempo
Primeira instalação 2-5 minutos
Atualizar existente 1-2 minutos
Apenas Squad 30-60 segundos

Fatores que afetam o tempo de instalação:

  • Velocidade da conexão de internet
  • Status do cache npm
  • Número de IDEs selecionadas
  • Squads selecionados

Q5: Quais arquivos o AIOX cria no meu projeto?

Resposta: O AIOX cria a seguinte estrutura:

your-project/
├── .aiox-core/                 # Core do framework (200+ arquivos)
│   ├── agents/                 # 11+ definições de agentes
│   ├── tasks/                  # 60+ workflows de tarefas
│   ├── templates/              # 20+ templates de documentos
│   ├── checklists/             # Checklists de validação
│   ├── scripts/                # Scripts utilitários
│   └── core-config.yaml        # Configuração do framework
│
├── .claude/                    # Claude Code (se selecionado)
│   └── commands/AIOX/agents/   # Comandos slash de agentes
│
├── .cursor/                    # Cursor (se selecionado)
│   └── rules/                  # Regras de agentes
│
├── docs/                       # Estrutura de documentação
│   ├── stories/                # Stories de desenvolvimento
│   ├── architecture/           # Docs de arquitetura
│   └── prd/                    # Requisitos de produto
│
└── Squads/            # (se instalado)
    └── hybrid-ops/             # Pack HybridOps

Atualizações e Manutenção

Q6: Como atualizo o AIOX para a versão mais recente?

Resposta:

# Atualizar via npx (recomendado)
npx aiox-core update

# Ou reinstalar a versão mais recente
npx aiox-core install --force-upgrade

# Verificar versão atual
npx aiox-core status

O que é atualizado:

  • Arquivos .aiox-core/ (agentes, tarefas, templates)
  • Configurações de IDE
  • Squads (se instalados)

O que é preservado:

  • Suas modificações customizadas em core-config.yaml
  • Sua documentação (docs/)
  • Seu código-fonte

Q7: Com que frequência devo atualizar?

Resposta: Recomendamos:

Tipo de Atualização Frequência Comando
Patches de segurança Imediatamente npx aiox-core update
Atualizações menores Mensalmente npx aiox-core update
Versões maiores Trimestralmente Revisar changelog primeiro

Verificar atualizações:

npm show aiox-core version
npx aiox-core status

Q8: Posso fazer rollback para uma versão anterior?

Resposta: Sim, várias opções:

Opção 1: Reinstalar versão específica

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

Opção 2: Usar Git para restaurar

# Se .aiox-core está no controle de versão
git checkout HEAD~1 -- .aiox-core/

Opção 3: Restaurar do backup

# O instalador cria backups
mv .aiox-core .aiox-core.failed
mv .aiox-core.backup .aiox-core

Uso Offline e Air-Gapped

Q9: Posso usar o AIOX sem internet?

Resposta: Sim, com alguma preparação:

Configuração inicial (requer internet):

# Instalar uma vez com internet
npx aiox-core install

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

Na máquina air-gapped:

# Extrair o pacote
tar -xzvf aiox-offline.tar.gz

# Os agentes AIOX funcionam sem internet
# (Eles não requerem chamadas de API externas)

Limitações sem internet:

  • Não é possível atualizar para novas versões
  • Integrações MCP (ClickUp, GitHub) não funcionarão
  • Não é possível buscar documentação de bibliotecas (Context7)

Q10: Como transfiro o AIOX para um ambiente air-gapped?

Resposta:

  1. Na máquina conectada:

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

  2. Transferir o arquivo via USB, transferência segura, etc.

  3. Na máquina air-gapped:

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

  4. Configurar IDE manualmente se necessário (os caminhos podem diferir)

IDE e Configuração

Q11: Quais IDEs o AIOX suporta?

Resposta:

IDE Status Ativação de Agentes
Claude Code Suporte Completo /dev, /qa, etc.
Cursor Suporte Completo @dev, @qa, etc.
Gemini CLI Suporte Completo Menção no prompt
GitHub Copilot Suporte Completo Modos de chat

Adicionar suporte para uma nova IDE: Abra uma issue no GitHub com a especificação de agentes/regras da IDE.

Q12: Posso configurar o AIOX para múltiplas IDEs?

Resposta: Sim! Selecione múltiplas IDEs durante a instalação:

Interativo:

? Which IDE(s) do you want to configure?
❯ ◉ Cursor
  ◉ Claude Code

Linha de comando:



Cada IDE recebe seu próprio diretório de configuração:


    

  • .cursor/rules/ para Cursor
    • 

  • .claude/commands/ para Claude Code
    • 





Q13: Como configuro o AIOX para um novo membro da equipe?


Resposta:


Se .aiox-core/ está commitado no seu repositório:


# Novo membro da equipe apenas clona
git clone your-repo
cd your-repo

# Opcionalmente configurar a IDE preferida
npx aiox-core install --ide cursor


Se .aiox-core/ não está commitado:


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


Melhor prática: Commitar .aiox-core/ para compartilhar configurações de agentes consistentes.




Agentes e Workflows


Q14: Quais agentes estão incluídos?


Resposta: O AIOX inclui 11+ agentes especializados:






Agente
Papel
Melhor Para






dev
Desenvolvedor Full-Stack
Implementação de código, debugging




qa
Engenheiro de QA
Testes, code review




architect
Arquiteto de Sistema
Design, decisões de arquitetura




pm
Gerente de Projeto
Planejamento, acompanhamento




po
Product Owner
Backlog, requisitos




sm
Scrum Master
Facilitação, gestão de sprints




analyst
Analista de Negócios
Análise de requisitos




ux-expert
Designer UX
Design de experiência do usuário




data-engineer
Engenheiro de Dados
Pipelines de dados, ETL




devops
Engenheiro DevOps
CI/CD, deployment




db-sage
Arquiteto de Banco
Design de schema, queries








Q15: Como crio um agente customizado?


Resposta:


    

  1. 

    Copie um agente existente:
    

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

    2. 

  2. 

    Edite o frontmatter YAML:
    

    agent:
  name: MyAgent
  id: my-agent
  title: My Custom Agent
  icon: 🔧

persona:
  role: Expert in [your domain]
  style: [communication style]
    

    3. 

  3. 

    Adicione à configuração da IDE:
    

    npx aiox-core install --ide claude-code
    

    4. 

  4. 

    Ative: /my-agent ou @my-agent
    

    5. 





Q16: O que é "yolo mode"?


Resposta: Yolo mode é o modo de desenvolvimento autônomo onde o agente:


    

  • Implementa tarefas de stories sem confirmação passo a passo
    • 

  • Toma decisões autonomamente baseado nos requisitos da story
    • 

  • Registra todas as decisões em .ai/decision-log-{story-id}.md
    • 

  • Pode ser parado a qualquer momento
    • 



Habilitar yolo mode:


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


Quando usar:


    

  • Para stories bem definidas com critérios de aceitação claros
    • 

  • Quando você confia na tomada de decisão do agente
    • 

  • Para tarefas repetitivas
    • 



Quando NÃO usar:


    

  • Para mudanças arquiteturais complexas
    • 

  • Quando os requisitos são ambíguos
    • 

  • Para código crítico de produção
    • 





Squads


Q17: O que são Squads?


Resposta: Squads são add-ons opcionais que estendem as capacidades do AIOX:






Pack
Funcionalidades






hybrid-ops
Integração ClickUp, automação de processos, workflows especializados






Instalar um Squad:


npx aiox-core install --Squads hybrid-ops


Listar packs disponíveis:


npx aiox-core install




Q18: Posso criar meu próprio Squad?


Resposta: Sim! Squads seguem esta estrutura:


my-expansion/
├── pack.yaml           # Manifesto do pack
├── README.md           # Documentação
├── agents/             # Agentes customizados
│   └── my-agent.md
├── tasks/              # Tarefas customizadas
│   └── my-task.md
├── templates/          # Templates customizados
│   └── my-template.yaml
└── workflows/          # Workflows customizados
    └── my-workflow.yaml



Exemplo de pack.yaml:


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




Uso Avançado


Q19: Como integro o AIOX com CI/CD?


Resposta:


Exemplo 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


Exemplo de GitLab CI:


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




Q20: Como customizo o core-config.yaml?


Resposta: O arquivo core-config.yaml controla o comportamento do framework:


# Fragmentação de documento
prd:
  prdSharded: true
  prdShardedLocation: docs/prd

# Localização de stories
devStoryLocation: docs/stories

# Arquivos carregados pelo agente dev
devLoadAlwaysFiles:
  - docs/framework/coding-standards.md
  - docs/framework/tech-stack.md

# Configuração do Git
git:
  showConfigWarning: true
  cacheTimeSeconds: 300

# Status do projeto nas saudações dos agentes
projectStatus:
  enabled: true
  showInGreeting: true


Após editar, reinicie sua IDE para aplicar as mudanças.




Q21: Como contribuo para o AIOX?


Resposta:


    

  1. 

    Faça fork do repositório: https://github.com/SynkraAI/aiox-core
    

    2. 

  2. 

    Crie um branch de feature:
    

    git checkout -b feature/my-feature
    

    3. 

  3. 

    Faça mudanças seguindo os padrões de código:
    

      

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

    • Adicione testes para novas funcionalidades
      • 

    • Atualize a documentação
      • 

    

    4. 

  4. 

    Envie um pull request:
    

      

    • Descreva suas mudanças
      • 

    • Vincule a issues relacionadas
      • 

    • Aguarde a revisão
      • 

    

    5. 



Tipos de contribuições bem-vindas:


    

  • Correção de bugs
    • 

  • Novos agentes
    • 

  • Melhorias de documentação
    • 

  • Squads
    • 

  • Integrações de IDE
    • 





Q22: Onde posso obter ajuda?


Resposta:






Recurso
Link






Documentação
docs/ no seu projeto




Solução de Problemas
troubleshooting.md




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




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






Antes de pedir ajuda:


    

  1. Consulte este FAQ
    2. 

  2. Consulte o Guia de Solução de Problemas
    3. 

  3. Pesquise issues existentes no GitHub
    4. 

  4. Inclua informações do sistema e mensagens de erro na sua pergunta
    5. 





Documentação Relacionada