bi-descomplicar/ESTRUTURA.md

layer, type, tags, title, description, timestamp

layer	type	tags	title	description	timestamp
wiki	Document	projecto modelo organizacao estrutura	Estrutura	Este documento define a estrutura de pastas e ficheiros obrigatória para todos os projectos do ecossistema Descomplicar®…	2026-05-13T11:27:31.572569+00:00

ESTRUTURA.md — Standard de Hierarquia de Projectos

Introdução

Este documento define a estrutura de pastas e ficheiros obrigatória para todos os projectos do ecossistema Descomplicar®. A consistência da estrutura permite que agentes de IA e programadores transitem entre projectos com atrito zero.

Hierarquia Base (Root)

/ (root)
├── docs/               # Documentação específica do projecto
│   ├── PLANS/          # Planos de acção e roadmaps específicos
│   └── SPECS/          # Especificações técnicas e requisitos do projecto
├── scripts/            # Scripts de automação local (opcional)
├── tests/              # Testes globais ou de integração
├── index.md            # Navegação OKF — links only, minúsculas (Obsidian + Wayland)
├── AGENTS.md           # Contexto para agentes IA — 5W2H + relacionamentos (Wayland, Hermes, Claude, OpenCode)
├── CLAUDE.md           # Instruções específicas para Claude Code
├── GEMINI.md           # Instruções específicas para Gemini CLI
├── STATUS.md           # Estado actual — PDCA (Plan/Do/Check/Act)
├── CHANGELOG.md        # Histórico de versões e decisões
├── MEMORY.md           # Factos duráveis, decisões, workarounds (append-only)
├── README.md           # Visão geral humana — o que é, porquê existe
├── desk.project        # Ligação ao Desk CRM (JSON)
└── ...                 # Ficheiros de código (src, backend, frontend, etc.)

Nota: PROCs e RUNBOOKs NÃO residem aqui. Consultar 06-Operacoes/Procedimentos/ e 06-Operacoes/Runbooks/ no Hub — são a fonte de verdade centralizada.

Definição de Directórios e Ficheiros Críticos

1. /docs

Documentação que vive e morre com o projecto.

• PLANS/: Documentos que descrevem "o que vamos fazer" neste projecto (ex: PLANS/PLAN-MIGRACAO-DB.md).
• SPECS/: Definições técnicas, diagramas de arquitectura e contratos de API específicos.

2. Documentação Centralizada (Externo ao Projecto)

Os procedimentos operacionais e manuais de manutenção não residem na pasta do projecto para evitar duplicação e garantir que todos seguem a versão mais recente (Single Source of Truth).

• PROCs no Hub em 06-Operacoes/Procedimentos/
• Runbooks no Hub em 06-Operacoes/Runbooks/
• Quick References no Hub em 06-Operacoes/Documentacao/Quick-Reference/

Nunca criar pastas docs/PROC ou docs/RUNBOOK num projecto. A referência correcta é sempre o Hub.

---

3. Ficheiros de Governance de IA (AGENTS.md, GEMINI.md, CLAUDE.md)

Servem para alinhar o comportamento dos agentes neste repositório. Devem conter regras de estilo, convenções de código e restrições de segurança específicas do projecto. Pelo menos AGENTS.md é obrigatório.

4. MEMORY.md

Obrigatório. Deve ser actualizado no final de cada sessão.

• Formato: Secções por data (ordem cronológica inversa).
• Conteúdo: O que foi feito, problemas encontrados e o que ficou pendente.

4. desk.project

Ficheiro JSON que mapeia o repositório local à tarefa ou projecto correspondente no Desk CRM.

Regras de Nomenclatura

• Pastas: UPPERCASE para categorias de documentação (PLANS, SPECS), lowercase para código.
• Ficheiros: kebab-case.md (letras minúsculas e hífens).
• Excepções: Ficheiros de sistema como README.md, CHANGELOG.md ou ficheiros de governance em UPPERCASE.

Validação de Estrutura

Um projecto é considerado "em conformidade" se contiver, no mínimo:

1. docs/ com as pastas PLANS/ e SPECS/ (mesmo que vazias).
2. AGENTS.md com directrizes específicas do projecto.
3. MEMORY.md com registo de sessões.
4. desk.project com task_id válido no Desk CRM.

Validação automática: Executar scripts/validate-structure.sh na raiz do projecto para verificar conformidade.

---

Convenção para Pastas Hub (Sistemas e Aplicações)

Para pastas de documentação no Hub (04-Stack/02.04-Sistemas/, 04-Stack/02.05-Aplicações/, etc.) aplica-se uma convenção própria:

→ Ver 06-Operacoes/Procedimentos/Cross-Departamental/PROC-Estrutura-Pasta-Projecto.md (XDP-PRJ-001)

Diferença principal: pastas Hub não têm docs/, scripts/ nem tests/ — são documentação pura. O AGENTS.md contém o 5W2H do sistema e os relacionamentos com o ecossistema.