Guia do Usuário AIOS

PT-BR

Guia completo para usar o Synkra AIOS - o Sistema Orquestrado por IA para Desenvolvimento Full Stack.

Versão: 2.1.0 Última Atualização: 2026-01-28

Início Rápido

Pré-requisitos

Antes de usar o AIOS, certifique-se de ter:

• Node.js versão 18.0.0 ou superior
• npm versão 8.0.0 ou superior
• Git para controle de versão
• Uma chave de API de provedor de IA (Anthropic, OpenAI ou compatível)

Instalação

# Novo projeto (Greenfield)
npx @synkra/aios-core init my-project
 
# Projeto existente (Brownfield)
cd existing-project
npx @synkra/aios-core install

Primeiros Passos

# Navegue até seu projeto
cd my-project
 
# Liste agentes disponíveis
aios agents list
 
# Ative um agente
@dev
 
# Obtenha ajuda
*help

Conceitos Fundamentais

Filosofia

“Estrutura é Sagrada. Tom é Flexível.”

O AIOS fornece estrutura orquestrada enquanto permite flexibilidade na comunicação. Isso significa:

• Fixo: Posições de templates, ordem de seções, formatos de métricas, estrutura de arquivos, workflows
• Flexível: Mensagens de status, escolhas de vocabulário, uso de emojis, personalidade, tom

A Diferença do AIOS

Agentes

O AIOS inclui 11 agentes especializados, cada um com papel e personalidade distintos:

Ativação de Agentes

# Ative um agente usando sintaxe @
@dev                # Ativar Dex (Desenvolvedor)
@qa                 # Ativar Quinn (QA)
@architect          # Ativar Aria (Arquiteto)
@aios-master        # Ativar Pax (Orquestrador)
 
# Comandos de agente usam prefixo *
*help               # Mostrar comandos disponíveis
*task <name>        # Executar task específica
*exit               # Desativar agente

Contexto do Agente

Quando um agente está ativo:

• Siga a persona e expertise específicas daquele agente
• Use os padrões de workflow designados do agente
• Mantenha a perspectiva do agente durante toda a interação

Tasks

Tasks são o ponto de entrada principal no AIOS. Tudo é uma task.

Arquitetura Task-First

Requisição do Usuário --> Task --> Execução do Agente --> Saída
                           |
                      Workflow (se multi-etapa)

Executando Tasks

# Executar uma task específica
*task develop-story --story=1.1
 
# Listar tasks disponíveis
aios tasks list
 
# Obter ajuda da task
*task --help

Categorias de Tasks

Workflows

Workflows orquestram múltiplas tasks e agentes para operações complexas.

Workflows Disponíveis

Executando Workflows

# Iniciar um workflow
aios workflow greenfield-fullstack
 
# Com parâmetros
aios workflow brownfield-integration --target=./existing-project

Squads

Squads são equipes modulares de agentes de IA que estendem a funcionalidade do AIOS.

O que é um Squad?

Um squad é um pacote autocontido contendo:

Níveis de Distribuição

Nível 1: LOCAL        --> ./squads/           (Privado)
Nível 2: AIOS-SQUADS  --> github.com/SynkraAI (Público/Gratuito)
Nível 3: SYNKRA API   --> api.synkra.dev      (Marketplace)

Usando Squads

# Listar squads disponíveis
aios squads list
 
# Baixar um squad
aios squads download etl-squad
 
# Criar seu próprio squad
@squad-creator
*create-squad my-custom-squad

Squads Oficiais

Uso Básico

Estrutura do Projeto

my-project/
├── .aios-core/                # Configuração do framework
│   ├── development/agents/    # Definições de agentes
│   ├── development/tasks/     # Workflows de tasks
│   ├── product/templates/     # Templates de documentos
│   └── product/checklists/    # Checklists de validação
├── docs/
│   ├── stories/               # Stories de desenvolvimento
│   ├── architecture/          # Arquitetura do sistema
│   └── guides/                # Guias do usuário
├── squads/                    # Squads locais
└── src/                       # Código fonte da aplicação

Comandos Comuns

# Comandos do AIOS Master
*help                # Mostrar comandos disponíveis
*create-story        # Criar nova story
*task {name}         # Executar task específica
*workflow {name}     # Executar workflow
 
# Comandos de Desenvolvimento
npm run dev          # Iniciar desenvolvimento
npm test             # Executar testes
npm run lint         # Verificar estilo de código
npm run build        # Build do projeto

Desenvolvimento Orientado a Stories

1. Criar uma story - Use *create-story para definir requisitos
2. Trabalhar a partir de stories - Todo desenvolvimento começa com uma story em docs/stories/
3. Atualizar progresso - Marque checkboxes conforme tasks completam: [ ] —> [x]
4. Rastrear mudanças - Mantenha a seção File List na story
5. Seguir critérios - Implemente exatamente o que os critérios de aceitação especificam

Configuração

Arquivo Principal de Configuração

A configuração principal está em .aios-core/core/config/:

# aios.config.yaml
version: 2.1.0
projectName: my-project
 
features:
  - agents
  - tasks
  - workflows
  - squads
  - quality-gates
 
ai:
  provider: anthropic
  model: claude-3-opus
 
environment: development

Variáveis de Ambiente

# Configuração do Provedor de IA
ANTHROPIC_API_KEY=sua-chave-anthropic-api
# ou
OPENAI_API_KEY=sua-chave-openai-api
 
# Configurações do Framework
NODE_ENV=development
AIOS_DEBUG=false

Integração com IDE

O AIOS suporta múltiplas IDEs. A configuração é sincronizada entre:

• Claude Code (.claude/)
• Cursor (.cursor/)
• VS Code (.vscode/)

# Sincronizar agentes para sua IDE
npm run sync:ide

Solução de Problemas

Problemas Comuns

Agente não ativa

# Verificar se agente existe
ls .aios-core/development/agents/
 
# Verificar configuração
aios doctor

Execução de task falha

# Verificar definição da task
cat .aios-core/development/tasks/{task-name}.md
 
# Executar com saída verbose
*task {name} --verbose

Problemas de memória/contexto

# Limpar cache
rm -rf .aios-core/core/cache/*
 
# Reconstruir índice
aios rebuild

Obtendo Ajuda

• GitHub Discussions: github.com/SynkraAI/aios-core/discussions 
• Issue Tracker: github.com/SynkraAI/aios-core/issues 
• Discord: Entre no nosso servidor 

Próximos Passos

Caminho de Aprendizado

1. Início Rápido - Siga este guia para começar
2. Referência de Agentes - Aprenda sobre as capacidades de cada agente: Guia de Referência de Agentes
3. Arquitetura - Entenda o sistema: Visão Geral da Arquitetura
4. Squads - Estenda funcionalidades: Guia de Squads

Tópicos Avançados

• Guia de Quality Gates
• Estratégia Multi-Repo
• Integração MCP
• Integração com IDE

Melhores Práticas

1. Comece com Stories

Sempre crie uma story antes de implementar funcionalidades:

@aios-master
*create-story

2. Use o Agente Certo

Escolha o agente apropriado para cada task:

3. Siga Quality Gates

O AIOS implementa quality gates em 3 camadas:

1. Camada 1 (Local): Hooks de pre-commit, linting, verificação de tipos
2. Camada 2 (CI/CD): Testes automatizados, review do CodeRabbit
3. Camada 3 (Humano): Review de arquitetura, aprovação final

4. Mantenha o Contexto

Mantenha o contexto entre sessões:

• Usando desenvolvimento orientado a stories
• Atualizando checkboxes de progresso
• Documentando decisões nas stories

5. Aproveite os Squads

Não reinvente a roda - verifique se existem squads:

aios squads search {keyword}

Documentação Relacionada

• Primeiros Passos
• Guia de Instalação
• Guia de Referência de Agentes
• Visão Geral da Arquitetura
• Guia de Squads
• Solução de Problemas

Guia do Usuário Synkra AIOS v4.0