90 lines
4.6 KiB
Markdown
90 lines
4.6 KiB
Markdown
---
|
|
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.
|