--- layer: wiki type: Document tags: [projecto, modelo, organizacao, proc] title: 2026 05 16 Proc Dev Standard Design description: >- Design do PROC-DEV-STANDARD (D7-SIS-006) — standard de procedimentos de desenvolvimento, aprovado 2026-05-16. timestamp: 2026-05-16T16:40:14.554151+00:00 --- # 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) 1. **Início** → ler `MEMORY.md` + `STATUS.md` + `.desk-project` 2. **Durante** → registar decisões relevantes em `MEMORY.md` em tempo real 3. **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 1. Identificar domínio da ideia 2. 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 3. Executar deep research: WebSearch + WebFetch + NLM 4. Sintetizar: decisões técnicas, alternativas avaliadas, alternativas descartadas e porquê, riscos identificados 5. 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] ``` 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) 1. **Bug descoberto** → criar issue Gitea (Issue-First Gate) → comentar na task Desk com URL da issue Gitea 2. **Feature concluída** → fechar issue Gitea com `Closes #N` no commit → actualizar task Desk para "concluído" + registar tempo 3. **PR merged** → `CHANGELOG.md` actualizado → `STATUS.md` actualizado 4. **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:** 1. Descoberta → criar issue com labels: `Bug` + severidade (`P: Critical/High/Medium/Low`) + área 2. Branch `fix/N-descricao-curta` 3. Commits com `(#N)` + `Fixes #N` no commit que fecha 4. **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