Introdução ao AIOS

O Synkra AIOS (AI Operating System) é um framework de meta-agentes que transforma o Claude em uma equipe completa de desenvolvimento de software. Este guia apresenta os conceitos fundamentais, a instalação e os primeiros passos com o sistema.

Pré-requisitos

Antes de instalar o AIOS, verifique se seu ambiente atende aos requisitos mínimos:

Você também precisa de uma chave de API de um provedor de IA compatível (OpenAI, Anthropic ou outro suportado).

Instalação

Inicialize o AIOS em um novo projeto com um único comando:

npx @synkra/aios-core init my-project

Para instalar em um projeto existente, navegue até o diretório do projeto e execute:

cd my-project
npx @synkra/aios-core init .

O instalador cria a estrutura completa do framework e configura os arquivos necessários automaticamente.

Estrutura do Projeto

Após a instalação, seu projeto terá a seguinte estrutura:

my-project/
├── .aios/
│   ├── config.json          # Configuração principal
│   ├── data/                # Dados persistentes e memória
│   └── cache/               # Cache de análises
├── .aios-core/
│   ├── agents/              # Definições dos 12 agentes
│   ├── workflows/           # Workflows automatizados
│   ├── tasks/               # Definições de tarefas
│   ├── templates/           # Templates de stories e documentos
│   ├── scripts/             # Scripts de automação
│   └── docs/                # Documentação interna do framework
├── docs/
│   ├── stories/             # Stories e épicos do projeto
│   └── qa/                  # Relatórios de QA
└── .env                     # Chaves de API (não committar)

Os diretórios .aios/ e .aios-core/ contêm toda a lógica do framework. O diretório docs/ é onde artefatos do projeto são gerados.

Configuração

Arquivo de Configuração Principal

O arquivo .aios/config.json controla o comportamento do framework:

{
  "project": {
    "name": "my-project",
    "type": "web-app"
  },
  "ai": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  },
  "features": {
    "memory": true,
    "learning": true,
    "codeReview": true
  }
}

Variáveis de Ambiente

Configure suas chaves de API no arquivo .env:

# Provedor de IA (obrigatório)
ANTHROPIC_API_KEY=sk-ant-...
# ou
OPENAI_API_KEY=sk-...
 
# Opcional
GITHUB_TOKEN=ghp_...

Importante: Nunca commite o arquivo .env. Ele já está no .gitignore por padrão.

Entendendo o Meta-Agente

O AIOS opera como um meta-agente — um sistema que coordena múltiplos agentes especializados. Suas capacidades incluem:

• Auto-análise: Examina o codebase para entender padrões, dependências e arquitetura
• Geração de código: Produz código seguindo os padrões identificados no projeto
• Aprendizado de padrões: Detecta e registra padrões recorrentes para reutilização
• Auto-evolução: Adapta suas estratégias com base no histórico de decisões

O meta-agente não é apenas um assistente de código — ele mantém contexto de longo prazo, gerencia o ciclo de vida completo de stories e garante consistência entre todos os agentes.

Comandos Básicos

Todos os comandos do AIOS usam o prefixo * (asterisco):

Para ajuda detalhada sobre qualquer comando, use *help {comando}.

Sistema de Agentes

O AIOS disponibiliza 12 agentes especializados, cada um com responsabilidades e autoridades específicas. Para ativar um agente, use a sintaxe @nome-do-agente.

Agentes de Gestão

Agentes Técnicos

Agentes de Qualidade e Análise

Agente de Governança

Camada de Memória

O AIOS possui um sistema de memória persistente que permite busca semântica e por palavras-chave. A memória armazena decisões, padrões aprendidos e contexto do projeto.

A memória suporta dois modos de busca:

• Busca semântica: Encontra conteúdo por significado, mesmo com termos diferentes
• Busca por palavras-chave: Busca exata por termos específicos

Boas Práticas

1. Comece pequeno: Inicie com um agente (@dev) e expanda gradualmente para workflows completos
2. Use nomes descritivos: Stories, épicos e branches com nomes claros facilitam a navegação
3. Aproveite a memória: Execute *analyze regularmente para manter o contexto do projeto atualizado
4. Análise frequente: Use *suggest para identificar oportunidades de melhoria contínua
5. Siga os workflows: O ciclo completo (criar, validar, implementar, revisar) existe para garantir qualidade
6. Documente decisões: O log de decisões (decision-log) é fundamental para rastreabilidade

Solução de Problemas

Node.js não encontrado ou versão incorreta

# Verifique a versão instalada
node --version
 
# Se menor que 18, atualize via nvm
nvm install 18
nvm use 18

Erro de chave de API

Se receber erros de autenticação, verifique:

1. O arquivo .env existe na raiz do projeto
2. A chave está no formato correto para o provedor escolhido
3. A chave tem créditos/quota disponível

Problemas de memória

Se a memória estiver lenta ou retornando resultados incorretos:

# Reconstrua os índices
*memory rebuild
 
# Se persistir, limpe o cache
*memory clear-cache

Erro na inicialização

Se npx @synkra/aios-core init falhar:

# Limpe o cache do npm
npm cache clean --force
 
# Tente novamente com a flag de verbose
npx @synkra/aios-core init my-project --verbose

Próximos Passos

Agora que o AIOS está instalado e configurado, explore os recursos disponíveis:

• Quick Start — Tutorial prático passo a passo
• Ativação de Agentes — Como ativar e configurar agentes
• Desenvolvimento de Stories — Ciclo completo de desenvolvimento
• Workflows — SDC, QA Loop, Spec Pipeline e mais
• Referência de Comandos — Lista completa de comandos
• Playbook — Guias práticos para cenários reais