Pular para conteúdo

Execucao de Tasks e Fluxo no Project

1. Objetivo

Este documento define como tasks de implementacao devem ser executadas e acompanhadas.

Ele existe para garantir:

  • visibilidade central de execucao
  • rastreabilidade entre backlog, issue, branch, PR e entrega
  • padrao operacional simples para humanos e agentes
  • isolamento seguro do desenvolvimento em forks

2. Regra principal

Toda task de implementacao deve ser atacada com apoio de agente.

Isso significa que o fluxo esperado e:

  1. a task nasce como issue no repositorio canonico
  2. a issue entra no Project centralizador
  3. a issue e atribuida a um desenvolvedor responsavel
  4. o agente prepara o ambiente de execucao no fork do desenvolvedor
  5. o desenvolvimento ocorre em branch isolada no fork
  6. a PR volta do fork para o repositorio canonico
  7. o Project reflete automaticamente o andamento da task

3. Conceitos operacionais

3.1 Repositorio canonico

Repositorio canonico e o repositorio oficial da organizacao onde:

  • a issue nasce
  • a PR deve ser aberta
  • a branch de integracao oficial existe
  • o historico oficial do componente e preservado

3.2 Fork de execucao

Fork de execucao e a copia individual do repositorio usada pelo desenvolvedor e pelo agente para:

  • isolar commits
  • reduzir risco de interferencia entre tarefas
  • permitir reescrita controlada da branch de trabalho

3.3 Branch de task

Cada task deve usar uma branch especifica e descartavel, criada no fork a partir da branch oficial de integracao do repositorio canonico.

Padrao recomendado:

  • feat/<issue-id>-<slug>
  • fix/<issue-id>-<slug>
  • chore/<issue-id>-<slug>
  • spike/<issue-id>-<slug>
  • docs/<issue-id>-<slug>

4. Onde o backlog e construido

O backlog executavel nao nasce durante a codificacao.

Ele deve ser construido no planejamento de implementacao, a partir do handoff da inception e registrado em plan/.

Esse planejamento deve produzir:

  • epicos
  • user stories
  • tasks tecnicas
  • spikes
  • docs
  • relacao com repositorios canonicos
  • criterio de pronto

5. Fluxo padrao de execucao

flowchart LR
    A[Backlog planejado em plan/] --> B[Issue criada no repositorio canonico]
    B --> C[Item adicionado ao Project central]
    C --> D[Issue atribuida ao dev]
    D --> E[Agent prepara fork e branch da task]
    E --> F[Implementacao e testes no fork]
    F --> G[PR do fork para o repositorio canonico]
    G --> H[Revisao]
    H --> I[Fechamento manual da issue]

6. Estados do Project

O Project central deve usar pelo menos estes estados:

  • Backlog
  • Ready
  • In Progress
  • In Review
  • Blocked
  • Done

7. Automacao esperada

O comportamento esperado do Project e:

  • issue atribuida a um desenvolvedor -> In Progress
  • PR aberta vinculada a issue -> In Review
  • issue fechada manualmente pelo desenvolvedor ou responsavel -> Done

Observacoes:

  • o fechamento da issue nao deve depender apenas de automacao por keyword em PR
  • o fechamento e manual para garantir revisao final de contexto, evidencias e pendencias
  • Blocked deve ser definido explicitamente quando houver impedimento relevante

8. Papel do agente

O agente deve atuar como executor assistido da task, e nao como dono informal do backlog.

Para cada task, o comportamento esperado e:

  1. ler a issue do repositorio canonico
  2. validar contexto no SOT e nos artefatos de planejamento
  3. preparar fork e branch da task
  4. implementar com commits isolados no fork
  5. executar validacoes tecnicas
  6. atualizar evidencias necessarias
  7. preparar PR para o repositorio canonico

9. Papel do desenvolvedor

O desenvolvedor continua sendo o responsavel operacional pela entrega.

Cabe ao desenvolvedor:

  • receber o assign da issue
  • supervisionar o trabalho do agente
  • validar resultado e evidencias
  • abrir ou concluir a PR para o repositorio canonico
  • fechar manualmente a issue quando a entrega estiver realmente concluida

10. Criterio minimo de qualidade

Antes da PR, a task deve buscar o seguinte padrao:

  • testes unitarios com cobertura maior que 85%, quando tecnicamente aplicavel ao componente
  • testes de integracao, quando houver integracoes relevantes
  • testes end-to-end, quando houver fluxo ponta a ponta viavel e custo justificavel
  • evidencias de execucao registradas no repositorio ou na PR

Quando algum destes itens nao for viavel, a PR deve explicar:

  • o motivo
  • o risco residual
  • a compensacao adotada

11. Rastreabilidade obrigatoria

Toda task deve manter a seguinte cadeia:

Backlog em plan/ -> Issue no repositorio canonico -> Branch no fork -> PR -> evidencias -> fechamento manual

Nao e aceitavel:

  • desenvolver sem issue
  • abrir PR sem task rastreavel
  • deixar task em execucao fora do Project
  • misturar multiplas tasks na mesma branch

12. Regra de simplicidade

Se houver duvida operacional, priorizar:

  • uma issue por entrega controlavel
  • uma branch por issue
  • um fork por desenvolvedor
  • uma PR por recorte coerente
  • um responsavel humano por task