Skip to Content
PlaybookPrimeiros PassosOnboarding em 60 Minutos

Onboarding em 60 Minutos

Um passo a passo estruturado para se tornar produtivo com o Synkra AIOS em uma hora. Ao final, você terá instalado o framework, ativado agentes, criado sua primeira story, executado o workflow SDC completo e passado por um quality gate.

Minuto 0-10: Instalação e Configuração

Pré-requisitos

Antes de começar, certifique-se de ter:

  • Node.js 20.0.0 ou superior
  • npm 8.0.0 ou superior
  • Git instalado e configurado
  • GitHub CLI (gh) instalado (para workflows de push/PR)
  • Uma IDE de IA — Claude Code (recomendado), Cursor ou VS Code com extensões de IA

Instalar o AIOS

# Criar um novo projeto
npx @synkra/aios-core init meu-primeiro-projeto
 
# Navegar até o projeto
cd meu-primeiro-projeto

Verificar a Instalação

Confirme que o diretório .aios-core/ foi criado:

meu-primeiro-projeto/
  .aios-core/          # Configuração do framework, agentes, tasks, workflows
  docs/
    stories/           # Arquivos de story serão salvos aqui

Configurar o Ambiente

Edite o arquivo .env com a chave do seu provedor de IA:

ANTHROPIC_API_KEY=sua-chave-anthropic
# ou
OPENAI_API_KEY=sua-chave-openai

Minuto 10-20: Entendendo o Framework

Conceitos Fundamentais

O AIOS orquestra 12 agentes especializados nomeados por meio de workflows estruturados. Cada agente tem:

  • Um handle (ex.: @dev) que você usa para endereçá-lo
  • Um nome (ex.: Dex) para sua persona
  • Limites de autoridade definidos — o que pode e não pode fazer
  • Um conjunto de comandos aos quais responde

Comandos Essenciais (Qualquer Agente)

*help      # Mostrar todos os comandos disponíveis
*status    # Exibir contexto atual, estado da story e agente
*guide     # Mostrar guia de uso detalhado para o agente ativo

Os 12 Agentes

HandleNomePapel
@devDexImplementação de software
@qaQuinnQuality gates
@poPaxValidação de stories
@pmMorganEpics e spec pipeline
@smRiverCriação de stories
@architectAriaArquitetura de sistemas
@analystAtlasPesquisa
@ux-design-expertUmaUX/Design
@data-engineerDaraBanco de dados
@devopsGageCI/CD e Git push
@docsAjaxDocumentação
@aios-masterOrionOrquestração do framework

Para detalhes completos sobre cada agente, veja Agentes.

Minuto 20-35: Ativação de Agentes e Sua Primeira Story

Ativar um Agente

Enderece os agentes diretamente para ativá-los:

@sm *help      # Ativar River e ver comandos disponíveis
@dev *help     # Ativar Dex

Limites de Autoridade dos Agentes

Um conceito crítico do AIOS: agentes têm limites de autoridade estritos.

  • @dev pode git add, git commit — mas não pode git push (delegar ao @devops)
  • @po pode validar stories — mas não pode editar critérios de aceitação após a validação
  • Apenas @devops (Gage) pode git push, gh pr create e gh pr merge

Fase 1: Criar Sua Primeira Story (@sm — River)

@sm *draft

River guia você na criação de uma story com título, descrição, critérios de aceitação e escopo. A saída é um arquivo {epicNum}.{storyNum}.story.md com status Draft.

Fase 2: Validar a Story (@po — Pax)

@po *validate-story-draft

Pax executa o checklist de validação de 10 pontos:

#Verificação
1Título claro e objetivo
2Descrição completa
3Critérios de aceitação testáveis
4Escopo bem definido (IN/OUT)
5Dependências mapeadas
6Estimativa de complexidade
7Valor de negócio declarado
8Riscos documentados
9Definição de Done
10Alinhamento com PRD/Epic

Decisão:

  • GO (≥ 7/10) — Status da story muda de Draft para Ready
  • NO-GO (menos de 7) — Correções necessárias listadas; story permanece Draft

Minuto 35-50: Executando o Story Development Cycle (SDC)

O SDC de 4 Fases

FaseAgenteO que Acontece
1. Criar@sm (River)Story rascunhada a partir de epic/PRD
2. Validar@po (Pax)Checklist de 10 pontos, GO/NO-GO
3. Implementar@dev (Dex)Código escrito, CodeRabbit self-healing
4. QA Gate@qa (Quinn)Verificação de qualidade em 7 pontos, veredicto

Fase 3: Implementar (@dev — Dex)

@dev *develop story-1.1

Dex trabalha em um de três modos de execução:

ModoPromptsMelhor Para
Interactive (padrão)5-10, com checkpointsAprendizado, decisões complexas
YOLO0-1, totalmente autônomoTarefas simples
Pre-Flight10-15 antecipados, depois zeroRequisitos ambíguos

Durante a implementação, o CodeRabbit escaneia automaticamente:

  • Problemas CRITICAL e HIGH são corrigidos automaticamente (até 2 iterações na fase dev)
  • Problemas MEDIUM são documentados como débito técnico
  • Problemas LOW são ignorados

Minuto 50-60: Quality Gates e Entrega

Fase 4: QA Gate (@qa — Quinn)

@qa *qa-gate

Quinn verifica 7 dimensões de qualidade:

#Verificação
1Code review (padrões, legibilidade)
2Testes unitários (cobertura, todos passando)
3Critérios de aceitação (todos atendidos)
4Sem regressões
5Performance dentro dos limites
6Segurança (básicos do OWASP)
7Documentação (atualizada se necessário)

Veredictos possíveis: PASS, CONCERNS, FAIL, WAIVED

Se FAIL — Iniciar o QA Loop

*qa-loop story-1.1       # Iniciar ciclo automatizado de revisão-correção
# Máx. 5 iterações: @qa revisa → @dev corrige → @qa revisa novamente

Entregar as Alterações (@devops — Gage)

@devops *push

Apenas Gage pode fazer push. Isso é por design — todos os agentes coordenam através deste único ponto de controle para operações remotas.

O que Você Conquistou

Em 60 minutos você:

  • Instalou e configurou o Synkra AIOS
  • Aprendeu os 12 agentes, seus nomes e limites de autoridade
  • Criou e validou sua primeira story (Fases 1-2 do SDC)
  • Implementou com CodeRabbit self-healing (Fase 3)
  • Passou por um quality gate (Fase 4)
  • Entregou suas alterações via @devops

Próximos Passos

Início RápidoVisão Geral