348 lines
12 KiB
Markdown
348 lines
12 KiB
Markdown
---
|
|
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] <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)
|
|
|
|
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
|