Guia de Workflow Git do AIOX

🌐 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 AIOX 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 .aiox-core/utils/aiox-validator.js pre-push
node .aiox-core/utils/aiox-validator.js stories

# Validar story única
node .aiox-core/utils/aiox-validator.js story docs/stories/1.1-story.yaml

# Pular hook (NÃO recomendado)
git push --no-verify

Validador de Stories

Localização: .aiox-core/utils/aiox-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 .aiox-core/utils/aiox-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 .aiox-core/utils/aiox-validator.js stories

# Corrigir arquivo da story
code docs/stories/X.X-story.yaml

# Verificar correção
node .aiox-core/utils/aiox-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:

// .aiox-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 .aiox-core/utils/aiox-validator.js pre-commit
node .aiox-core/utils/custom-validator.js

Adicionar ao CI:

# .github/workflows/ci.yml
- name: Custom validation
  run: node .aiox-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

AIOX Validator: .aiox-core/utils/aiox-validator.js
CI Workflow: .github/workflows/ci.yml

Dúvidas? Problemas?

FilesExpand file tree

git-workflow-guide.md

Latest commit

History

git-workflow-guide.md

File metadata and controls

Guia de Workflow Git do AIOX

Índice

Visão Geral

Por Que Três Camadas?

Diagrama de Arquitetura

Arquitetura de Defesa em Profundidade

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

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

Camada 3: CI/CD (Cloud - Autoritativo)

Camada 1: Validação Pre-commit

Referência Rápida

Configuração do ESLint

Configuração do TypeScript

Otimização de Performance

Camada 2: Validação Pre-push

Referência Rápida

Validador de Stories

Regras de Validação

1. Formato de Checkbox

2. Consistência de Status

3. Seções Obrigatórias

4. Registro do Dev Agent

Mensagens de Erro

Camada 3: Pipeline CI/CD

Estrutura do Workflow

Detalhes dos Jobs

Job ESLint

Job TypeScript

Job de Testes

Job de Validação de Stories

Job de Resumo de Validação

Gatilhos do CI

Visualizando Resultados do CI

Proteção de Branch

Configuração

Requisitos

Regras de Proteção

Configuração Manual

Workflow Diário

Iniciando uma Nova Feature

Atualizando uma Story

Corrigindo Falhas de Validação

Fazendo Merge de um Pull Request

Solução de Problemas

Hook Não Está Executando

Hook Pre-commit Lento

Validação de Story Falha

CI Falha mas Local Passa

Proteção de Branch Bloqueia Merge

Dicas de Performance

Gerenciamento de Cache

Desenvolvimento Incremental

Otimização do CI

Performance de Validação de Stories

Tópicos Avançados

Pulando Validações

Validação Customizada

Suporte a Monorepo

Referências