Guia de Workflow Git do AIOS

🌐 EN | PT | ES

Story: 2.2-git-workflow-implementation.yaml

Índice

Visão Geral
Arquitetura de Defesa em Profundidade
Camada 1: Validação Pre-commit
Camada 2: Validação Pre-push
Camada 3: Pipeline CI/CD
Proteção de Branch
Workflow Diário
Solução de Problemas
Dicas de Performance

Visão Geral

O Synkra AIOS implementa uma estratégia de validação de Defesa em Profundidade com três camadas progressivas que detectam problemas antecipadamente e garantem a qualidade do código antes do merge.

Por Que Três Camadas?

Feedback rápido - Detecta problemas imediatamente durante o desenvolvimento
Validação local - Sem dependência de cloud para verificações básicas
Validação autoritativa - Portão final antes do merge
Consistência de stories - Garante que o desenvolvimento está alinhado com as stories

Diagrama de Arquitetura


┌─────────────────────────────────────────────────────────────┐
│                     Workflow do Desenvolvedor                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Camada 1: Hook Pre-commit (Local - <5s)                     │
│ ✓ ESLint (qualidade de código)                              │
│ ✓ TypeScript (verificação de tipos)                         │
│ ✓ Cache habilitado                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Camada 2: Hook Pre-push (Local - <2s)                       │
│ ✓ Validação de checkboxes da story                          │
│ ✓ Consistência de status                                    │
│ ✓ Seções obrigatórias                                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Camada 3: GitHub Actions CI (Cloud - 2-5min)                │
│ ✓ Todas as verificações de lint/tipos                       │
│ ✓ Suíte completa de testes                                  │
│ ✓ Cobertura de código (≥80%)                                │
│ ✓ Validação de stories                                      │
│ ✓ Proteção de branch                                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                      ┌──────────────┐
                      │ Pronto para  │
                      │    Merge     │
                      └──────────────┘

Arquitetura de Defesa em Profundidade

Camada 1: Pre-commit (Local - Rápido)

Meta de Performance: <5 segundos Gatilho: git commit Localização: .husky/pre-commit

O que valida:

Qualidade de código ESLint
Verificação de tipos TypeScript
Erros de sintaxe
Problemas de importação

Como funciona:


# Acionado automaticamente no commit
git add .
git commit -m "feat: add feature"
 
# Executa:
# 1. ESLint com cache (.eslintcache)
# 2. Compilação incremental TypeScript (.tsbuildinfo)

Benefícios:

⚡ Feedback rápido (<5s)
💾 Cache para velocidade
🔒 Previne commits de código quebrado
🚫 Sem sintaxe inválida no histórico

Camada 2: Pre-push (Local - Validação de Stories)

Meta de Performance: <2 segundos Gatilho: git push Localização: .husky/pre-push

O que valida:

Completude de checkboxes da story vs status
Seções obrigatórias da story presentes
Consistência de status
Registros do dev agent

Como funciona:


# Acionado automaticamente no push
git push origin feature/my-feature
 
# Valida todos os arquivos de story em docs/stories/

Regras de Validação:

Consistência de Status:


# ❌ Inválido: completada mas tarefas incompletas
status: "completed"
tasks:
  - "[x] Task 1"
  - "[ ] Task 2"  # Erro!
 
# ✅ Válido: todas as tarefas completadas
status: "completed"
tasks:
  - "[x] Task 1"
  - "[x] Task 2"

Seções Obrigatórias:

id
title
description
acceptance_criteria
status

Fluxo de Status:


ready → in progress → Ready for Review → completed

Camada 3: CI/CD (Cloud - Autoritativo)

Performance: 2-5 minutos Gatilho: Push para qualquer branch, criação de PR Plataforma: GitHub Actions Localização: .github/workflows/ci.yml

Jobs:

ESLint (job lint)
- Executa em ambiente limpo
- Sem dependência de cache
TypeScript (job typecheck)
- Verificação completa de tipos
- Sem compilação incremental
Testes (job test)
- Suíte completa de testes
- Relatório de cobertura
- Limite de 80% obrigatório
Validação de Stories (job story-validation)
- Todas as stories validadas
- Consistência de status verificada
Resumo de Validação (job validation-summary)
- Agrega todos os resultados
- Bloqueia merge se algum falhar

Monitoramento de Performance:

Job de performance opcional
Mede tempos de validação
Apenas informativo

Camada 1: Validação Pre-commit

Referência Rápida


# Validação manual
npm run lint
npm run typecheck
 
# Auto-corrigir problemas de lint
npm run lint -- --fix
 
# Pular hook (NÃO recomendado)
git commit --no-verify

Configuração do ESLint

Arquivo: .eslintrc.json


{
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  "parser": "@typescript-eslint/parser",
  "plugins": ["@typescript-eslint"],
  "cache": true,
  "cacheLocation": ".eslintcache"
}

Recursos principais:

Suporte a TypeScript
Cache habilitado
Avisa sobre console.log
Ignora variáveis não usadas com prefixo _

Configuração do TypeScript

Arquivo: tsconfig.json


{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true,
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

Recursos principais:

Target ES2022
Modo strict
Compilação incremental
Módulos CommonJS

Otimização de Performance

Arquivos de Cache:

.eslintcache - Resultados do ESLint
.tsbuildinfo - Dados incrementais do TypeScript

Primeira execução: ~10-15s (sem cache) Execuções subsequentes: <5s (com cache)

Invalidação de cache:

Mudanças de configuração
Atualizações de dependências
Exclusão de arquivos

Camada 2: Validação Pre-push

Referência Rápida


# Validação manual
node .aios-core/utils/aios-validator.js pre-push
node .aios-core/utils/aios-validator.js stories
 
# Validar story única
node .aios-core/utils/aios-validator.js story docs/stories/1.1-story.yaml
 
# Pular hook (NÃO recomendado)
git push --no-verify

Validador de Stories

Localização: .aios-core/utils/aios-validator.js

Recursos:

Saída colorida no terminal
Indicadores de progresso
Mensagens de erro claras
Avisos para problemas potenciais

Exemplo de Saída:


══════════════════════════════════════════════════════════
  Validação de Story: 2.2-git-workflow-implementation.yaml
══════════════════════════════════════════════════════════

Story: 2.2 - Git Workflow com Validação Multi-Camada
Status: in progress

Progresso: 12/15 tarefas (80.0%)

✓ Validação de story passou com avisos

Aviso:
  • Considere atualizar o status para 'Ready for Review'

Regras de Validação

1. Formato de Checkbox

Formatos suportados:

[x] - Completado (minúsculo)
[X] - Completado (maiúsculo)
[ ] - Incompleto

Não reconhecidos:

[o], [*], [-] - Não contam como completos

2. Consistência de Status

Status	Regra
`ready`	Nenhuma tarefa deve estar marcada
`in progress`	Algumas tarefas marcadas
`Ready for Review`	Todas as tarefas marcadas
`completed`	Todas as tarefas marcadas

3. Seções Obrigatórias

Todas as stories devem ter:


id: "X.X"
title: "Título da Story"
description: "Descrição da story"
status: "ready" | "in progress" | "Ready for Review" | "completed"
acceptance_criteria:
  - name: "Critério"
    tasks:
      - "[ ] Tarefa"

4. Registro do Dev Agent

Recomendado mas não obrigatório:


dev_agent_record:
  agent_model: 'claude-sonnet-4-5'
  implementation_date: '2025-01-23'

Aviso se ausente.

Mensagens de Erro

Seções Obrigatórias Ausentes:


✗ Seções obrigatórias ausentes: description, acceptance_criteria

Inconsistência de Status:


✗ Story marcada como completed mas apenas 12/15 tarefas estão marcadas

Arquivo Inexistente:


✗ Arquivo de story não encontrado: docs/stories/missing.yaml

Camada 3: Pipeline CI/CD

Estrutura do Workflow

Arquivo: .github/workflows/ci.yml

Jobs:

lint - Validação ESLint
typecheck - Verificação TypeScript
test - Testes Jest com cobertura
story-validation - Consistência de stories
validation-summary - Agregação de resultados
performance (opcional) - Métricas de performance

Detalhes dos Jobs

Job ESLint


- name: Run ESLint
  run: npm run lint

Executa no Ubuntu mais recente
Timeout: 5 minutos
Usa cache npm
Falha em qualquer erro de lint

Job TypeScript


- name: Run TypeScript type checking
  run: npm run typecheck

Executa no Ubuntu mais recente
Timeout: 5 minutos
Falha em erros de tipo

Job de Testes


- name: Run tests with coverage
  run: npm run test:coverage

Executa no Ubuntu mais recente
Timeout: 10 minutos
Cobertura enviada ao Codecov
Limite de 80% de cobertura obrigatório

Job de Validação de Stories


- name: Validate story checkboxes
  run: node .aios-core/utils/aios-validator.js stories

Executa no Ubuntu mais recente
Timeout: 5 minutos
Valida todas as stories

Job de Resumo de Validação


needs: [lint, typecheck, test, story-validation]
if: always()

Executa após todas as validações
Verifica status de todos os jobs
Falha se qualquer validação falhou
Fornece resumo

Gatilhos do CI

Eventos de Push:

Branch master
Branch develop
Branches feature/**
Branches bugfix/**

Eventos de Pull Request:

Contra master
Contra develop

Visualizando Resultados do CI


# Ver checks do PR
gh pr checks
 
# Ver execuções do workflow
gh run list
 
# Ver execução específica
gh run view <run-id>
 
# Re-executar jobs que falharam
gh run rerun <run-id>

Proteção de Branch

Configuração


# Executar script de setup
node scripts/setup-branch-protection.js
 
# Ver proteção atual
node scripts/setup-branch-protection.js --status

Requisitos

GitHub CLI (gh) instalado
Autenticado no GitHub
Acesso de admin ao repositório

Regras de Proteção

Proteção do Branch Master:

Checks de Status Obrigatórios:
- ESLint
- TypeScript Type Checking
- Jest Tests
- Story Checkbox Validation
Revisões de Pull Request:
- 1 aprovação obrigatória
- Descarta revisões obsoletas em novos commits
Regras Adicionais:
- Histórico linear obrigatório (apenas rebase)
- Force pushes bloqueados
- Exclusão de branch bloqueada
- Regras se aplicam a administradores

Configuração Manual

Via GitHub CLI:


# Definir checks de status obrigatórios
gh api repos/OWNER/REPO/branches/master/protection/required_status_checks \
  -X PUT \
  -f strict=true \
  -f contexts[]="ESLint" \
  -f contexts[]="TypeScript Type Checking"
 
# Exigir revisões de PR
gh api repos/OWNER/REPO/branches/master/protection/required_pull_request_reviews \
  -X PUT \
  -f required_approving_review_count=1
 
# Bloquear force pushes
gh api repos/OWNER/REPO/branches/master/protection/allow_force_pushes \
  -X DELETE

Workflow Diário

Iniciando uma Nova Feature


# 1. Atualizar master
git checkout master
git pull origin master
 
# 2. Criar branch de feature
git checkout -b feature/my-feature
 
# 3. Fazer alterações
# ... editar arquivos ...
 
# 4. Commit (aciona pre-commit)
git add .
git commit -m "feat: add my feature [Story X.X]"
 
# 5. Push (aciona pre-push)
git push origin feature/my-feature
 
# 6. Criar PR
gh pr create --title "feat: Add my feature" --body "Descrição"

Atualizando uma Story


# 1. Abrir arquivo da story
code docs/stories/X.X-story.yaml
 
# 2. Marcar tarefas como completas
# Mudar: - "[ ] Tarefa"
# Para:  - "[x] Tarefa"
 
# 3. Atualizar status se necessário
# Mudar: status: "in progress"
# Para:  status: "Ready for Review"
 
# 4. Commit das atualizações da story
git add docs/stories/X.X-story.yaml
git commit -m "docs: update story X.X progress"
 
# 5. Push (valida story)
git push

Corrigindo Falhas de Validação

Erros de ESLint:


# Auto-corrigir problemas
npm run lint -- --fix
 
# Verificar problemas restantes
npm run lint
 
# Commit das correções
git add .
git commit -m "style: fix lint issues"

Erros de TypeScript:


# Ver todos os erros
npm run typecheck
 
# Corrigir erros no código
# ... editar arquivos ...
 
# Verificar correção
npm run typecheck
 
# Commit das correções
git add .
git commit -m "fix: resolve type errors"

Erros de Validação de Stories:


# Verificar stories
node .aios-core/utils/aios-validator.js stories
 
# Corrigir arquivo da story
code docs/stories/X.X-story.yaml
 
# Verificar correção
node .aios-core/utils/aios-validator.js story docs/stories/X.X-story.yaml
 
# Commit da correção
git add docs/stories/
git commit -m "docs: fix story validation"

Falhas de Testes:


# Executar testes
npm test
 
# Executar teste específico
npm test -- path/to/test.js
 
# Corrigir testes que falharam
# ... editar arquivos de teste ...
 
# Executar com cobertura
npm run test:coverage
 
# Commit das correções
git add .
git commit -m "test: fix failing tests"

Fazendo Merge de um Pull Request


# 1. Garantir que CI passou
gh pr checks
 
# 2. Obter aprovação
# (Aguardar revisão de membro do time)
 
# 3. Merge (squash)
gh pr merge --squash --delete-branch
 
# 4. Atualizar master local
git checkout master
git pull origin master

Solução de Problemas

Hook Não Está Executando

Sintomas: Commit funciona sem validação

Soluções:

Verificar instalação do Husky:


npm run prepare

Verificar se arquivos de hook existem:


ls -la .husky/pre-commit
ls -la .husky/pre-push

Verificar permissões de arquivo (Unix):


chmod +x .husky/pre-commit
chmod +x .husky/pre-push

Hook Pre-commit Lento

Sintomas: Pre-commit leva >10 segundos

Soluções:

Limpar caches:


rm .eslintcache .tsbuildinfo
git commit  # Reconstrói cache

Verificar mudanças de arquivos:


git status
# Commit de menos arquivos por vez

Atualizar dependências:


npm update

Validação de Story Falha

Sintoma: Pre-push falha com erros de story

Problemas Comuns:

Incompatibilidade de checkbox:


# Erro: Status completed mas tarefas incompletas
status: 'completed'
tasks:
  - '[x] Task 1'
  - '[ ] Task 2' # ← Corrigir isto
 
 
# Solução: Completar todas as tarefas ou mudar status

Seções ausentes:


# Erro: Seções obrigatórias ausentes
id: '1.1'
title: 'Story'
# Faltando: description, acceptance_criteria, status
 
# Solução: Adicionar seções faltantes

YAML inválido:


# Erro: Sintaxe YAML inválida
tasks:
  - "[ ] Task 1
  - "[ ] Task 2"  # ← Aspas de fechamento faltando acima
 
# Solução: Corrigir sintaxe YAML

CI Falha mas Local Passa

Sintomas: CI falha mas todas as validações locais passam

Causas Comuns:

Diferenças de cache:


# Limpar caches locais
rm -rf node_modules .eslintcache .tsbuildinfo coverage/
npm ci
npm test

Diferenças de ambiente:


# Usar mesma versão de Node que o CI (18)
nvm use 18
npm test

Arquivos não commitados:


# Verificar mudanças não commitadas
git status
 
# Stash se necessário
git stash

Proteção de Branch Bloqueia Merge

Sintomas: Não consegue fazer merge do PR mesmo com aprovações

Verificar:

Checks obrigatórios passaram:


gh pr checks
# Todos devem mostrar ✓

Aprovações obrigatórias:


gh pr view
# Verificar seção "Reviewers"

Branch está atualizado:


# Atualizar branch
git checkout feature-branch
git rebase master
git push --force-with-lease

Dicas de Performance

Gerenciamento de Cache

Manter caches:

.eslintcache - Resultados do ESLint
.tsbuildinfo - Info de build do TypeScript
coverage/ - Dados de cobertura de testes

Adicionar ao .gitignore:


.eslintcache
.tsbuildinfo
coverage/

Desenvolvimento Incremental

Melhores Práticas:

Commits pequenos:
- Menos arquivos = validação mais rápida
- Mais fácil de debugar falhas
Testar durante desenvolvimento:


# Executar validação manualmente antes do commit
npm run lint
npm run typecheck
npm test

Corrigir problemas imediatamente:
- Não deixe problemas acumularem
- Mais fácil de corrigir no contexto

Otimização do CI

Otimizações do workflow:

Jobs paralelos - Todas as validações executam em paralelo
Timeouts de jobs - Falha rápida em travamentos
Cache - Dependências npm em cache
Jobs condicionais - Job de performance apenas em PRs

Performance de Validação de Stories

Performance Atual:

Story única: <100ms
Todas as stories: <2s (típico)

Dicas de otimização:

Mantenha stories focadas - Uma feature por story
Limite contagem de tarefas - Quebre stories grandes em menores
YAML válido - Erros de parsing atrasam validação

Tópicos Avançados

Pulando Validações

Quando apropriado:

Hotfixes de emergência
Mudanças apenas de documentação
Mudanças de configuração do CI

Como pular:


# Pular pre-commit
git commit --no-verify
 
# Pular pre-push
git push --no-verify
 
# Pular CI (não recomendado)
# Adicione [skip ci] na mensagem de commit
git commit -m "docs: update [skip ci]"

Aviso: Pule apenas quando absolutamente necessário. Validações puladas não detectam problemas.

Validação Customizada

Adicionar validadores customizados:

Criar função de validação:


// .aios-core/utils/custom-validator.js
module.exports = async function validateCustom() {
  // Sua lógica de validação
  return { success: true, errors: [] };
};

Adicionar ao hook:


# .husky/pre-commit
node .aios-core/utils/aios-validator.js pre-commit
node .aios-core/utils/custom-validator.js

Adicionar ao CI:


# .github/workflows/ci.yml
- name: Custom validation
  run: node .aios-core/utils/custom-validator.js

Suporte a Monorepo

Para monorepos:

Escopar validações:


// Validar apenas pacotes alterados
const changedFiles = execSync('git diff --name-only HEAD~1').toString();
const packages = getAffectedPackages(changedFiles);

Validação paralela de pacotes:


strategy:
  matrix:
    package: [package-a, package-b, package-c]

Referências

AIOS Validator: .aios-core/utils/aios-validator.js
CI Workflow: .github/workflows/ci.yml

Dúvidas? Problemas?