---
layer: wiki
type: Document
tags: [projecto, modelo, organizacao, estrutura]
title: Estrutura
description: >-
  Este documento define a estrutura de pastas e ficheiros obrigatória para todos os projectos do ecossistema Descomplicar®…
timestamp: 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)

```text
/ (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.