ealmeida/bi-descomplicar

Fork 0

Files

T

ealmeida 75041136d2 chore: ignora graphify-out gerado

2026-10-28 15:59:30 +00:00

12 KiB

Raw Permalink Blame History

layer, type, tags, title, description, timestamp

layer

type

Design — PROC-DEV-STANDARD (D7-SIS-006)

Data: 2026-05-16 Status: Aprovado Autor: Emanuel Almeida + Claude Code Baseado em: WhatSMS v2 (/media/ealmeida/Dados/Dev/WhatSMS/whatsms-v2)

Objectivo

Criar o PROC-DEV-STANDARD — protocolo de desenvolvimento de ciclo completo (ideia → produção) para todos os projectos Descomplicar®. Agnóstico de stack. Garante que qualquer agente (Claude, Gemini, Hermes, OpenCode, Antigravity) compreende o estado do projecto, nunca perde contexto e partilha toda a informação disponível.

Localização

Fonte de verdade: Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md (código D7-SIS-006)
Resumo/referência: Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md

Estrutura do Documento

1. Princípios
2. Fluxo Completo (visão geral)
3. Estrutura de Projecto Obrigatória
4. Ficheiros de Contexto Cross-Agent
5. Fase 1 — Ideia
6. Fase 2 — Pesquisa (deep research + NLM)
7. Fase 3 — Spec
8. Fase 4 — Plan
9. Fase 5 — Desenvolvimento (branch + commits)
10. Fase 6 — Quality Gates
11. Fase 7 — Code Review & PR
12. Fase 8 — Deploy & Validação
13. Gestão de Ferramentas: Gitea vs Desk CRM
14. Gates Obrigatórios (Issue-First, Deploy Guard)
15. Excepções (hotfix, re-deploy)
16. Referências

Fluxo Completo

Ideia
  → Pesquisa (deep research + NLM existente ou novo se domínio novo)
  → Spec (SPEC.md aprovado)
  → Plan (implementação detalhada)
  → Desenvolvimento (feat/* → commits atómicos)
  → Quality Gates (pre-commit → pre-push → CI)
  → Code Review & PR (Gitea)
  → Deploy & Validação (PROC-DEPLOY-STANDARD)

Excepções ao pipeline completo: bugfix, operação unitária, continuação de plano existente.

Estrutura de Projecto Obrigatória

/ (root)
├── docs/
│   ├── PLANS/          # Planos de acção e roadmaps
│   └── SPECS/          # Specs técnicas + notas de pesquisa
├── scripts/            # Automação local (opcional)
├── AGENTS.md           # Directrizes por agente (obrigatório)
├── CHANGELOG.md        # Histórico de versões
├── CLAUDE.md           # Instruções Claude Code (se aplicável)
├── MEMORY.md           # Contexto cross-agent (obrigatório)
├── STATUS.md           # Estado vivo do projecto (obrigatório)
└── .desk-project       # Ligação Desk CRM (JSON, obrigatório)

Validação automática: scripts/validate-structure.sh (já existente no modelo).

Ficheiros de Contexto Cross-Agent

MEMORY.md

Partilhado entre Claude, Gemini, Hermes, OpenCode, Antigravity e outros
Formato: secções por data, ordem cronológica inversa
Conteúdo: decisões, paths, IDs, workarounds, factos de sessão
Não usar projects/*/memory/*.md do Claude Code — usar sempre MEMORY.md local

STATUS.md

Estado instantâneo do projecto — actualizado no início e fim de cada sessão
Conteúdo: sprint actual, versão, bloqueios, próximos passos, agente activo

Formato sugerido:

# STATUS.md — [Nome Projecto]
**Versão:** vX.Y.Z | **Sprint:** #N | **Data:** YYYY-MM-DD
**Agente activo:** [nome] | **Sessão iniciada:** HH:MM

## Estado
- Em curso: [o que está a ser feito]
- Bloqueios: [impedimentos activos]
- Próximos passos: [próxima acção concreta]

AGENTS.md

Directrizes específicas do projecto para cada família de agentes
Conteúdo: o que cada agente pode/não pode fazer, ferramentas disponíveis, restrições
Actualizado pelo owner quando as regras mudam

CHANGELOG.md

Histórico de versões com data, sprint e impacto
Actualizado pelo agente activo a cada versão/sprint concluído
Formato: Conventional Changelog (## vX.Y.Z — YYYY-MM-DD)

Protocolo de sessão (qualquer agente)

Início → ler MEMORY.md + STATUS.md + .desk-project
Durante → registar decisões relevantes em MEMORY.md em tempo real
Fim → actualizar STATUS.md + MEMORY.md com factos novos

Fase 1 — Ideia

Entrada: ideia ou pedido de funcionalidade Saída: decisão de avançar ou descartar + âmbito inicial definido

Verificar antes de avançar:

Não existe já funcionalidade equivalente no projecto
Alinhado com o MASTER-PLAN / objectivos do projecto
Âmbito claro o suficiente para pesquisar

Fase 2 — Pesquisa

Entrada: ideia com âmbito definido Saída: nota de pesquisa em docs/SPECS/research-YYYY-MM-DD-tema.md

Processo

Identificar domínio da ideia
Verificar NLMs existentes via /knowledge (65 notebooks inventariados)
- Se domínio coberto → usar NLM existente (adicionar fontes se necessário)
- Se domínio novo e pesquisa extensa → criar NLM dedicado ao projecto
- Criar NLM apenas se estritamente necessário
Executar deep research: WebSearch + WebFetch + NLM
Sintetizar: decisões técnicas, alternativas avaliadas, alternativas descartadas e porquê, riscos identificados
Guardar nota de pesquisa em docs/SPECS/

Output mínimo da nota de pesquisa

Pergunta de investigação
Fontes consultadas
Conclusões (o que fazer e porquê)
Alternativas descartadas (com justificação)
Riscos e mitigações

Fase 3 — Spec

Entrada: nota de pesquisa aprovada Saída: SPEC.md ou ficheiro em docs/SPECS/ aprovado pelo owner

Seguir skill /brainstorm → /spec para trabalho não-trivial (>3 ficheiros ou sistema novo)
Excepções: bugfix, operação unitária, continuação de plano existente
A spec é o contrato bilateral — nada entra em código sem spec aprovada

Fase 4 — Plan

Entrada: spec aprovada Saída: plano de implementação em docs/PLANS/

Seguir skill /writing-plans para decompor em tarefas executáveis
Cada tarefa com critério de aceitação claro
Registar plano em docs/PLANS/PLAN-YYYY-MM-DD-tema.md

Fase 5 — Desenvolvimento

Entrada: plano aprovado Saída: commits atómicos em branch dedicada

Branch strategy

main — produção (protegida)
dev — desenvolvimento (se aplicável)
feat/N-descricao — novas funcionalidades
fix/N-descricao — correções de bugs (N = número da issue Gitea)

Commits

Formato Conventional Commits com referência à issue:

tipo(scope): descrição breve (#N)

Corpo opcional com contexto adicional.

Closes #N
Co-Authored-By: [Agente] <noreply@anthropic.com>

Tipos válidos: feat, fix, refactor, test, docs, chore

Regras:

Um commit = uma alteração lógica
#N obrigatório (ref à issue Gitea)
Pre-commit hooks automáticos: formatação + lint (apenas staged)

Fase 6 — Quality Gates

Entrada: código desenvolvido Saída: código validado pronto para PR

Gate	Momento	Responsável	O que verifica
Pre-commit	Automático	Hook	Formatação, lint
Pre-push	Manual	Agente	Build, testes, cobertura, auditoria segurança
CI	Automático (push)	Gitea Actions	Tudo + report cobertura

Thresholds de cobertura e comandos concretos definidos por projecto no CONTRIBUTING.md do projecto — não no PROC genérico.

Regra: nunca fazer push sobre CI vermelho. Nunca fazer PR sem quality gates verdes.

Fase 7 — Code Review & PR

Entrada: branch com CI verde Saída: PR aprovado e merged para main

Checklist PR

Branch actualizada com main
Todos os testes passam localmente
Cobertura acima do threshold do projecto
Build sem erros
Auditoria de segurança sem vulnerabilidades críticas/altas
CHANGELOG.md actualizado
Documentação actualizada (se aplicável)
STATUS.md reflecte o novo estado

Reviewers verificam

Código segue convenções do projecto (CLAUDE.md / AGENTS.md)
Testes cobrem casos críticos
Sem código duplicado
Sem secrets hardcoded, inputs validados
MEMORY.md actualizado com decisões relevantes

Fase 8 — Deploy & Validação

Entrada: PR merged para main Saída: versão em produção validada

Seguir PROC-DEPLOY-STANDARD.md (D7-SIS-005) na íntegra.

Após deploy:

Actualizar STATUS.md com versão deployada
Registar em MEMORY.md: versão, data, o que foi deployado
Fechar task Desk CRM correspondente + registar tempo

Gestão de Ferramentas: Gitea vs Desk CRM

Divisão de responsabilidades

O quê	Onde	Nunca em
Bugs, issues técnicas, PRs, releases	Gitea	Desk CRM
Projectos, sprints, tempo, facturação	Desk CRM	Gitea
Código, commits, CI/CD	Gitea	—
Cliente 360, propostas, pagamentos	Desk CRM	—

Regra geral: Gitea = tracker técnico. Desk CRM = gestão de projecto e facturação.

Sincronização manual (regras)

Bug descoberto → criar issue Gitea (Issue-First Gate) → comentar na task Desk com URL da issue Gitea
Feature concluída → fechar issue Gitea com Closes #N no commit → actualizar task Desk para "concluído" + registar tempo
PR merged → CHANGELOG.md actualizado → STATUS.md actualizado
Deploy prod → task Desk fechada → MEMORY.md regista versão deployada

Referências cruzadas obrigatórias

.desk-project contém: task_id Desk + gitea_repo + gitea_project_id
MEMORY.md regista IDs relevantes de ambos os sistemas
Commits referenciam (#N) da issue Gitea
Comentários Desk referenciam URL completa da issue/PR Gitea

Gate Obrigatório — Issue-First (Bugs)

Regra não-negociável: todo o bug passa por issue Gitea antes de qualquer commit de fix.

Fluxo:

Descoberta → criar issue com labels: Bug + severidade (P: Critical/High/Medium/Low) + área
Branch fix/N-descricao-curta
Commits com (#N) + Fixes #N no commit que fecha
Excepção hotfix: fix cirúrgico urgente em prod → criar issue post-hoc com label Backfill, fechada à criação, com link ao commit

Gate Obrigatório — Deploy Guard

Ver PROC-DEPLOY-STANDARD.md (D7-SIS-005) — secção "Deploy Guard".

Regra: CI tem de estar verde no último commit de main antes de qualquer deploy. Se abortar, não fazer override — investigar, corrigir, empurrar, esperar verde.

Excepções Documentadas

Situação	Excepção permitida	Condições
Bug crítico em prod	Hotfix sem PR (push directo main)	Fix trivial e reversível; issue criada post-hoc
Re-deploy sem código novo	workflow_dispatch	Após mudança de env vars
Bugfix simples	Sem spec/plan	Apenas 1-2 ficheiros, causa raiz clara
Continuação de plano	Sem nova spec	Plano existente aprovado, âmbito inalterado

Referências

PROC-DEPLOY-STANDARD.md — D7-SIS-005 (deploy para produção)
ESTRUTURA.md — hierarquia de projecto standard
GOVERNANCA.md — manifesto de qualidade
PROTOCOLO-CRM.md — integração Lean Gitea ↔ Desk CRM
scripts/validate-structure.sh — validação automática de estrutura
WhatSMS v2 CONTRIBUTING.md — implementação de referência

Criado: 2026-05-16 | Aprovado por: Emanuel Almeida | Próximo passo: writing-plans

12 KiB Raw Permalink Blame History